Legacy Comprehension — Capability Maps from Old Code

Tier: Core · Hands-on time: ~30 minutes

Legacy comprehension is the workload that agentic migration vendors lead with — AWS Transform's marketing counts billions of lines analyzed, which is evidence of demand whatever you make of the number. The architect's version of the job is narrower and more designable: not transforming the code, but extracting what the system does (capabilities), where it touches the world (interfaces), and which behaviors are load-bearing — as inputs to target-architecture design. Models with large context windows and repo-aware agents like Claude Code are genuinely strong here, with one systematic bias to manage: code describes what the system does, not why, and a model narrating legacy code will confidently supply the why it cannot know.

When to use

• •
  A modernization or replacement design needs a capability inventory of a system with thin documentation and thinner institutional memory.
• •
  An interface inventory is required before decomposition — every consumer, file drop, and integration that will break if the system changes.
• •
  Analyzer output (CAST-class scans, dependency reports) exists and needs synthesizing with the code into something a design review can use.

Skip AI when living experts and current documentation exist — interview first, and use the model to check the code against what the experts believe (the disagreements are gold), not to rediscover what is already known.

Prerequisites

• The code, complete and clearedrepository access including the unglamorous parts (batch scripts, stored procedures, config files, cron definitions); the pb-03 register cleared for AI processing of client source.
• Claude Code or a large-context modelrepo-scale comprehension needs either agentic file traversal or deliberate chunking with an index pass first.
• Analyzer exports where they existstatic-analysis inventories give the model a skeleton to verify and flesh out, and give you a second source to cross-check against.
• A capability-map templatecapability, evidence (files/procedures), interfaces in/out, data owned, business rules encoded, confidence.

The workflow

1. 1.

   Index before comprehending. First pass is cartography, not reading: "Traverse the repository and produce an inventory — entry points (jobs, endpoints, triggers, scheduled tasks), major modules with one-line guesses at purpose, external touchpoints (connection strings, file paths, queue names, API URLs), and dead-looking code (unreferenced modules). Cite file paths for everything; mark every purpose guess as GUESS." The index scopes the deep passes and immediately surfaces the system's true perimeter, which is reliably larger than anyone remembered.

2. 2.

   Extract capabilities with evidence discipline.

   Copy

   Deep-pass the order-management modules (list attached from the index).
   Produce capability-map entries:
   
   - CAPABILITY: what the system does, stated as a business function
     ("applies volume discounts at invoice generation"), not a code
     summary ("loops over line items").
   - EVIDENCE: the specific files, procedures, or jobs implementing it.
   - BUSINESS RULES: encoded rules with the code location — thresholds,
     date logic, special cases. Quote the constant, cite the line.
   - INTERFACES: what this capability consumes and produces (tables,
     files, messages, calls), with direction.
   - WHY-UNKNOWN: where the code implies intent you cannot verify
     (special-case handling, magic values, commented-out logic), list
     it here as a question — do NOT explain it away with a plausible
     story.
   

   The WHY-UNKNOWN column is this playbook's load-bearing wall. A 2009 special case for one customer ID is exactly what a model will smooth into "handles legacy customer edge cases" — and exactly what the target design must decide to preserve, kill, or escalate.

3. 3.

   Build the interface inventory as its own artifact. Consolidate every interface across capabilities into one table — consumers, producers, protocols, formats, schedules — and cross-check it against the analyzer export and network-flow data where available (pb-24's verified edges serve double duty). Interfaces the code shows but flows never confirm are candidates for dead; interfaces flows show but the code doesn't explain are the terrifying kind — both lists go to humans.

4. 4.

   Sample the map against the code — stratified, not random. Verification effort goes where wrongness is expensive: every capability marked as owning data (a misread there corrupts the target's data architecture), every business rule with a quoted constant (open the file, confirm the quote and its context), and a random handful of the rest. Score the sample; a batch with fabricated evidence citations gets its whole module re-passed, because comprehension errors cluster.

5. 5.

   Interrogate the map with the people who remain. Present the capability map to whatever institutional memory exists — ops staff, the DBA, the business analyst who filed the change requests. Their corrections and their confirmations both matter, but their surprises matter most: a capability nobody knew existed is either dead weight or a silent dependency, and the WHY-UNKNOWN list is the interview agenda.

6. 6.

   Hand the map to design, with confidence attached. The deliverable set for the target-architecture work: capability map with per-entry confidence, interface inventory with verification status, the business-rules register, and the open WHY-UNKNOWN questions. Vikram's rule for his BFSI core-adjacent systems: no capability enters the target design's "replace" column while its confidence is low — low-confidence capabilities get discovery tasks, not design decisions.

Verify before you trust it

• Evidence citations open and support. Every sampled capability's cited files actually implement what the entry claims. Models summarizing large codebases occasionally attribute behavior to the wrong module — a small error that sends the target design's decomposition down a wrong seam.
• Quoted constants are verbatim. Business rules with thresholds and dates get character-level checks against the source. A transposed digit in a discount threshold, carried into the target system's requirements, is a production defect scheduled years in advance.
• The WHY-UNKNOWN list is honestly long. A legacy comprehension pass that explains everything has been embellished — old systems always contain genuine mysteries. Suspiciously complete narratives are the tell; audit the smoothest sections hardest.
• Dead code verdicts get runtime evidence. "Unreferenced in the repo" is not "unused" — reflection, dynamic SQL, and external callers defeat static reading. Anything slated for non-migration on the model's dead-code assessment needs log or trace confirmation first.

Restricted-environment variant

Legacy source is often the client's most guarded IP — and in BFSI, the code encodes regulated business logic. Process inside the boundary without exception: Claude Code against the client-tenancy endpoint, or local models over a cloned repo for air-gapped estates (comprehension quality drops with model size; compensate by narrowing passes and doubling the sampling rate). Mainframe estates add a practical wrinkle — code often lives outside git in library managers; the extraction into reviewable text is itself a controlled operation under the client's change process. Analyzer exports usually contain hostnames and connection strings: scrub before any external processing, though inside-boundary processing makes scrubbing moot.