Briefing a coding agent on an existing repository

Most of the code we touch already exists. It has conventions nobody wrote down, tests that cover some things and not others, and a deployment path somebody set up two years ago. A coding agent dropped into that repository with a one-line task will produce something plausible. Whether it produces something the team can merge depends almost entirely on what it was told first.

This is the brief we have settled on. It is not long, and most of it is reusable between tasks.

Start with the task, not the tool

The first thing in the brief is the actual change, described the way a reviewer will judge it: the behaviour before, the behaviour after, and what must not change. We write it as acceptance criteria rather than as implementation hints, because the agent is good at finding an implementation and bad at guessing what "done" means.

• One observable outcome. "Invoices with a zero total are skipped by the export job" is a task. "Improve the export job" is a conversation.
• What stays fixed. Public API shapes, database schema, anything a downstream system depends on.
• Where the evidence is. The existing test, log line or fixture that shows the current behaviour.

Give it the rules of the repository

The second part lives in the repository itself, in a short file the agent reads on every run. It replaces the tribal knowledge a new engineer would absorb in the first week. Ours tends to look like this:

# AGENTS.md

## Running things
- Tests: bin/rails test (unit) and bin/rails test:system (slow, run only when asked)
- Lint: bin/rubocop -a before every commit

## Rules
- Do not change db/schema.rb by hand; write a migration.
- Background jobs must be idempotent: check for an existing record before inserting.
- Never call external APIs from a model callback.

## Out of bounds
- config/credentials/*, anything under vendor/

Two things matter here. The file is short enough that it is read in full, and every rule is one the team will enforce in review anyway. A rule that only exists for the agent is a rule nobody maintains.

Context the agent should go and find

We do not paste half the codebase into the prompt. Instead the brief names the entry points: the controller or job the change starts from, the test file that will need to grow, and one example of a similar past change. The agent reads from there. This keeps the brief stable while the repository changes underneath it.

Keep the loop short

The brief ends with how the work comes back. The loop we run is deliberately small:

1. The agent proposes a plan in a few lines and lists the files it expects to change.
2. An engineer confirms or narrows the plan. This takes a minute and saves an hour.
3. The agent implements, runs the fast tests and reports what it ran and what it did not.
4. Review happens on a diff small enough to read in one sitting. If the diff is not small enough, step one was wrong.

The agent's job is to make a decision easy to review. Our job is to make the decision.

Working rule from a recent engineering enablement engagement

Step three is where most of the trust is earned or lost. A report that says "tests pass" is less useful than one that says "ran 41 unit tests, skipped the system suite, did not touch the migration you asked me to leave alone". We ask for the second kind explicitly.

What this changes in practice

Roughly the same amount of engineering judgement is spent, but it moves. Less goes into typing and more into the brief and the review. Over a few weeks the repository rules file becomes the most accurate description of how the team actually works, which is a side effect we did not plan for and now rely on.

If you are introducing agents into a team that owns an existing system, this is the shape we would start from. The services behind it are described under AI adoption for engineering teams, and the longer, structured version of the argument is in Keep delivery accountability when AI speeds up coding.