How to review a feature your coding agent built

Claude Code finishes a feature and reports that it added a payout service, two REST endpoints, a gRPC method, a Kafka consumer and a migration. Say the diff is 38 files. You can read it top to bottom, but diff order is alphabetical and has nothing to do with how the pieces run, so you end up holding the design in your head while reading code in the wrong order.

Read the shape before the lines

A line-by-line review answers one question: is this code correct? There's a cheaper question to answer first. Is this the design you asked for?

The mistakes that cost most to undo sit at that level. A service boundary in the wrong place, a new dependency on a third-party API, a synchronous call where you wanted an event. All of them show up as boxes and arrows. At the line level you only notice them after reading most of the diff, and by then you've already spent the review.

So ask for the map first, while the agent still has the whole change in context.

What the map needs to show

A map of every box in the system is too much. Four categories cover the design changes a line-by-line read tends to miss:

1. Entry points. Every new or changed route, RPC method, consumer and scheduled job. Each one is a way into the system that someone has to secure and support.
2. Writes. Every table or store the change writes to, plus any it now reads that it didn't read before.
3. New dependencies. Calls to services or external APIs that the touched code didn't make before this change.
4. Async edges. Events published and consumed, with topic names.

Async edges are the easiest to miss in a diff. The producer and the consumer sit in different files, and the only thing connecting them is a string.

A prompt that produces a usable map

Ask before you start a new session, because the agent loses the context of what it changed.

Before I review the diff, describe this change as a system:
1. Every new or changed entry point (HTTP route, RPC method, consumer, job), with its path or name.
2. Every table or store it writes to or newly reads from.
3. Every service or external API it calls that it did not call before.
4. Every event it publishes or consumes, with the topic name.
Then draw it: one node per service, store, topic or endpoint, and one labelled edge per call or event.
Only include things that appear in the diff. Mark anything you are unsure about.

The last two lines do most of the work. Without the first one, an agent that read half the codebase while it worked has no reason to stop at the part you changed. The second gives it a way to flag a guess instead of presenting it as fact.

Check the map against the diff

The same model wrote the code and the map, so the map can be wrong in the same places as the code. Don't skip this step.

Take each entry point on the map and find it in the diff. Then go the other way. Search the diff for the things that create entry points and edges in your stack, such as route decorators, @KafkaListener or consumer.subscribe calls, outbound HTTP clients and new migration files. Anything you find that isn't on the map is the most useful result of the whole review, because it's the part of the change that neither of you was thinking about.

Once the map and the diff agree, read the code in the order the map suggests. Start at an entry point and follow the edges. It's much easier to judge a function when you already know what calls it and what it writes.

Where to keep the map

For a one-off review, a Mermaid block in the pull request description is enough. GitHub renders it, and most coding agents can write Mermaid.

The limits show up a month later. Mermaid boxes are text. "Payout Service" in this pull request and "PayoutSvc" in the next one are two unrelated strings, and nobody can ask which diagrams mention the service before changing it.

This is the problem ArchDocs is built for. The agent connects over MCP and writes the map as a document. Services and queues are references to objects in a shared catalog, endpoints are REST and gRPC cards with their parameters and responses, and tables show their columns. The next agent session can read that document before it touches the same area, and each object lists every document that uses it. There's a short walkthrough on the coding agents page.

If your team doesn't keep architecture docs at all, the Mermaid block is the cheaper choice. The review method works the same either way.