Why Claude fails at legacy (The 5 Signal Files technique)

Open a 3-year-old monolith in Claude, paste 40 files, and the model returns a generic refactor that ignores the system's most critical edge cases. It's not a model problem. It's a context problem.

The 5 Signal Files

This isn't a magic number; it's a limit that forces the right decision. What files does the model need to reason about this specific refactor?

1. The file you want to refactor.
2. Its direct imports (not transitive ones).
3. The type definition file affecting it.
4. A representative test, if it exists.
5. A CONTEXT.md written by you.

Step 2 is where most fail. Transitive imports pull in utilities, helpers, and unrelated modules. Claude uses them to "understand the system" and ends up suggesting changes that couple what you wanted to decouple.

CONTEXT.md is the differentiator between a senior and an amateur AIDD session. The model doesn't know why that code exists; you do:

## Context: payment-gateway.ts

**What it does:** Processes payments via Bancard vPOS and manages order status.

**Non-breakable constraints:**

- The `legacyId === 999` block compensates for a PYG rounding error in corporate accounts. Do not delete.
- The function must be idempotent; Bancard webhooks can arrive duplicated.

**Refactor goal:** Extract validation logic into a pure, testable function without touching the Bancard integration.

With this context before the code, the model understands the system: it knows what's off-limits, where to go, and why that weird legacyId block is a deliberate decision, not a bug. Without it, it optimizes individual files and hands you the exact refactor that breaks production—often ignoring how to handle indestructible payments with Algebraic Data Types.

The Claude Code Flow

# Start the session with context, not code
/read CONTEXT.md
/read src/payment-gateway.ts
/read src/types/payment.ts
/read src/payment-gateway.test.ts

The Trade-off

If the refactor spans more than 3 interdependent modules, this technique alone isn't enough. Signal fragments across sessions and the model loses the thread of constraints defined in CONTEXT.md. At that point, split the work into per-module sessions, each with its own CONTEXT.md, or use a sub-agent per context if your tooling allows it.

The practical indicator: if describing the refactor goal takes more than 5 sentences in CONTEXT.md, the scope is too large for a single session.

The same criteria applies to AI-generated tests: the more signal and less noise in the initial context, the better the result. See how I generate E2E tests with AI.