Ir para o conteúdo

Onboarding Guide: NS Flow Kit for New Squad Members

File: docs/onboarding/squad-member-guide.md
Audience: Developers joining a squad that uses the AI-Ready Legacy Engineering Template

Welcome to Agent-Driven Engineering

If you've worked in traditional engineering teams, your mental model is probably:

"Ticket arrives → I investigate → I write the fix → I test → I open a PR"

In this team, your model is:

"Ticket arrives → I start the agent pipeline → Agents investigate, fix, and test → I validate and approve → Agents create the PR and coordinate release"

This is not about removing developers from the process. It's about redirecting developer expertise from repetitive execution to high-value judgment.

What You Actually Do

Your Role What It Means
Context Provider Make sure tickets have enough information for agents to work. If the agent flags INCOMPLETE_TICKET, you fill the gap.
Quality Validator Read the BugReport, ImpactReport, PatchBundle, and CodeReviewReport with expert eyes. Agents can be confidently wrong. Your domain knowledge is the check.
Decision Maker At each of the 4 human checkpoints, you make a real decision — not a rubber stamp. "Does this look right?" should require 5 real minutes, not 5 seconds.
Knowledge Curator Review learning-agent outputs after each ticket. Is Speckit being updated accurately? Add context the agent missed.

Your First Week

Day 1–2: Read the Foundation

  1. Read this entire README.md
  2. Read .claude/context/operating-context.md
  3. Browse .speckit/domain/system-overview.md — learn the systems you'll work with
  4. Browse .speckit/known-issues/ — the most common problems you'll encounter

Day 3–4: Observe a Ticket

  1. Pair with a senior team member on a P3 or P4 ticket
  2. Watch the full pipeline run: /analyze-bug → /generate-fix → /run-regression → /open-pr
  3. At each checkpoint, discuss: "Why did the agent produce this? Is it correct? What would you change?"

Day 5: Run Your First Ticket Solo

  1. Pick a P4 ticket assigned to you
  2. Run /analyze-bug ADO-{id} — read the output carefully
  3. If the analysis looks correct, proceed. If not, ask a senior why and what context was missing.
  4. Follow the full flow through to PR creation
  5. Debrief with your tech lead

The Human Checkpoints: How to Use Them Well

Checkpoint 1: Review BugReport + ImpactReport

What to look for: - Is the root cause hypothesis technically plausible? Does it match your domain knowledge? - Is the blast radius accurate? Are there systems affected that the agent missed? - Is the severity classification appropriate?

Common issues: - Agent identified the wrong system as the root cause (often happens when logs are sparse) - Agent underestimated blast radius because Speckit doesn't have the full integration map - Agent over-escalated to P1 due to keyword matching on "production" in the description

What to do: Add context to the ticket as an ADO comment, then re-run /analyze-bug with additional context in the prompt.

Checkpoint 2: Review the Patch (with the CodeReviewReport at your side)

Before this checkpoint, the code-reviewer-agent already reviewed the diff automatically and produced .ns-flow/delivery/<ticket>-code-review.md — findings by severity (Blocker → Nit) plus a verdict. Read it first: any Blocker should already have been sent back to the builder-agent; you decide on the Majors/Minors. The report sharpens your review — it does not replace it.

What to look for: - Did you read the CodeReviewReport? Blockers resolved? Majors consciously decided? - Does the code change match the confirmed root cause? - Is the change minimal? (No refactoring, no opportunistic "while I'm in here" changes) - Is the error handling correct? - Does it follow the patterns used in the rest of the file? - Are there any hardcoded values or credentials? - If it touches UI: does it follow the ux-guidance / .speckit/design-system/ — preserving the product's look while modernizing within it (no new one-off visual identity)?

This is the most important checkpoint. Agents generate correct code most of the time, but they can make mistakes in complex legacy code with unusual patterns.

Checkpoint 3: PR Review

What to look for: - PR description is accurate and complete - Rollback plan is executable (not generic) - Reviewers assigned are appropriate - Homologation sign-off is documented

Checkpoint 4: Deploy Approval

What to look for: - All pre-release gates are passed - Release window is appropriate - On-call is aware (for P1/P2) - You know what the rollback trigger criteria are

Common Questions

Q: What if the agent gets the root cause wrong? A: This happens, especially with sparse context. Add more information to the ticket (logs, additional context, your hypothesis) and re-run. You can also directly tell the agent what you think the cause is and ask it to validate.

Q: What if I disagree with the ImpactReport's blast radius? A: Add your knowledge to Speckit. The agent can only work with what Speckit knows. If an integration isn't documented, the agent doesn't know it exists.

Q: Can I just write the fix myself instead of using the agents? A: For P4 bugs where you know exactly what to do and it's a 2-line change, yes — use your judgment. But you should still document it via the standard artifacts (even brief ones) so Speckit learns from it.

Q: What happens if the pipeline gets stuck? A: Look at the last artifact produced. It will contain a specific reason why the agent stopped and what's needed to continue. Most "stucks" are: missing context, a policy triggered, or a human decision required.

Q: How do I improve the agents over time? A: Two ways. First, enrich Speckit — more known issues, better system maps, more ADRs. Second, improve prompts in .claude/prompts/ if you identify a pattern where the agent consistently gets things wrong in a specific way.

Speckit: Your Most Important Tool

Think of Speckit as the collective brain of everyone who has ever worked on these systems. It knows: - What systems exist and how they talk to each other - Which bugs have occurred before and how they were fixed - Which architectural decisions have been made and why - Which patterns are known to cause problems (anti-patterns) - The history of every incident

The more you contribute to Speckit, the better every agent works — for you and for everyone else.

After every significant ticket: - Did you learn something new about a system? Add it to .speckit/domain/. - Did you see a bug pattern you've seen before? Add it to .speckit/known-issues/. - Did you make a technical decision? Add an ADR to .speckit/decisions/. - Was the learning-agent output incomplete? Edit it.

Key Files to Bookmark

README.md                                          # This project's operating manual
.claude/context/operating-context.md               # Agent operating constraints
.speckit/domain/system-overview.md                 # System landscape
.speckit/known-issues/anti-patterns.md             # What NOT to do
.speckit/architecture/architecture-overview.md     # Architecture constraints
.claude/workflows/bug-flow.md                      # The standard bug process
.claude/workflows/critical-incident-flow.md        # P1 incident protocol
.claude/policies/policies.md                       # The rules agents and humans must follow

Questions? Open an ADO ticket with tag adlc-question or speak to your tech lead.

Voltar ao topo