All writing
  • architecture
  • microservices
  • ai agent
  • migration

How do I split a monolith into services when AI agents write the code?

People decide the boundaries and who owns the data, the spec becomes the thing you review, and each extraction stays small enough to undo

To split a monolith into services when AI agents write the code, let people decide the boundaries, who owns which data and what the contract between services is. Then review the written spec and the contract, not only the code the agent produces. Extract one small slice at a time, behind a switch that sends traffic back to the old code, and run the same gates on every change. Agents make writing a service cheap. They do not make deciding where the service starts and ends any cheaper, and that is the decision that goes wrong.

I am Ash, a Staff engineer in Toronto. I lead a move from a monolith to services that the CTO sponsors, and it starts with one team. I introduced spec-first development with coding agents there, where engineers write and review the spec, agents write the code, and tests and review gates check every change before it merges. I also got the plan agreed with product, design, customer support and engineering leadership. The work is in flight, so I report no results from it. This article is the method, with sources, for staff engineers and engineering leaders planning this move.

One extraction when agents write the code. People decide the boundary, the data owner and the contract, then review the spec. An agent writes the code and tests. Gates check every change, and a failed gate goes back to the spec. Traffic moves to the new service a little at a time and the old code stays, so there is a way back.

What changes and what stays the same

Writing code is no longer the slow part. The slow parts stay slow. Someone has to know where the seams of the system are, what the old code does that nobody wrote down, and how to move traffic without breaking anyone.

Martin Fowler’s description of the strangler fig approach names the work that does not go away. You understand the outcomes you want, decide how to break the problem into smaller parts, deliver the parts, and change the organisation so this can continue. None of the four is typing. Sam Newman’s book Monolith to Microservices is for people who want to “evolve your current systems, rather than just rewriting everything from scratch”. Agents change who types, not that order of work.

What does change is where review effort goes. An agent produces plausible code faster than anyone can read it line by line, so review moves up to the things that stay small, which are the boundary, the data ownership, the spec and the contract.

Decide the boundary and the data owner before an agent starts

A service boundary is also a statement about who owns which data and which team answers the page. Those are decisions about the business and about people, so I keep them with people. An agent can trace imports, list every query that touches a table and draw the call graph, and that evidence is worth having. I would not accept a list of proposed services from it as the answer.

A boundary should follow a business capability, not the folders of the code. The Microsoft architecture guide on identifying microservice boundaries gives checks to run on a candidate. One is that “there are no chatty calls between services”, and if splitting two pieces of functionality makes them overly chatty, “it might be a symptom that these functions belong in the same service”. An agent reading the code sees imports and tables. It does not see the refund rule that only support knows.

Write the decision down before any code exists, with four answers on one page for each candidate.

  1. Which business capability it owns, in the words the business uses.
  2. Which data it owns, and how any other part of the system may read it.
  3. What must stay consistent in one transaction and what may be eventually consistent.
  4. Which team is paged for it.

Restructuring before splitting is a step I would not skip. At a company I worked at, I led a team of 7 that turned a tangled MVC codebase into one that is easy to read and maintain, in place, using domain-driven design. I wrote the architecture documents and ran the design reviews. It was not a split into services, and it did not need to be. A codebase with clear parts is also a better thing to hand to an agent.

Make the spec and the contract the unit of review

When an agent writes the code, the artifact you can afford to review closely is the spec. A good spec for one extraction is short enough to read in one sitting and says what the code cannot say for itself.

  • The data the service owns, and the interface it offers, including the error cases.
  • The behaviour that must stay exactly the same, and the behaviour you are deliberately dropping.
  • How traffic moves, and what the way back is.
  • How you will know it works, in checks that can fail.

The second point matters more than it looks. Fowler notes that “replacements seem easy to specify, but often it’s hard to figure out the details of existing behavior”, and that much of that behaviour “isn’t really wanted, so building it is a waste”. His page on the feature parity trap says workarounds for past bugs have become requirements for current business processes. An agent told to preserve everything will preserve everything, including the accident. A person has to say what to leave behind.

Then review changes shape. Engineers write the spec and other engineers review it, and code review asks whether the code matches the approved spec and contract.

In the case study of how I run my products with AI agents, each step starts as a written plan with decisions, pass marks and a numbered list of slices, and each slice is small enough for one agent to finish in one run. A fresh builder agent gets a brief for that slice and the repository’s rules, and no history.

Cut each extraction small, and keep a way back

Size is your main safety control. Fowler says that “since these components are small, there isn’t so much risk involved when we introduce the new software”. Three patterns from the same family do most of the work.

The strangler fig, in Sam Newman’s pattern page, wraps the new system around the old one, redirecting calls as functionality is ported.

Branch by abstraction lets old and new implementations live in the same running system behind one abstraction, so callers move over gradually. Fowler’s rule is to “ensure that the system builds and runs correctly at all times”. It also keeps the work off a long-lived branch, which matters because a long-lived branch of agent-written code is a large unreviewed diff waiting to happen.

Parallel change, also called expand and contract, splits an incompatible change into “expand, migrate, and contract”. It suits database and interface changes and has one trap. Fowler warns that “if the contract phase is not executed you might end up in a worse state than you started”. Agents are good at the expand phase and happy to stop there, so put the contract phase in the spec as a task with an owner.

Fowler’s legacy displacement article names parallel run as another cutover strategy. In plain words, you run old and new side by side and compare what they return before the new one answers for real.

At a company I worked at, I led the migration of 120 services to Kubernetes with no downtime. Traffic moved one service at a time, and each move had a tested way back. That was a platform move and not a monolith split, but the rule carries over. A step you cannot undo needs a stronger argument than one you can.

Run the same gates on every change, and enforce them

Do not rely on the agent remembering your rules. The Claude Code documentation on memory and instruction files says the model treats them as “context, not enforced configuration” and that to block an action regardless of what it decides, you use a hook. The hooks guide describes hooks as “deterministic control: certain actions always happen rather than relying on the LLM to choose to run them”. The open AGENTS.md format calls itself “a README for agents”, which is the place for conventions. Hooks and CI carry the rules that must hold.

For an extraction I would gate on these, in this order.

  1. The behaviour tests for the slice pass in the monolith before anything moves.
  2. Contract tests prove the new service keeps the promises in the spec.
  3. A check that nothing outside the owner reads or writes its data.
  4. The full suite and the linters, run by a hook so nobody can skip them, people included.
  5. A review of the diff by a second reader, an agent or a person, who has not seen the first one’s reasoning.

In my own products every change passes hooks that block unsafe edits and a CI run of 3,584 tests and 279 browser tests. One lesson from that case study applies here. Tests that replace the model with a stub pass the happy path and say nothing about failure, and a service called over a network is the same. Have the agent write the tests for the timeout, the duplicate message and the service that is down. The hooks themselves are covered in How do I set up guardrails for an AI coding agent?.

What agents are bad at in this work

This list is my view, from the reasoning above, not from a measurement.

  • They copy existing behaviour. They cannot tell a rule from an accident, so they keep both.
  • They guess at data ownership. A table read in three places looks shared, so two services end up writing to it.
  • They do not feel the cost of the network. A function call in the monolith becomes a request, and an agent will chain a dozen of them.
  • They make services cheap to write, which tempts you into too many. Cheap to write is not cheap to run.
  • They report success from tests they wrote themselves, so the checks must come from the spec.

What I would reject, and what it costs

I would reject three shortcuts. The first is asking an agent to propose the services and accepting the answer, because the boundary is a business decision. The second is one large task to extract a whole module, because a diff that size cannot be reviewed or undone cleanly. The third is a long-lived branch, for the reason given above.

The approach has real costs. Writing and reviewing specs moves effort to the front, so the first extractions go slower than a team expects.

You also build code you will throw away. Fowler admits people balk at building transitional architecture “that will go away once the modernization is complete”, and then says “the reduced risk and earlier value from the gradual approach outweigh its costs”. I agree, and I would still budget for it, because while old and new run side by side you pay for two systems.

Adoption is its own work, and Fowler lists changing the organisation as one of the four activities. In my current work I got the plan agreed across product, design, customer support and engineering leadership, and I keep those groups current as each part moves.

A plan for the first weeks

  1. Write the outcome you want from the split in one paragraph, and get the affected groups to agree to it.
  2. Ask agents to map dependencies and data access for your starting area, read-only.
  3. Have people decide the first boundary, the data owner and the contract, on one page.
  4. Put the instruction file and the hooks in place so the gates run on every change.
  5. Write the spec for the smallest slice that can move traffic, with the way back and the contract phase.
  6. Let an agent build it, run the gates and move a small share of traffic. Compare old and new, then decide.
  7. Write what you learned into the instruction file or a test, and start the next slice.

When the first slice is boring, you are ready for the second.

Frequently asked questions

Can an AI agent decide where to split a monolith?

It can help you see the coupling, but a person should decide. The boundary is about business capabilities, data ownership and who is paged, and the code does not hold all of that. Use agents for evidence and have people choose.

Should I make the monolith modular before I extract services?

Often yes, because it is a smaller step that you can undo. Restructuring in place, as in the domain-driven design work above, makes the seams visible. Extract a part once it has a narrow interface.

How big should one extraction be when agents write the code?

Small enough that a person can review the spec in one sitting and that you can send traffic back with one switch. If a slice needs a long-lived branch, cut it again.

Do I still need people to review the code?

Yes, where a mistake is expensive, such as data, permissions and the cutover itself. For the rest, a reviewed spec, contract tests and a second reader can carry the review. Decide that line before the first slice.