Most advice about adopting AI coding agents is written for organizations with a platform team, a security review board, and a budget line for "AI enablement." Small teams don't have any of that. They have a backlog, a production system, and maybe ten engineers — and they are exactly the teams where agents can make the biggest relative difference, because there is no slack capacity to absorb the boring work.
We adopted agents as a small team ourselves, and used them to ship three open-source infrastructure tools. This is the playbook we would hand to a past version of us — what to have in place first, where to start, and what will go wrong in month one.
Pick the Right Pilot
Start with a project that is real but not critical. A throwaway demo teaches you nothing, because nobody reviews throwaway code seriously and review is the skill you are actually building. A critical system is the opposite problem: the first misstep becomes an argument for abandoning the whole effort.
Good pilots we have seen: an internal tool, a new service that isn't on the revenue path yet, a well-isolated module of a bigger system, a documentation overhaul. Something where the team will genuinely care about the output but a bad week costs a bad week, not an outage.
The Prerequisites That Matter More Than Tool Choice
Teams agonize over which agent to use. In our experience the choice of tool matters far less than what the agent lands in. Before the pilot starts, the repo needs:
- Tests that run fast and mean something. The agent will use them as its feedback loop hundreds of times a day. If your test suite is flaky or takes twenty minutes, fix that first — it is the single highest-leverage preparation.
- CI that gates merges. Lint, typecheck, tests, build. The agent's output goes through the same gate as everyone else's.
- A written conventions file. More on this below — it is the most underrated item on the list.
- Small-PR culture. If your team already merges 2,000-line PRs without reading them, agents will make that habit fatal. Fix the habit either way.
Notice that every item on this list pays off with or without AI. That is not a coincidence — agents amplify whatever engineering discipline exists. Amplified discipline is velocity; amplified chaos is chaos, faster.
Write the Doc the Agent Reads
Every serious agent tool reads a repository-level instruction file — CLAUDE.md, AGENTS.md, or equivalent. Most teams either skip it or paste in a mission statement. Both are mistakes.
This file is the highest-density lever you have over output quality. It should contain the things a senior engineer tells a new hire in their first week: how to run the tests, which patterns to copy and which legacy corners not to imitate, naming conventions, what "done" means, the commands that must pass before a PR is opened. Ours are short — a page or two — but every line is a rule we got tired of repeating.
Treat it like code. When the agent makes the same mistake twice, the fix is usually a line in this file, not a longer prompt next time. We covered how this fits the larger loop in our AI-driven development workflow.
Supervised First, Autonomy Later
Run the loop supervised at the start: the engineer watches the agent work, interrupts wrong turns, and reviews every diff before it lands. This feels slow. It is also where the team learns the two skills that determine everything downstream — writing specifications precise enough to act on, and reviewing AI-generated code without rubber-stamping it.
Autonomy is something the setup earns. When a class of task has gone well ten times — dependency bumps, test additions, a well-specified refactor — let the agent run it end-to-end and review only the PR. Keep novel or risky work supervised. The trajectory is per-task-type, not global: we still supervise anything touching auth, migrations, or anything with infrastructure blast radius.
Measure Rework, Not Velocity
The vanity metrics — lines generated, PRs opened, "acceptance rate" — all go up the moment you adopt agents, and none of them tell you whether the code was worth merging.
The honest metric is rework: how much agent-produced code gets reverted, rewritten, or bug-fixed within a few weeks of merging. Track it roughly — a label on PRs that touch recently-merged agent work is enough. If rework is low and falling, expand scope. If it is high, the problem is almost always upstream of the agent: vague specs, weak tests, or reviews that approved things nobody understood. We wrote more about which costs actually dominate in the real costs of AI-driven development.
Budget the Review Time
The bottleneck moves. Writing code stops being the constraint; reading it becomes the constraint. A small team adopting agents should expect review load to grow substantially, and plan for it — review time on the calendar, smaller PRs enforced ruthlessly, and a shared understanding that "the agent wrote it" is never a reason to skim.
If nobody on the team has capacity to review carefully, the team does not have capacity to adopt agents yet. Generated-but-unreviewed code is not an asset; it is inventory with unknown defects.
Month-One Failure Modes
Expect these. They are normal, and each has a process fix:
| Failure mode | What it looks like | The fix |
|---|---|---|
| Huge diffs | Agent refactors half the codebase to fix one bug | Cap scope in the instruction file; reject oversized PRs mechanically |
| Test-shaped tests | Tests that execute the code but assert almost nothing | Review tests first; require failing-then-passing demonstrations for bug fixes |
| Invented APIs | Code calls library functions that don't exist | CI catches it if typecheck/build gates are real; treat as a signal specs lacked references |
| Confident wrong turns | Agent "fixes" the wrong root cause, plausibly | Supervise novel work; ask for the diagnosis before the diff |
| Instruction drift | Same mistake recurring across sessions | Every repeated correction becomes a line in the conventions file |
None of these are reasons to stop. All of them are reasons to keep the loop tight in month one.
When Not to Adopt Yet
An honest list. Hold off if:
- There are no tests. The agent has no feedback loop and you have no safety net. Write the first tests — with the agent's help, supervised, if you like — before anything else.
- There is no CI gate. Unreviewed, ungated generation into a shared branch is how codebases rot at machine speed.
- The codebase runs on tribal knowledge. If the rules live only in someone's head, the agent can't follow them and the team can't review against them. Write them down first.
Every one of these fixes is worth doing even if you never adopt an agent. That is the reassuring part: the preparation is just good engineering, and it pays for itself either way.
Takeaways
- Pilot on something real but not critical — review skill only develops on code people care about
- Tests, CI, and a conventions file matter more than which agent you pick
- Write and maintain the repo instruction file — every repeated correction becomes a line in it
- Supervise first; grant autonomy per task type as it's earned
- Track rework, not lines generated — reverted diffs are the metric that can't flatter you
- Move review capacity to where the bottleneck now is — reading, not writing
We have set this loop up for ourselves and shipped real software with it. If you want a team that has already made the mistakes to help yours skip them — from CI gates to the first supervised pilot — get in touch.
