Adopting agentic development on a legacy codebase

You are here if

You use the agent for pieces of work and paste or adapt what comes back. You run one or two sessions at a time. You decide everything, read everything, and run everything yourself.

What is keeping you here

You still write a lot of the code, because you do not trust the agent. The parts you keep are the hard ones. Those are exactly the parts where it would have got things wrong, so you never see it get them wrong, and you learn nothing about what it is bad at.

Your runs are too short to leave you idle. Work you hand over in one prompt comes back in under a minute. There is no gap to fill, so a second session would not help. If two feels like your ceiling, that is usually why.

What to do

1. Hand over the coding, easier areas first. Start with the tests. They are the safest thing to hand over, because they are easy to judge and they show you what the agent misunderstood. Then move to code, beginning in the areas you know best. You are here to judge whether it got the change right, and you cannot do that in code you do not understand yourself.
2. Review everything. Every line, every change, for as long as this phase lasts. It is the only phase where that is the right thing to do.
3. Fix defects and design. Leave the style alone. The agent writes code differently from you. That is not a problem, and correcting it is expensive twice over: it costs you the time now, and anything you write down becomes a rule it carries on every future request. So push back on two things only. Something is broken or will break. Or the design is wrong: the change sits in the wrong place, or the shape of it is wrong. How the code is phrased is not your business any more. What earns a place in writing is Guidance.
4. Define your technical design. Which services exist, which boundaries matter, what lives where, which pattern is current and which one you are leaving. The agent can work most of it out by reading the code, but it pays for that in tokens every session and still guesses wrong at the edges. See DO control the technical design.
5. Make the boundaries you care about fail the build. Take two or three you would be angry to see crossed and write each as a lint rule on imports. It is the only check you can have in a phase with no tests yet, and it catches two of the three things an agent gets wrong on a legacy codebase: changing more than it was asked to, and putting the change in the wrong place. Your architecture is probably not the one you want, so record the violations that already exist and fail only on new ones. You are not claiming the structure is right. You are claiming it will not get worse.
6. Set up a session review. At the end of a working session, read the conversation back for every correction you gave, work out which rule would have prevented it, and write that rule down. It keeps your markdown files and your technical design current, so the next session starts from what the last one learned. Cockpit runs it as a skill: session-review. See DO catch a mistake when the session ends.
7. Let the product side start building proofs of concept. Your tickets, ceremonies and estimation all stay as they are in this phase. This is the one exception. A question about what to build, answered by something you can click, is worth a week of discussion.

You are here if

The agent writes most of your code and it is mostly right. You read every change before it merges, and that is now where your day goes. You would like to run more work at once and you cannot, because you are the only thing standing between a change and production.

What is keeping you here

You wrote the rules down instead of building tests. This is the common one. A markdown file does not stop anything: nothing fails, nothing goes red, and the agent can ignore it. So you are still the only thing catching mistakes, and it feels like progress because the file keeps growing.

Your tests are stuck at the expensive level. Without a clean architecture you cannot test a small piece on its own, so everything has to go through the browser or the whole system. Those tests are slow. A slow suite is one people skip, and a skipped suite catches nothing.

You want to clean up the code first. You cannot yet. A refactor with no tests around it is a change nobody can check, and an agent doing it does not make that safer.

What to do

1. Write your test levels, the rule for choosing one, and what the suite may cost. One file, which the agent reads before it writes a test. Name the levels. Say what each one may reach, as a table rather than a judgement call. Give one rule for picking between them. Put the run time you are willing to pay in the same file, so the budget is in front of the agent when it decides. Cockpit's testing strategy is the worked example. See DO decide the test levels yourself and DO write down what the suite is allowed to cost.
2. Write tests for the code you touch. You could ask an agent to write tests for the whole codebase this month, and you should not. Tests written against code nobody is changing only record what it does today, bugs included, and nobody reads ten thousand of them closely enough to notice. The tests you end up trusting are the ones written while you were changing that code and could still tell whether they were right. So they arrive one area at a time, as part of the change to that area. At first the only ones you can write go round the outside, through the browser or the API, because the code will not let you in lower. Write them anyway. Never keep one you have not seen fail: see DON'T trust a test you haven't seen fail.
3. Monitor and optimise your harness. It only ever gets slower and more thorough on its own, and a harness you cannot afford is one people skip. You need four answers on demand, with no reporting stack behind them: how long a change takes from first commit to merged, how long CI takes and which job is slowest, what a change costs in CI minutes and tokens, and how often a check fails for a reason that is not the change. Then run the cheapest thing that can safely judge a change, and do the same with reviews instead of one depth over everything. I left this late. My pipeline went from under a minute to eleven over three weeks, on 246 runs in a single week, and I still cannot tell you how much of that was worth paying for. See DO build a lead time report, DO publish the pass rate of every check and DO let the change decide how deep the review goes.
4. No big refactors. Small local ones, only to make an area's tests cheaper. Once a slow test is around an area, you will have to change the code so a faster test can reach the logic. That is a refactor, and its purpose is the speed of your tests rather than the quality of your design. The limit: the test you just wrote has to be able to catch it going wrong. See DO let agents fix old architecture, behind tests that can catch a broken refactor.
5. Set up a periodic review, so the agent learns from the fixes made after the merge. Corrections you make during a session already reach your guidance. What never reaches it is everything you fixed a week later. Every few weeks, read what merged, the review threads and the closed issues, and file one issue for each thing that happened at least twice. Cockpit runs it as a skill: periodic-review. See DO spend a session every few weeks reading your recent work.
6. Set up a harness review, so you can manage what your harness costs. Nothing removes a check unless somebody goes looking. Take each required check, ask what it has actually blocked and what it costs to run, and file one candidate for each one that is not earning it. I ran a remote security review on every pull request for weeks: it found nothing on 30 of 31 runs, after an earlier sample of 39 that also found nothing. Cockpit runs it as a skill: harness-cost-review.
7. Move QA, and do not cut it. Away from structural testing, towards acceptance testing, deciding what has to be proven, and keeping the harness efficient. This is the phase where that judgement is worth the most, and the phase where most companies cut it because the agent writes the tests now. See DO agree the product's rules before the work starts.
8. Let the product side build proofs of concept on the real product. In phase 1 those were throwaway. Now there is a harness, so a rough version can go into the actual codebase and the tests will say whether it broke anything. That is the first thing the harness buys anyone outside engineering, and it arrives long before the loop does.

Both review skills arrived on day 33 of my own project, after the loop was already running, and my own cycles still mostly watch the harness rather than the guidance. This is something I learned rather than something I did in the right order.

You are here if

Your tests catch things before you do. You hand over whole changes now, but you scope each one yourself, start it yourself, and remember the review yourself. Two or three at a time at most.

What is keeping you here

You answer the agent's questions while it works. It asks what you meant, you tell it, and the change comes out fine. So you never find out that the ticket did not contain the answer, and the next ticket does not contain it either.

Scoping takes you about as long as building takes the agent. If a change takes it forty minutes and a ticket takes you thirty, you cannot keep two running, whatever your tooling does.

What to do

1. Build a command that helps you scope. You are about to write far more tickets than before, and the shape of a good one is not obvious. A skill that asks the questions in order, decides whether the work has to be seen before it is built, sizes the slice and writes out the rules the change has to satisfy gives every ticket the same shape, whoever wrote it. Cockpit's is scoping, and it runs before any code exists on every piece of work.
2. Write tickets in product language, not implementation. That is what keeps someone who has never opened the codebase out of the how, and still lets them start the work. See DO write the ticket in product language.
3. Size the work, and let a model split it. On a legacy codebase keep it smaller than feels necessary. The smaller the change, the less there is for the agent to get wrong about where things belong. See DO set the limit on how big a piece of work can be.
4. Run three or more tracks in parallel locally. A worktree per track, each with its own branch, ports and environment, is the usual answer, but the worktree is only the mechanism. The requirement is that nothing is shared: two agents in one checkout is the first thing everyone tries and the first thing that breaks. See DO give every track its own worktree, branch and environment.
5. Take on the bigger refactors you have been putting off. The harness could not catch them in phase 2 and it can now, because you have been adding tests to every area you touched ever since. The limit moves from one seam to whatever your tests cover. See DO let agents fix old architecture.
6. Extend the periodic review to count rework. How often a feature had to change after it shipped, through bug fixes, design changes or scope changes. That is your scoping quality, and it is the number nobody tracks. A ticket that needed no questions and then three rounds of rework was not a good ticket. See DO spend a session every few weeks reading your recent work.
7. The product manager scopes the work, not just the outcome. Not a ticket saying what should be true, but the whole piece of work shaped through the same scoping skill an engineer would use. Where it makes sense an engineer does it instead. What matters is that both use the same skill, so the result is the same shape whoever produced it.

You are here if

You write a ticket and the agent builds it without coming back to ask. You are still the one starting each change, checking on it, and remembering to run the review.

What is keeping you here

You run every change through the steps yourself. Scope it, start the build, come back to see where it got to, run the review, merge it. None of those steps is hard. There are just five of them on every change, and they all need you. That works at two changes at once and falls apart at four, and what fails is that you forget a step on the one that mattered.

Your setup was built for three tracks. Ports, databases, preview environments and CI capacity are all sized for what you do today, and each one becomes the constraint in turn as the number goes up.

What to do

1. Build one command that takes a ticket all the way to merged. It runs the steps you have been running by hand: scope, build, test, review, ship. Do not restate your rules inside it. See DO build one skill that takes a ticket all the way to merged and DON'T restate your rules inside the command.
2. Scale the same setup from three tracks to five or ten. What you built by hand for three does not survive ten. This is infrastructure work and it is most of the phase. You will also need a way to ask where each session stands without reading back through it: see DO ask each session where it stands.
3. Watch what parallel work does to your process and your architecture. Both will show cracks, and the cracks are the roadmap. No automated review will tell you the team is stuck. That one you have to look for. See DON'T expect any automated review to tell you the team is stuck. OpenWhat comes out of the guidance file, which has been growing for months and is read on every request, is still unanswered.
4. Make the product strategy hold. A weak one starts to hurt here, and it is worth treating as a target rather than a consequence. Far more has to be decided and prepared ahead of the engineers, because what they get through has gone up sharply. Development got cheaper. Being wrong did not. See Roles.