AI / Workflow Guide
How to ship real software with an AI agent in the loop
Nothing here depends on which assistant you use. AI-assisted development succeeds or fails on process: whether you wrote the spec before the code, whether the repo tells the agent its own conventions, whether a test suite catches the plausible-looking wrong answer, and whether anyone actually reads the diff. This is the discipline that turns a fast typist into a shipped feature.
About 10 min read. Written August 2026 and deliberately tool-agnostic.
The loop, in the order it has to happen
Six steps. Skipping any of them is what produces the horror stories, and the two most commonly skipped are the first and the last.
| Step | What you do | What it prevents |
|---|---|---|
| 1. Spec | Write down the outcome, the constraints, and the acceptance criteria before you open a chat box. Three sentences is enough for a bug fix; a page for a feature. | The agent inventing requirements you never had, then defending them for the rest of the session. |
| 2. Plan | Ask for a plan and read it. Every serious tool has a read-only planning mode now. Reject the plan, do not edit the code. | Forty files changed before you notice it picked the wrong abstraction on file three. |
| 3. Context | Point at the specific files, the schema, and the one prior example that shows the house pattern. Do not tell it to "look around". | Burned tokens, a slower loop, and code written against a file that has been dead for a year. |
| 4. Execute in slices | One reviewable unit at a time, each ending in a commit. A slice is something you could revert without unpicking anything else. | A 2,000-line diff that is 90 percent correct and impossible to bisect. |
| 5. Verify | Tests, types, lint, and a build - run by the agent, then run again by CI on the pull request. | Code that compiles in the agent's head. Green locally is a claim; green in CI is evidence. |
| 6. Review | Read the diff yourself, with the spec beside it. Ask what it deleted, not only what it added. | Shipping a change nobody on the team can explain in six months. |
Gotcha: the loop is not slower than typing it yourself once you count review time. It is slower than not reviewing, which is what "AI made me 5x faster" usually means.
Spec first, because the agent will not ask twice
A coding agent optimizes for producing something. Given an underspecified task it will fill the gaps with the most statistically ordinary choice, commit to it, and then keep that choice consistent for the rest of the session. That consistency looks like competence and is actually the problem: by the time you notice the wrong assumption it is load-bearing in nine files.
The fix is cheap. Before the first prompt, write down four things: what the user-visible outcome is, what must not change, which existing pattern to follow, and how you will know it worked. That is your spec. Paste it into the session, or better, save it as a file in the repo and reference it - agents read files more reliably than they remember chat.
Then ask for a plan and refuse to accept the first one uncritically. Plan mode in Cursor, plan mode in Claude Code, /permissions in Codex set to read-only - all three exist because reviewing a plan costs a minute and reviewing a bad implementation costs an afternoon. The plan is also where you catch the tell-tale signs of a misread task: a new dependency you did not ask for, a file it wants to create that duplicates one you already have, a database migration for a feature that does not need one.
Teach the repo once with a rules file
Every mainstream assistant now reads a markdown file at the repo root and loads it into context automatically. Writing that file is the highest-leverage hour in AI-assisted development, because every correction you type twice belongs in it permanently.
AGENTS.md
The closest thing to a cross-tool standard. Plain markdown, no frontmatter, read by Codex, Cursor, and most of the open-source agents. Cursor also supports nested AGENTS.md files in subdirectories for area-specific instructions.
CLAUDE.md
Claude Code reads this and not AGENTS.md. If your repo already has AGENTS.md, create a CLAUDE.md whose first line is @AGENTS.md - that imports the shared file, and anything below it becomes Claude-specific. Aim for under 200 lines.
Path-scoped rules
Both ecosystems support instructions that load only for matching files: .claude/rules/*.md with a paths frontmatter field, and .cursor/rules/*.mdc with globs. Use them so backend conventions do not sit in context during frontend work.
What actually belongs in it
Not an architecture tour. The agent can read your directory tree faster than you can describe it, and a stale description is worse than none. What it cannot derive are the decisions:
- Commands. The exact build, test, lint, and typecheck invocations, including the flags your project needs.
- Conventions that differ from the default. "We use Drizzle, never raw SQL in route handlers." "Every new component gets a story." "Dates are stored UTC and formatted at the edge."
- Landmines. The generated directory nobody should edit, the migration that must not be re-run, the test that is flaky for a known reason.
- Hard prohibitions. Never commit, never push, never touch production config. Write them as rules, then back the important ones with a hook, because a rules file is context and not enforcement.
Keep it specific enough to verify. "Use 2-space indentation" beats "format code properly"; "run npm test before committing" beats "test your changes". And review it periodically - two rules that contradict each other are worse than one rule, because the agent will pick one at random and you will not know which.
Guardrails: what stops a bad change, not what discourages one
Instructions are advice. Hooks, permissions, sandboxes, and CI are enforcement. The difference matters the first time an agent decides that the fastest way to make the test pass is to delete the test.
Tests are the contract
An agent with a fast, reliable test suite is a different tool from one without. It closes its own loop: change, run, read the failure, fix, repeat - with no round trip through you. If your suite takes eleven minutes, the agent will avoid running it and you will lose the whole benefit. Invest in a fast unit tier before you invest in a better model.
Write the test first when you can. A failing test is the most precise spec you can hand an agent, and it makes "done" a machine-checkable claim instead of a judgement call.
CI is the second opinion
Everything the agent ran locally, run again on the pull request from a clean checkout: install, typecheck, lint, test, build. Agents are good at making a command pass on their machine and indifferent to whether it passes on yours - a missing dependency in the lockfile, a file that was never added to git, an environment variable that only exists in their shell.
Add the checks a human reviewer forgets: dependency audit, bundle-size budget, and a diff-size threshold that makes an unexpectedly large change require a second approval. The CI/CD pipeline guide covers the mechanics.
Permissions and sandboxes
Every serious agent separates capability from consent. Codex splits them explicitly: sandbox_mode decides whether the process can write to disk or reach the network at all, and approval_policy decides when it stops to ask. Claude Code has permission modes from plan through acceptEdits to bypassPermissions, plus allow and deny rules per tool and path.
Grant read and test freely, edit within the working directory freely, and network plus destructive shell commands never without a prompt. Blanket bypass is for throwaway sandboxes, not your main checkout.
Hooks for the rules that must hold
A hook is a shell command bound to a lifecycle event, so it runs regardless of what the model decided. Format on every write. Block edits to generated directories. Run the typechecker when the agent says it is finished. Refuse a commit that touches an infrastructure file.
The rule of thumb: if you would be genuinely upset that it happened, it is a hook or a permission deny rule, not a bullet in a markdown file.
Reviewing code you did not write
AI-generated code fails review differently from human code. It is rarely sloppy and almost never syntactically wrong. It is plausible - correct-looking, idiomatic, well-named, and quietly solving a slightly different problem than the one you have. Reading it the way you read a colleague's pull request will miss that, because the surface signals you rely on are exactly the ones the model is best at producing.
Read against the spec, not against the code. Open your acceptance criteria and check them off one at a time. Then run these five checks, which catch most of what slips through:
- What did it delete? Diffs are read top to bottom and removals hide at the bottom. An agent under pressure to make something pass will remove an assertion, a guard clause, or a whole test.
- Are the error paths real? Happy paths are the model's strongest suit. Check that failures are handled rather than caught and swallowed, and that the catch block does something other than log.
- Is anything new in the dependency tree? Agents reach for a package where three lines would do. Every new dependency is a supply-chain decision you just delegated.
- Does it duplicate something you already own? A second date formatter, a second fetch wrapper, a second validation schema. This is the most common quiet cost, and it compounds.
- Could you explain it in six months? If the answer is no, you do not have working code, you have an outage waiting for the person who did not write it either.
Use a second agent as a first-pass reviewer if you like - Claude Code ships a bundled /code-review and /security-review, Codex has /review, and Copilot and Cursor both review pull requests. Treat that output as a linter with opinions: excellent at spotting a missing null check, useless at spotting that the feature solves the wrong problem.
Cost control without rationing yourself
Every vendor meters differently - dollar credit pools, usage multiples over a rolling window, raw tokens - but the levers that reduce spend are the same everywhere, and most of them make the output better as a side effect.
| Lever | Why it works |
|---|---|
| Match the model to the task | A rename, a docstring, or a test scaffold does not need the flagship. Small models cost roughly a fifth as much per token and are indistinguishable on mechanical work. |
| Start fresh sessions | Long conversations re-send their whole history. A new session for a new task is cheaper and produces better answers, because the agent is not reasoning around three abandoned approaches. |
| Name the files | Exploration is the expensive part. Pointing at four files instead of asking it to find them can cut the token count for a task by an order of magnitude. |
| Delegate to subagents | A subagent researches in its own context window and returns a summary, so the search results never enter your main conversation and never get re-sent on every subsequent turn. |
| Keep the rules file short | It loads on every session, so a 600-line CLAUDE.md is a tax on every prompt for the rest of the project - and adherence drops as it gets longer, so you pay twice. |
| Cap the run | Headless and CI runs should carry a turn limit and, where supported, a hard budget ceiling. An agent stuck in a retry loop at 3am is a real invoice. |
Gotcha: the cheapest optimization is not asking. Half the prompts developers send are for things they could have typed in less time than the round trip took, and each one adds a whole conversation history to the bill.
When to close the chat and write it yourself
Knowing when to take over is a skill, and the signal is almost always the same: the third attempt. If two rounds of correction have not converged, a third will not either - you are now negotiating with a model that has anchored on a wrong mental picture, and each correction is fighting the previous context rather than replacing it. Stop, start a fresh session with a better description, or do it by hand.
Take over directly when:
- The change is small and the blast radius is large. Auth checks, permission logic, payment handling, anything touching money or identity. The typing was never the hard part.
- You cannot describe the problem. If you cannot write the spec, you are not ready to delegate - you are asking the agent to decide what you want, and it will.
- The failure is environmental. Wrong version, missing credential, stale cache, a Docker layer that did not rebuild. Agents guess confidently at these and can spend twenty minutes rewriting correct code.
- The domain logic lives in someone's head. Business rules that are nowhere in the codebase cannot be inferred from it. Write them down first, then delegate - now they are documentation too.
- You are learning the codebase. Delegating the exploration is how teams end up with a system nobody understands. Read it once yourself; you only pay that cost once.
The counter-case matters too. Hand it over without hesitation for mechanical breadth - a codemod across two hundred files, a test suite for an untested module, a dependency upgrade with a mechanical migration, a first draft of documentation from source. That work is genuinely faster, genuinely reviewable, and genuinely boring, which is the ideal profile.
AI-assisted development questions, answered
Do I still need to review AI-generated code line by line?
Yes, and you need to review it differently. AI code is rarely sloppy and almost never syntactically wrong, so the surface signals you use on a colleague's pull request do not help. Read against your acceptance criteria rather than against the code, check what the diff deleted as carefully as what it added, and confirm that error paths do something real. If you cannot explain the change six months from now, it is not ready to merge.
Should my repo use CLAUDE.md or AGENTS.md?
Use both, without duplicating anything. AGENTS.md is the closest thing to a cross-tool standard and is read by Codex, Cursor, and most open-source agents. Claude Code reads CLAUDE.md and not AGENTS.md, so create a CLAUDE.md whose first line is an @AGENTS.md import and put any Claude-specific instructions underneath. One source of truth, every agent reads it, and nothing goes stale in two places.
How do I keep AI coding costs under control?
Four levers do most of the work. Match the model to the task, because a rename does not need the flagship. Start a fresh session per task, since long conversations re-send their entire history on every turn. Name the specific files instead of asking the agent to go looking, which is the expensive part. And keep the rules file short, because it loads into every single session. Cap headless and CI runs with a turn limit so a retry loop cannot run all night.
When should I stop the agent and write the code myself?
On the third failed attempt. If two rounds of correction have not converged, the model has anchored on a wrong mental picture and a third round fights the context instead of replacing it. Start over with a better description or write it yourself. Take over directly for anything small with a large blast radius, such as auth, permissions, and payments, for environmental failures like a missing credential or a stale cache, and any time you cannot yet describe the problem.
Where to go next
Put the workflow on a specific tool: the Claude Code cheatsheet covers memory files, hooks, subagents, and the headless flags a CI job needs, and the Cursor cheatsheet covers rules files, context controls, and agent mode. Still choosing? The AI code assistant field guide has a verdict per tool.
To give an agent access to your issue tracker, database, or monitoring, read the Model Context Protocol explainer first - it is the difference between pasting context in by hand and letting the agent fetch it. For the pipeline side of the guardrails above, see the CI/CD pipeline guide and the testing tool directory.