AI & developer workflow
AI Coding Agent Context and Verification: A Checklist
How to give an AI coding agent bounded context, inspect its diff and demand evidence from checks, so suggestions stay separate from verified changes.
An AI coding agent is only as reliable as the context you give it and the checks you can run against its output. Give it a bounded task, the facts it cannot infer from the code, and a command that returns pass or fail. Then review the diff and the command output, not the agent's own summary of what it did.
Quick answer
- Bound the task: one behavior change, a named area of the code, and a stated definition of done.
- Supply what the repo cannot show: constraints, commands, forbidden areas, the reason behind the change.
- Give the agent a pass or fail check and ask for the command and its output as evidence.
- Read the diff yourself. Treat everything the agent says without evidence as a suggestion.
- Enforce the rules that cannot have exceptions in tooling (hooks, CI, branch protection), not in prose.
Suggestion versus verified change
An agent produces text and edits. Neither is evidence that the software works. A change becomes verified only when something independent of the agent's reasoning confirms it: a test, a typecheck, a build exit code, a reviewer who did not see the conversation, or you running the app.
This distinction is the whole workflow. The agent proposes, the checks and the reviewer decide. GitHub's documentation on the Copilot coding agent says it directly: it can produce incorrect or suboptimal code, including code with security vulnerabilities, and its session logs "do not replace your own review and testing."
I have written about what AI changes in my development workflow in general terms. This article is narrower: how to set up one task so that the result is checkable.
Bound the task before you start
Vague tasks produce wide diffs, and wide diffs are expensive to review. A useful task brief has five parts: the goal, the scope, the constraints, the check, and the evidence you expect back.
The following is an illustrative brief, not a record of a real session. It assumes a TypeScript project with an npm test script.
Goal: reject webhook requests whose timestamp is older than 5 minutes.
Scope: only src/webhooks/verify.ts and its test file.
Constraints: no new dependencies. Do not change the public signature
of verifySignature(). Do not touch src/billing/.
Check: npm run typecheck && npm test -- verify
Evidence: paste the exact command output and list every file changed.
Each line removes a decision the agent would otherwise guess. The scope line is also your review boundary: if the diff touches src/billing/, you already know something went wrong, before reading a line of code.
If a task does not fit in a brief like this, split it. A schema change plus a refactor plus a new endpoint is three tasks, each with its own check.
Give it the context the repo cannot show
Agents read the repository themselves, so do not paste your architecture into the prompt. Write down what is not in the code:
- The commands that build, test and lint, with the exact flags.
- Rules like "never edit generated files" or "migrations are append-only".
- Why a strange-looking piece of code exists.
- Which behavior is intentionally unchanged.
The open AGENTS.md convention is a plain Markdown file at the repository root for this purpose, "a README for agents". There are no required fields. It commonly holds build and test commands, code style and security notes, and per the site, if you list test or lint commands, agents will attempt to run them and fix failures before finishing. In monorepos, the nearest file in the directory tree wins, and an explicit prompt overrides the file.
Claude Code uses a CLAUDE.md file the same way. Its best practices guide recommends keeping it short, because every line costs attention on every task, and limiting it to what the model could not work out from the code. It also warns against describing architecture and file layout that the agent can read for itself.
A minimal file in that spirit (illustrative, any OS):
# Project notes
- Check before finishing: `npm run typecheck && npm test`
- Generated files in `src/gen/` are never edited by hand; run `npm run gen`.
- Database migrations are append-only. Never edit an existing one.
- Webhook handlers must stay idempotent (see docs/webhooks.md).
Make the check return pass or fail
The Claude Code guide puts the problem bluntly: if the agent has nothing to run that says whether the work is done, "looks done" is all it has, and you become the test suite. A check that returns pass or fail closes the loop. The agent changes code, runs the check, reads the failure and tries again.
Useful checks, from cheapest to most thorough:
| Check | Catches | Misses |
|---|---|---|
| Typecheck or compiler exit code | Broken types, missing symbols | Wrong behavior that type-checks |
| Linter | Style and some bug patterns | Logic errors |
| Unit tests for the changed code | Regressions in covered behavior | Anything the tests do not cover |
| Fixture diff (output against a stored file) | Unintended output changes | Wrong fixtures |
| Running the app or a browser screenshot | Integration and UI problems | Rare edge cases |
None of these is complete. A passing suite is evidence about the behavior the suite covers, nothing more. If the agent writes both the code and the tests in the same session, the tests may encode the same misunderstanding as the code. Review new tests as carefully as new code, and prefer writing the failing test yourself for the behavior you care about most.
Ask for evidence, not confirmation
"All tests pass" tells you very little. Ask for the command, the exit status and the output. The Claude Code guide gives the same advice and notes that for a session you were not watching, command output is the only evidence you have.
Cross-platform note: define the check as an npm script, a CMake target or a make-style task, so the same name works on Windows, macOS and Linux. For example, in package.json (Node 20 or later assumed):
{
"scripts": {
"typecheck": "tsc --noEmit",
"verify": "npm run typecheck && npm test"
}
}
Then the brief says "run npm run verify" regardless of the shell.
Inspect the diff like a pull request
Read the diff before you read the agent's explanation. Then ask four questions:
- Is every changed file inside the scope I stated?
- Are there deleted tests, loosened assertions, skipped cases or broadened
try/catchblocks? - Did it add a dependency, a config change or a network call that I did not ask for?
- Can I explain each hunk without referring to the agent's summary?
A fresh reviewer helps. The Claude Code guide describes reviewing the diff in a subagent that never saw the conversation, so it is not swayed by the reasoning that produced the code. It also suggests reviewing against a written spec and telling the reviewer to skip style, because a reviewer asked to find problems will always find something, and fixing every finding invites needless abstraction. A human teammate who did not write the prompt works just as well.
For hosted agents the same discipline applies at the repository level. GitHub notes that repository rulesets or branch protection can block the Copilot coding agent from creating or updating pull requests unless an administrator allows it. Required reviews and required status checks keep an agent's pull request on the same path as any other.
Where this approach is the wrong tool
- Exploratory design work with no testable outcome. The agent can sketch options, but there is nothing to verify, so the value is only in what you decide.
- Code with no tests and no way to run it. Write the check first, or accept that review is your only safety net and keep the diff very small.
- Security-sensitive paths such as authentication, cryptography and payment logic. Use the agent for suggestions if you like, but require a human who understands the threat model to sign off.
- Tasks where the context is mostly in people's heads. Writing it down takes longer than doing the work.
Why this matters for production work
I am co-founder and Technical Lead at Legacies in Bucharest, where my responsibilities are backend architecture, integrations and product stability. Those are areas where an unreviewed change is expensive, which is why the verification habits above matter more than which agent writes the first draft. I have not published measurements of AI-related time savings, so I will not attach numbers to this workflow. You can see the company at legacies.ro, read about it in the Legacies section, or browse selected work for the kind of full-stack and systems projects where these checks apply.
Frequently Asked Questions
How much context should I give an AI coding agent?
Give it what it cannot read from the repository: build and test commands, constraints, forbidden areas and the reason for the change. Do not paste architecture descriptions or file listings, since the agent can read those itself and extra text competes for attention. Keep persistent instruction files short and update them when the agent repeatedly gets the same fact wrong.
Is a passing test suite enough to trust an agent's change?
No. It shows that the behavior covered by the tests still works, nothing about uncovered behavior. Review the diff, check that no tests were weakened, and run the application for anything user-facing.
Should the agent write its own tests?
It can, but treat those tests as part of the change under review. Tests written in the same session as the code can share its misunderstanding. For critical behavior, write or approve the test first, then let the agent make it pass.
What should I do when the agent claims it ran the checks?
Ask for the exact command and its output, or rerun the check yourself. A claim without output is a suggestion. Where a rule must never be skipped, enforce it with CI or a hook so it does not depend on the agent's report.