How Should You Use AI to Rewrite a Project? Module by Module, Not Layer by Layer

Introduction

When you rewrite a project with AI, go vertical - one module at a time, full stack - not horizontal (database first, then backend, then frontend). Rewrite the first module by hand with a senior and an architect, turn it into a reference, lock the rules with documentation and tests, right-size the model, and aim for one prompt per module.

That's the short version. The longer story is that the model you pick matters far less than how you slice the work and what rules you hand the AI before it writes a line. Most teams default to a horizontal rewrite because it mirrors how their teams are organized - and it quietly fails. AI doesn't fix that failure mode. It amplifies it.

This article is about the practical side: how to structure an AI-assisted rewrite so juniors plus an AI agent can carry most of the load, stakeholders see progress every couple of weeks, and the AI doesn't quietly invent an architecture you never agreed to. It picks up where our earlier piece, Refactoring vs Rewriting from Scratch, left off: that one helps you decide whether to rewrite; this one assumes you've decided to, and focuses on doing it well with AI.

What changes when you rewrite a project with AI?

A rewrite means building a new version of a system - usually in parallel with the old one - and switching over once it's ready. That part hasn't changed. What AI changes is the economics and the risk profile.

Two things move:

• Who can do the work. Replicating an established pattern across many modules used to be senior work. With a good reference and a tight spec, a junior plus an AI agent can do it. The expensive part shrinks to the first module and the genuinely hard ones.
• Where the bottleneck sits. It moves off writing code and onto two things: specifying the work precisely, and reviewing what comes back. If your specs are vague, the AI fills the gaps with its own decisions. If your review is shallow, those decisions ship.

AI is excellent at one job and dangerous at another. Give it a clear pattern to follow and it will replicate that pattern across thirty modules faithfully. Give it freedom and it will invent architecture, add abstractions you didn't ask for, and "improve" things you needed left alone. The whole game is keeping it in the first mode.

How should you slice a rewrite: horizontal or vertical?

There are two ways to cut a rewrite into work.

Horizontal means slicing by layer: rewrite the whole database, then the whole backend, then the whole frontend. Vertical means slicing by module: take one feature end to end - its data, its API, its UI - rewrite all of it, ship it, then take the next module.

Horizontal: clean on paper, painful in practice

In my experience most teams go horizontal. It feels logical, and it maps onto how teams are usually structured - a backend group, a frontend group, each owning their layer. It looks clean on a plan.

It backfires for a specific reason: nothing works until the very end. A half-rewritten database with no backend on top of it demonstrates nothing. You accumulate months of work with no running vertical slice, no demo, and all of the integration risk compressed into the final phase - exactly when budgets are tightest and patience is thinnest. There's also no reference: nothing finished to anchor the AI against, and no clean unit of work to hand a junior.

Vertical: a working slice every time

Vertical wins, and it wins harder once AI is involved:

• Every module is a working slice you can demo. When a module is done, its whole behavior is rewritten and runnable. You show stakeholders a real capability, not "the data layer is 40% migrated."
• Work splits cleanly. A module is a self-contained unit you can assign, estimate, and review on its own.
• You agree the architecture once and reuse it. Settle the new patterns and decisions on module one, then every later module follows the same shape.
• The first module becomes a living reference. A senior and an architect build module one carefully. After that, juniors plus an AI agent rewrite the rest using module one as the canonical example - you can literally feed it into the prompt as "match this."
• Progress is continuous. Because changes are scoped to one module, you can demo on a regular cadence instead of going dark for half a year.

The big-bang trap

There's a third option people try and regret: big bang - dump the whole repository at the AI and ask for a rewrite. It produces an unreviewable diff built on architecture nobody approved. Skip it.

What rules does the AI need before you start?

This is the single biggest lever, and it's the part teams skip when they're excited to start generating. Before the AI writes anything, it needs a rulebook. The rulebook is what keeps it in "replicate the pattern" mode instead of "invent freely" mode.

The rulebook

What goes in it:

• Base documentation of the project - business logic and architectural approach. Even a rough version beats nothing.
• ADRs (Architectural Decision Records) - the decisions are locked in writing so the AI doesn't quietly re-decide them. Why this database, why this boundary, why this pattern.
• FR and NFR - functional requirements (what it must do) and non-functional requirements (the qualities: performance, security, extensibility).
• Acceptance criteria in Given/When/Then, not bullet points. This format matters more than it looks. Bullet-point AC leaves ambiguity, and the AI resolves ambiguity its own way. Given/When/Then is precise: given a state, when an action, then an outcome. And it maps almost one to one onto test cases - so writing AC this way gives you your test scaffold for free.
• Test cases written before the rewrite, derived from the docs above. This is the fence. With tests in place, the AI's job stops being "design this module" and becomes "make these tests pass while matching the reference module." That single reframing is what stops it from adding new logic, new patterns, and architectural decisions you never approved.

Definition of Done for every module

Once module one exists, define a clear Definition of Done for every AI-rewritten module and apply it every time: tests pass, the code matches the reference module's patterns, no new dependencies were introduced, behavior hasn't drifted from the characterization tests, and the relevant ADR is referenced. If a module doesn't clear that bar, it isn't done - regardless of how good the diff looks.

Which model should you use, and how many prompts?

Right-size the model

You do not need the biggest model with the most reasoning effort for everything. Right-size it to the task.

• Planning, decomposition, and documentation - use the heavy reasoning model. This is where deep reasoning pays for itself: writing the ADRs, shaping FR/NFR, breaking the project into modules. With Claude that's the Opus tier. (The same split maps onto other vendors - a frontier reasoning model here, a faster general-purpose one for the next step.)
• Generating the actual code against a tight spec - use the faster execution model. With Claude that's the Sonnet tier. Against clear documentation and a reference module, it overengineers less, doesn't disappear into its own reasoning as much, and returns solid solutions. You save tokens, you save response time, and - the point that matters most - you spend less money and effort producing a wrong solution.

One prompt, one module

The faster model leads into the most important discipline of all: aim for one prompt, one module. We call it "one shot, one kill." The success of a module correlates strongly with the detail of the very first prompt, so the first prompt should carry everything: links to the ADR/FR/NFR, the reference module, the acceptance criteria in Given/When/Then, the test cases, and explicit constraints - do not add dependencies, do not change the architecture, do not refactor anything unrelated.

Be honest about reality, though: one prompt per module is the target, not a guarantee. In practice you'll often need a follow-up to add missing context or correct the result. Each extra prompt is a tax, and the goal is to keep the count low.

Say no early: rewind and restart

When the AI drifts, say no early. If the output isn't what you expected, don't keep patching it in the same thread - a long session accumulates context and starts leaning on its own earlier, possibly wrong, decisions. End the session and start a fresh one with a sharper prompt and the reference module. In Claude Code there's a faster move: press Esc twice (or run /rewind) to roll back to the checkpoint before the bad answer - it creates one automatically on every prompt - then re-send a tighter prompt. You can also "summarize from here" to compress part of the session and free up context. Small habit, real impact: fewer tokens burned and noticeably better answers afterward.

What does an AI rewrite cost the business - and what does it buy?

The decision is ultimately a business one, so frame it in business terms.

Budget

Token cost is real but small next to salaries, and right-sizing the model plus keeping prompt counts low keeps it modest. The bigger economic lever is staffing arbitrage. Module one is expensive - a senior and an architect. Every module after that is cheap - juniors plus AI working against the reference. On our project the split landed around 80% of modules done by juniors plus AI, 20% by the tech lead plus AI (the tech lead took the first module and the complex, critical ones). That ratio is the real saving, not the token bill.

Delivery

Vertical slicing produces demoable progress on a regular cadence - on our project roughly every two weeks, with the exact timing tied to the complexity of the module in flight. Horizontal slicing produces zero demoable progress for months. The business feels that difference directly.

Why rewrite at all

Worth being precise here, because it shapes the acceptance metric. Our driver wasn't only that some modules were slow. It was business requirements - specifically, the need to extend particular modules with future business rules that the old structure couldn't absorb cleanly. So the measurable acceptance criterion wasn't latency, it was extensibility: can we add new business rules to this module without touching unrelated code? Vertical modules are independently extensible by design, which is precisely the business case for slicing that way.

Maintenance and support after the rewrite

The payoff doesn't stop at delivery - it shows up in every month of support afterward. Vertical module boundaries keep maintenance cheap: a bug usually lives inside one module, so you fix it without untangling cross-cutting layers, and you can ship that fix without redeploying everything. Because every module follows the same patterns as the reference, anyone on the team can pick up an unfamiliar one quickly, and the tests written during the rewrite double as a regression net for future changes. The same rulebook that guided the rewrite keeps working: a junior plus AI can extend or patch a module later by pointing at the reference and the existing tests. The result is that ongoing support doesn't bottleneck on the few people who happened to write the original code - which, with a small team, is often what decides whether a rewrite was worth it.

Risk of failure

A horizontal or big-bang rewrite can fail wholesale, because everything integrates at the end. A vertical rewrite fails, at worst, one module at a time - cheap to catch and cheap to recover.

Explaining it to stakeholders

Demo a module, not a layer. "Module X is fully rewritten - here's the new behavior, and here's how we'll extend it for the requirement you raised last month." Speak in modules and business capabilities, not in database tables and service layers.

Horizontal vs vertical vs big bang: a side-by-side

Case study: rewriting module by module with AI

A real project. We had a property and building management platform - React and JavaScript on the frontend, Python (Django REST) on the backend, PostgreSQL for data, deployed on a major cloud. Dozens of modules, from data-entry forms to dashboards and integrations with external government APIs. A small team and live customers who needed continuous forward motion.

Why we rewrote rather than refactored

The driver was business requirements, not cosmetics. Several modules needed to grow to absorb new business rules, and the existing structure couldn't take them cleanly. The acceptance criterion we agreed on was concrete and measurable - the ability to extend specific modules with new business rules without disturbing unrelated code. (We walk through how to make the refactor-or-rewrite call in a separate article; here we take the decision to rewrite as given.)

What we did - vertical, module by module

• Built the rulebook first. Base documentation of business logic and architecture, ADRs for the significant decisions, FR and NFR per module, acceptance criteria written in Given/When/Then, and test cases derived from those criteria - written before the rewrite, as the fence against invented logic.
• A senior plus an architect built module one carefully, and it became the reference for everything that followed. The tech lead also took the most complex and critical modules personally.
• Juniors plus an AI agent rewrote the rest against that reference. The split came out around 80% of modules by juniors plus AI, 20% by the tech lead plus AI.
• Right-sized the models. The Opus tier for planning, decomposition, and documentation; the Sonnet tier for generating code against the spec - faster, cheaper, and less prone to overengineering.
• Aimed for one prompt per module. We didn't always hit it, and that's fine. When the AI drifted, we didn't grind in the same thread - we rewound or started fresh to avoid context rot.
• Demoed roughly every two weeks, with the cadence flexing to the complexity of whatever module was in flight.

What got better

• The actual goal - extensibility. The rewritten modules could absorb new business rules locally, which was the entire point.
• Demoable, continuous progress instead of a months-long dark period - which kept stakeholders calm and the project funded.
• Junior throughput. With a reference module and a tight rulebook, juniors plus AI shipped modules that previously would have needed senior time.
• Predictable per-module delivery. Work became a queue of similar-shaped units, easy to estimate and review.
• Fewer invented-logic regressions, because the tests-first fence caught behavior drift before it shipped.
• Lower cost, from the staffing split and right-sized models together.

The takeaway

The model we used mattered less than the two things around it - how we sliced the work and the rulebook we handed the AI. Vertical slicing plus a reference module plus tests-as-fence turned what could have been a risky rewrite into something closer to a predictable assembly line.

How should you staff an AI-assisted rewrite?

The approach implies a specific team shape, and getting that shape right matters more than headcount.

• An architect and a senior (or tech lead) for module one and the hard modules. They set the patterns, write the ADRs, and build the reference everyone else copies. This is where you spend your most expensive people - deliberately, and only here.
• Mid and junior developers paired with an AI agent for the rest. Once the reference and rulebook exist, they can carry the bulk - on our project around 80% of modules. The skill that matters most for them is less raw coding and more reading a spec, following a pattern, and reviewing AI output critically.
• Someone who owns review. The bottleneck moves to review quality, so make it a named responsibility, not an afterthought.

If you're hiring or bringing in an outside team for this, look past "we use AI" as a selling point - almost everyone says it now. The real signal is whether they insist on the rulebook and a reference module before generating, right-size their models instead of reaching for the biggest one, and can show you demoable progress module by module rather than a single reveal at the end. A team that throws the whole repository at an AI and promises a finished rewrite is describing the failure mode, not the method.

This is the team shape we default to for AI-assisted rewrites at SDA, and it works as a checklist whether you build the team in-house or bring one in.

Common mistakes

1. Slicing horizontally. Layer by layer means no working slice and no demo until the end, with all the integration risk saved for last. Slice vertically so every finished module runs.

2. Throwing the whole repo at the AI. A big-bang prompt returns an unreviewable diff built on architecture nobody approved. Constrain it to one module at a time.

3. Generating before the rulebook exists. No ADR, FR/NFR, AC, or tests means the AI fills every gap with its own decisions. Write the rules first.

4. Acceptance criteria as vague bullets. Bullets leave ambiguity, and the AI resolves it its own way. Use Given/When/Then - it's precise and doubles as your test scaffold.

5. No tests before the rewrite. Without tests, nothing stops the AI from changing behavior or bolting on logic - the second-system effect Fred Brooks described in The Mythical Man-Month, now with an AI doing the over-building. Tests are the fence.

6. Endlessly correcting in one long thread. A drifting session leans on its own bad context. Rewind or start fresh instead of patching in place.

7. Using the maximum model for everything. The heaviest model is slower, costlier, and tends to overengineer. Right-size: heavy for planning and docs, fast for code.

8. Letting juniors work without the reference module. The reference is what makes junior-plus-AI safe. Build module one first, then hand it over as the example to match.

Conclusion

The success of an AI rewrite is mostly decided before the first line of generated code - by how you cut the work and the rules you give the model. Cut it into vertical modules, build the first one carefully as a reference, and put a real rulebook in front of the AI. Do that and the rest becomes a repeatable process that juniors and an AI agent can run.

If you're starting an AI-assisted rewrite, make sure you have:

• Vertical slicing - modules, not layers
• Base documentation plus ADRs, FR, and NFR
• Acceptance criteria written in Given/When/Then
• Test cases written before the rewrite, as the fence against invented logic
• A reference module built first by a senior and an architect
• A right-sized model, the one-prompt-per-module discipline, and a rewind-or-restart habit when the AI drifts

Get those in place and a rewrite stops being a heroic, senior-only effort and turns into an assembly line - one where every module stays independently extensible for the business requirements you haven't been handed yet.

Sources and further reading

• Fred Brooks, The Mythical Man-Month (1975) - the second-system effect.
• Dan North, Introducing BDD (2006) - origins of behaviour-driven development.
• Cucumber, History of BDD - the Given/When/Then template and Chris Matts' early contribution.
• SDA Company, Refactoring vs Rewriting from Scratch - deciding whether to rewrite in the first place.

Written from hands-on experience leading an AI-assisted, module-by-module rewrite of a production platform - Django REST and PostgreSQL on the backend, React on the frontend - delivered by a small team of seniors and juniors working alongside AI agents.