Give coding agents clear repository instructions, working checks, and useful examples. Make each task easier to implement and review.
Not long ago, getting good results from an AI coding assistant was mostly about the prompt. You pasted the relevant file, described the task carefully, and hoped the model had seen enough to fill in the rest. The advice that worked then still holds: give context before the task, state the constraints, show an example instead of describing one, and work in steps.
What changed is the shape of the tool. Coding agents now run in the terminal and the editor. They read the repository on their own, run commands and tests, call external systems through MCP, spawn sub-agents for parallel work, and load instruction files the repository provides. The prompt you type is a few sentences. Most of what the agent knows comes from the environment.
That shifts where effort pays off. The repository supplies context beyond the prompt: what the agent reads before it starts, which examples it can follow, and how it can check its own work. Maintained repository context can help across sessions and team members.
An original diagram of the context a repository gives a coding agent.
The instruction file is the team’s standing context
Write down what a new engineer would need
Most agents look for a repository instruction file, commonly AGENTS.md or CLAUDE.md, at the root and sometimes in subdirectories. Loading rules vary by tool and directory. Check the agent’s documentation and confirm which instructions it receives.
Put in it what a new engineer would need on day one that isn’t obvious from the code. The commands to install, build, test, and lint. The conventions that tooling doesn’t enforce. Where things live. And the gotchas: the generated folder nobody should edit, the migration command that needs a flag, the test that fails for a known reason.
# AGENTS.md
## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- Before any commit: `pnpm typecheck && pnpm lint && pnpm test`
- Single test file: `pnpm test path/to/file.test.ts`
## Conventions
- Server components by default. Add "use client" only for interactivity.
- Data access goes through `lib/db/`. Never query from components.
- New API routes follow `app/api/invoices/route.ts`.
## Gotchas
- `lib/generated/` comes from `pnpm codegen`. Do not edit by hand.
- Migrations: `pnpm db:migrate --env local`. Never target staging.
- Timestamps are stored in UTC. Format them only in the UI layer.
Keep it short and current
Every line competes for attention with the task itself. A sprawling instruction file dilutes the ten lines that matter, and stale instructions are worse than none, because the agent will follow them. Keep it to what changes behavior, and link to longer docs rather than pasting them in.
Treat the file like code. When the agent makes the same mistake twice, that usually points to a missing line. When a line no longer matches the codebase, delete it. Review changes to it in pull requests, because it is code for a different reader.
Skills turn recurring tasks into playbooks
Write the procedure once
Some tasks recur with the same steps: adding an API endpoint, writing a migration, cutting a release, triaging a bug report. Instead of explaining the procedure in every session, write it once as a skill or playbook. That means a short document with the steps, the files involved, the checks to run, and a pointer to a good example.
Agents that support skills can load their full instructions when needed. Skill descriptions may still occupy context before a skill runs. The instruction file says how the repository works. A skill says how to do one specific job in it.
The test for a good skill is the same as for a good runbook. A capable person who has never done this task should be able to follow it and produce something reviewable.
Plan before code on anything non-trivial
Review the plan, not only the diff
For a one-line fix, let the agent go. For anything that touches several files, a data model, or behavior users see, ask for a plan first: which files will change, what the approach is, what could break, and how the work will be verified. Read it before any code exists.
A plan is cheap to correct. A wrong assumption caught at the plan stage costs a sentence. Caught in a 600-line diff, it costs the diff. Planning also surfaces the decisions the agent would otherwise make on its own, like whether to change an existing interface or add a new one, or whether a missing test is intentional.
This is the old advice to iterate in steps, applied at the right grain. Agree on the approach, then implement, then verify.
Give the agent a way to check its own work
Verification is part of the context
Tests give an agent feedback it can use to correct mistakes before review. They also give the reviewer evidence beyond the agent’s description of its work.
Make verification available and cheap: fast unit tests, type checking, lint, and a way to run a single test file. For interface work, give the agent a running preview it can open in a browser and screenshot, so it sees the layout it built instead of guessing. For backend work, provide a seeded local database and a script that exercises the endpoint.
Put the commands in the instruction file, and state in the task which checks define done. If a check is slow or flaky, fix it. The agent will run it far more often than any person did.
Scope the task so the diff is reviewable
Small, specific, and pointed at an example
You are still responsible for what ships, so the unit of work should be something you can review properly. “Add pagination to the projects API” is reviewable. “Improve the projects page” is not. Split large work into tasks that each produce a coherent diff with its own verification.
The strongest way to communicate style is still to show it. Instead of describing how an endpoint should be structured, point at one that already is. The agent can read the file, and matching a real example is far more reliable than interpreting a description.
A well-scoped task has the same parts as a good prompt always did, with verification added:
Context: The /projects page loads every project at once. Some
accounts have thousands of projects and the page times out.
Task: Add cursor-based pagination to GET /api/projects and use it
on the /projects page with a "Load more" button. Infinite scroll
is out of scope.
Constraints:
- Follow app/api/invoices/route.ts, which already paginates by cursor.
- No schema changes. The (account_id, created_at) index exists.
- Keep the response shape backward compatible for the mobile app.
Verify:
- pnpm typecheck && pnpm test api/projects
- In the preview, sign in as the seeded large account, open
/projects, and confirm "Load more" appends the next page.
Show me the plan before editing.
Keep sessions focused
Start fresh when context gets polluted
Context windows are large now, but quality still beats quantity. A long session accumulates failed attempts, abandoned approaches, and outdated copies of files. The agent starts following an idea you rejected an hour ago, or keeps working around a bug that has since been fixed. More context isn’t more understanding.
When a session drifts, stop and start a new one. First, ask the agent to write a short handoff: the goal, what is done, what was tried and ruled out, what remains, and the commands that verify it. Start the next session from that summary. The same discipline applies to sub-agents. Give each one a narrow brief and ask for a compact result, so the main session receives conclusions rather than every file the sub-agent read.
Ask what context was missing
When a result is bad, the most useful question is still the old one: what context was missing? Usually the answer is a file, a convention, or a check the agent didn’t know about. Fix it in the repository, not only in the conversation, and every later session starts ahead.
Tools extend context beyond the repository
Connect what the work depends on, with least privilege
Through MCP, an agent can read the documentation for the library version you actually use, pull the issue it is working on, query a development database, or drive a browser to check a page. That removes a lot of copying and pasting, and it grounds the agent in current information instead of whatever it remembers from training.
Every tool is also a permission. Grant read access by default, scope write access to what the task needs, and point database tools at a local copy or a read replica, never at production with write credentials. Keep secrets out of the agent’s environment where you can. The question isn’t only whether a tool is useful. It is what the worst plausible mistake with that tool would cost.
What still needs a person
Judgment, architecture, and anything irreversible
Good context makes agents faster and more reliable at implementation. It doesn’t transfer accountability. Some things stay with people:
- Product judgment: what to build, for whom, and which trade-offs are acceptable.
- Architecture: boundaries, data models, and decisions that are expensive to reverse.
- Security review: authentication, authorization, secrets, input handling, and new dependencies.
- Anything irreversible: production migrations, deletions, deploys, and messages to customers.
Agents can draft, analyze, and propose in all of these areas. The decision, and the final button press, stay human.
A practical starting point
One file, one check, one example
You don’t need to reorganize a codebase to get most of the benefit. Start with this:
- Write a short
AGENTS.mdwith the real commands, a handful of conventions, and the gotchas that have bitten people. - Make sure one command runs the fast checks, and that it passes on a clean checkout.
- For your most common kind of task, find the best existing example and reference it by path.
- On the next non-trivial task, ask for a plan first and review it before any code is written.
- Each time the agent gets something wrong, ask what context was missing and add it to the repository.
After a few weeks, the instruction file reflects how the team actually works, and every new session starts from a better place.
Maintain the context
The prompt still matters, but it is the last few sentences on top of everything the repository already says. Teams that get consistent results from coding agents invest in that layer: clear instructions, reusable playbooks, fast checks, good examples, and tasks scoped for review. The same instructions and checks help new engineers understand the project.
Review this context when commands, dependencies, or conventions change. Stale instructions can repeat the same mistake across many tasks.