Pattern 17

One canonical copy, and pointers from everywhere else

Problem. The same rule ends up written in three places: the user-global instructions, the workspace instructions, and a project file. All three were correct on the day they were written. Then one gets edited. Now an agent loading all three reads two versions of the rule and silently picks one, and a reader checking the project file gets an answer that the workspace file contradicts. Nobody notices, because each copy looks authoritative on its own. Duplication does not announce itself as duplication; it announces itself as a wrong answer, months later, with no obvious cause.

Pattern. Each fact has exactly one canonical location. Everywhere else points at it and states that it is a pointer.

Three mechanics make that hold. Delete the copy, keep the pointer. When the same rule appears twice, the second instance becomes a one-line reference naming the canonical file and section, not a summary of it, because a summary is a copy that drifts more slowly. Banner what is superseded. A document that has been replaced says so at the top, names its replacement, and stays on disk, so the reader learns which copy governs from the document itself rather than from folder archaeology. Measure the duplication mechanically. Always-loaded files accumulate shared boilerplate that no single edit introduced, so something has to scan across them and report the overlap.

Why this beats the obvious. The obvious fix is to keep the copies synchronised, which is a promise to do unbounded manual work forever, made by whoever is least likely to remember. It also fails silently: nothing breaks when a copy drifts, so nothing prompts the fix.

The pointer approach has a property the sync approach lacks. A pointer cannot disagree with its target. It can be stale (pointing at something moved or renamed), but stale-and-broken is loud, whereas stale-and-plausible is not. Trading a silent failure for a noisy one is most of the value.

This workspace's own instructions carry a worked instance, left in place deliberately: a communication-standards section that had been duplicated into the workspace file was cut back to a pointer after the inline copy was found to have drifted from its source. Two bullets had diverged and one had gone missing entirely. Neither file looked wrong.

Cost. Indirection. A reader following a pointer needs a second lookup, which is a real tax on comprehension, and pointer chains longer than one hop become their own problem. Canonical placement also has to be decided rather than discovered, and the wrong choice is expensive to reverse once other files reference it. Duplication is genuinely cheaper right up until the first edit.

Where it lives: samples/scripts/claudemd_audit.py inventories every always-loaded instruction file and flags size, staleness, broken imports, and boilerplate duplicated across files. Pattern 5 is the same instinct applied to memory; this is it applied to instructions, which are loaded on every session and so cost on every session.

Seen in 2 of 8 teardowns · Practise: learn/01