Reverse Engineering your Software Architecture with Claude Code to Help Claude Code

Nick Tune · article · 2026-10-08 Reader 🖥️

Developer Experience & Flow Golden Path Organizational Legibility Platform Engineering World Model (Organizational)

Because coding agents' usefulness on complex, cross-repository problems is bottlenecked by lack of end-to-end system understanding, using Claude Code itself to reverse-engineer and document standardized, versioned, machine-and-human-readable flow diagrams (UI to BFF to API to DB to events) measurably improves the agent's ability to investigate real incidents — but this is a stopgap: the real target state is platform tooling that exposes the system as a live dependency graph so agents consult a source of truth rather than reverse-engineering it themselves.

practical · narrative — A first-person practitioner case study (explicitly 'one day of hacking around') describing an iterative process of using Claude Code to reverse-engineer and document multi-repository end-to-end flows, then feeding that documentation back to Claude Code for production-incident investigation. Ends with a forward-looking architectural claim about platform engineering's future role.

Structure

Part	Role
Motivating observation: Claude Code is useful on simple stack-trace bugs but weak on complex, cross-repository support tickets because end-to-end flows span many repos and the default `/init` doesn't produce sufficient detail	context
Setting initial context: a light requirements doc instructing Claude to map UI-to-BFF-to-API-to-DB-to-event flows in Mermaid, plus two light reference files (domain concepts, system overview) and filesystem/GitHub read permissions across sibling repos	evidence
Mapping the first flow collaboratively (~2 hours), iterating on diagram format (sequence diagram rejected as unreadable; settled on horizontal swimlane flowcharts with a constrained vocabulary of valid step types)	evidence
Subsequent flows map faster (~15 min each) once the pattern and requirements doc are established; author stays 'in the driving seat' on deciding flow boundaries and scope	evidence
Evolving the requirements file itself (grew to 449 lines) as a persistent, re-runnable spec so new Claude sessions can reproduce the process without a warmed-up context window; rules accumulate from observed failure modes (e.g. must read full AWS Step Functions workflow files, not infer from partial reads)	evidence
Testing the payoff: feeding the flow docs back into a support-ticket investigation agent, which correctly identified the affected flow and proposed a targeted event-history verification plan instead of needing to re-derive system behavior from scratch	evidence
Accuracy/hallucination risk: significant inaccuracies were found and corrected by the author; four mitigation options floated (tolerate imperfection if path-finding still works, CI-pipeline checks, periodic regeneration, dedicated verification agents/swarms)	counter-evidence / qualification
Closing claim: this reverse-engineering effort is a stopgap; the real future task for platform engineering is building frameworks/tooling (e.g. Event Catalog) that expose the system as a live dependency graph so agents consult a source of truth instead of reverse-engineering it	conclusion

Key terms

flow Developer Experience & Flow
A single end-to-end path through the system from a UI action, through a BFF, to backend APIs and/or events, including database interactions and downstream workflow/event consumers — documented with a fixed, descriptive name and a constrained vocabulary of step types (HTTP endpoint, aggregate method call, database operation, event publication, workflow trigger/step, lambda invocation, UI action).
reverse engineering architecture (with Claude Code, for Claude Code)
Using a coding agent to inductively derive and document a system's actual end-to-end behavior (as opposed to its intended design) by reading code, OpenAPI specs, and workflow definitions across repositories, producing an artifact that both humans and the agent itself can subsequently consult.
source of truth (for architecture, platform-exposed)
A live, platform-maintained graph of the system's actual dependencies and flows that agents can consult directly, as opposed to an artifact that must be periodically reverse-engineered and risks drifting stale or inaccurate.

Propositions

explicitA coding agent's usefulness on complex production issues (e.g. a support ticket with no stack trace) scales with how much it understands about the end-to-end domain behavior of the system, not just the code of a single repository.conf: high
explicitThe default `/init` command and single-repository analysis are insufficient for systems whose end-to-end behavior spans multiple repositories, because the agent cannot see the other repositories' code without being explicitly granted access and instructed to look.conf: high
explicitConstraining the diagram format to a fixed, small vocabulary of step types (HTTP endpoint, aggregate method call, DB operation, event publication, workflow trigger/step, lambda, UI action) and a horizontal swimlane-per-repository layout produces more consistent, readable output than letting the agent choose its own diagram style, which initially produced an unreadable sequence diagram and over-granular method-call detail.conf: high
explicitA persistent, versioned requirements/rules file that accumulates specific corrections (e.g. 'you MUST read the ENTIRE workflow definition, not infer from a partial read') measurably reduces iteration count and increases output quality across repeated runs, even though the agent still does not follow every instruction.conf: high
explicitReproducing the flow-mapping process in a fresh Claude session (rather than continuing in the same warmed-up context) validates that the accumulated requirements file is itself a sufficient, largely repeatable specification, though the agent would still sometimes ignore parts of it.conf: medium
explicitHaving pre-built, machine-readable architecture-flow documentation lets an investigation agent immediately identify the relevant flow and expected behavior for a complex support ticket, replacing a slow, context-expensive, unverified from-scratch codebase analysis with a structured, directly usable starting point.conf: high
explicitAgent-generated architecture documentation contains significant inaccuracies that a human reviewer must catch, and undetected inaccuracies would be dangerous because they could silently misdirect important system decisions.conf: high
explicitA dedicated verification agent, run fresh against the same flow, successfully detected the same inaccuracy the author had manually spotted — making agent-based verification a credible (if costly) mitigation for documentation drift/hallucination.conf: medium
explicitReverse-engineering architecture after the fact is an inferior, interim solution compared to platform tooling that exposes a live, authoritative dependency/flow graph as a source of truth agents can consult directly without needing to infer system behavior from code.conf: high
implicitOrganizations with a paved-path platform (and especially greenfield startups without legacy systems) stand to profit disproportionately from AI agents, because the platform itself removes the need for agents (or engineers) to reverse-engineer system behavior.conf: medium

Arguments

Investing a day in agent-assisted, standardized flow documentation is worthwhile even though it is acknowledged as an interim, imperfect solution. strength: medium

Explicit premises:

Claude Code's value on complex, cross-repository problems is bottlenecked by lack of end-to-end domain understanding.
A constrained documentation format (fixed step vocabulary, swimlane layout, two files per flow) produces consistent, reusable output across many flows once established.
The documentation measurably improved a real investigation-agent's performance on a genuine support ticket.

Implicit premises:

The learning value to the human author (discovering nuances about the system they didn't know) independently justifies at least part of the effort, separate from the agent-performance payoff.
The risk of documentation drift and hallucinated inaccuracies is manageable through periodic regeneration or verification agents, rather than disqualifying the whole approach.
A one-day, single-practitioner effort generalizes reasonably to the needs of other engineers or new team members, not just the author's own investigative workflow.

Inferences:

If documentation drift is not actively managed (via CI checks, periodic regeneration, or verification swarms), the accuracy problem will compound over time in exactly the way agent-config-decay and context-rot patterns elsewhere in the corpus describe for other kinds of agent-consumed artifacts.
The explicit list of four accuracy mitigations, none of which the author commits to, implies the practice as described is not yet production-hardened — a team adopting it needs to choose and operationalize one of those mitigations, not treat the one-day prototype as a finished practice.

Narratives

The author tests the flow documentation by picking a complex support ticket, adding a step instructing the investigation agent to check '/docs/architecture/flows,' and watching it correctly identify the affected flow, propose an event-history verification plan, and converse 'more like... a team member' than a pattern-matcher — though it did not resolve the ticket.
→ Directly supports the proposition that pre-built flow documentation shifts agent investigation from slow from-scratch codebase analysis to immediate, structured reasoning grounded in known expected behavior.
Early in building the first flow, Claude initially produced an unreadable sequence diagram and over-granular method-call steps; only after two hours of iterative correction did the author and Claude converge on the horizontal swimlane format with a constrained step vocabulary.
→ Supports the proposition that format constraints must be discovered and encoded through iteration rather than specified correctly upfront, and illustrates why the requirements file grew to accumulate such rules.

Questions addressed

✅ Does pre-built architecture documentation actually help a coding agent, or does it only benefit human readers?
Tested directly on a real support ticket: the investigation agent used the flow docs immediately and productively, rather than needing to re-derive system behavior from the codebase.
⭕ How should the risk of inaccurate or stale agent-generated architecture documentation be managed long-term?
Four options are listed (tolerate imperfection, CI checks, periodic regeneration, verification agents/swarms) but none is chosen, tested at scale, or shown to actually resolve the maintenance burden — the author explicitly says they are 'not sure this is the optimal way of approaching the situation.'
⭕ Who maintains and re-validates the flow documentation as the underlying system changes, and at what ongoing cost relative to its benefit?
Not addressed beyond the speculative options above; the article ends by redirecting the real solution toward platform-level tooling rather than resolving the maintenance question for the documentation approach it just demonstrated.

Gaps

incompleteThe article never resolves how the documentation stays synchronized with a changing codebase over time (beyond floating, without choosing or testing, 'destroy and regenerate quarterly' or CI checks or verification swarms) — it is a one-day snapshot with no reported re-validation after initial creation.
Read next: extract-pilcer-agent-first-engineering-playbook's 'doc-gardening agent' (scheduled background agent that detects doc/code drift and opens fix-up PRs) proposes a concrete mechanism for exactly this gap.
incompleteThe article doesn't examine whether the effort of building and maintaining this flow documentation is actually less costly than the platform-level 'expose the system as a dependency graph' solution it endorses in its conclusion — it treats the two as sequential (interim vs. ideal) without comparing their respective costs, or addressing why platform teams haven't already built the graph-exposure tooling it calls for.
Read next: Compare against the corpus's platform-engineering and golden-path material on why paved-path adoption and tooling investment lag behind individual practitioner workarounds.