Start with an observable outcome
A coding agent can produce a convincing screen before you have decided what the screen should do. Start with a small user outcome: a signed-in user edits their profile, saves it, and sees the saved name after reloading. That gives both the implementation and the review a concrete target.
Include the current behavior, the desired behavior, and the important failure cases in the brief. Name the existing module that owns the work. A request to add profile editing should point to the authentication layer, rather than leave the agent to invent a second user store. Keep credentials out of prompts and screenshots — a pasted apps/web/.env.local or session cookie becomes part of the conversation record.
A workable brief reads like this: “In the account screen, let a signed-in user edit their display name and see it after reload. The auth module owns the user record; do not add a table. An empty name, or a request that names another user's record, must be rejected. Prove it with pnpm test and one manual save at a narrow width.” Five sentences, and most of the guessing is gone.
- The user-visible outcome, phrased so you can check it in the running app.
- The file or module that owns the behavior today — and the areas that should stay untouched.
- At least one failure case: an unauthenticated attempt, invalid input, or a repeated request.
- The check that proves it — a test command, a fixture, or an explicit manual walkthrough.
Make the repository explain itself
Document how to run the application, which checks are deterministic, and where ownership is enforced. In supastack, AGENTS.md records the workspace boundary and .ai/ records file-level decisions. These notes are most useful when they tell the next contributor — human or agent — why an implementation exists, not just which files changed. The agent setup guide shows how the kit exposes that material, and the local setup guide is the walkthrough the agent will actually follow.
Ask the agent to read the relevant code before editing. A narrow change usually needs the interface, its server boundary, and the tests around that boundary. Loading the entire repository is less useful than understanding the few places that decide whether the new behavior is correct: the ownership check, the schema, the entitlement.
When a feature touches configuration, name the file rather than transcribing it — “add the key to apps/web/.env.local” keeps secrets on disk. The same discipline applies to provider dashboards: describe the destination, don't paste the credential.
Work in small, reviewable changes
Agents are most reliable when a change has one owner and one checkable outcome. “Add profile editing” is reviewable; “improve the account area” invites refactors nobody asked for. If a feature decomposes into a schema change, a server boundary, and a screen, run them as separate briefs that each leave the build green.
Commit or checkpoint before each agent run. A clean baseline turns a bad output into a deleted diff rather than an archaeology exercise, and it gives your review a stable before-and-after to compare.
Review one complete change at a time
Write an acceptance check before changing behavior. For profile editing, cover a valid update and an unauthorized attempt. Build the smallest implementation that satisfies those cases, then inspect the actual interaction with realistic text and a narrow viewport.
Review the diff as well as the result. Look for duplicated business logic, broad exception handling, and new dependencies that solve a problem the existing stack already handles. Run the project's checks and record what they establish. A browser fixture can verify a form interaction; it cannot establish that the production database or an external provider is configured correctly.
Each command answers a different question. pnpm test exercises behavior against deterministic fake and local adapters, pnpm check covers lint, typechecking, and formatting, and pnpm build surfaces the integration errors that only appear at bundle time. Together they are a floor for review — the launch checklist covers what still has to be proven in the real environment.
pnpm test
pnpm check
pnpm buildWhen the agent gets it wrong
When a result is wrong, resist stacking follow-up prompts onto a bad diff. Revert to the checkpoint, tighten the brief around whatever was misunderstood — usually an unstated constraint or a missing owner — and run again. Each retry should carry new information, not just new urgency.
Persistent failure usually means the brief assumes context the repository does not contain. If the agent keeps inventing a second place to store users, the fix is a sentence in AGENTS.md about where identity lives, not a firmer tone. Update the document, then retry the task — the agents guide is where the kit keeps this workflow.
Common questions about agent workflows
A few questions come up whenever a founder starts trusting a coding agent with real product work.
- Can a coding agent build a whole SaaS by itself? — It can assemble the visible parts quickly, but the durable parts — authorization, billing lifecycle, data isolation — still need a brief, a check, and a review. Speed without that loop turns into rework.
- How big should a task for a coding agent be? — Small enough that you can verify the result in the running app within minutes: one user-visible outcome, one owning module, one acceptance check.
- What should never go into a prompt? — Provider secrets, session cookies, the contents of
.env.local, and customer data. Name files and let the tool read them locally instead of copying values into a chat log. - Does agent-written code change how I review? — The review shifts from typing to reading: inspect the diff for duplicated logic, broad exception handling, and dependencies that re-solve a problem the stack already handles.
- Which tests matter most for agent output? — The ones that pin ownership and failure behavior: unauthorized requests, invalid input, and repeated submissions, not only the happy path the demo shows.