luria

The agent file is a map, not a copy

3 min read

Graph View

ADR-037: The agent file is a map, not a copy

Status Active · Filed 2026-08-07 · Issue #45

Context

CLAUDE.md had grown into a restatement of the record’s doctrine — the four layers, the filing rules, the correction protocol, a command block — and the scaffolded template/CLAUDE.md mirrored it. Every piece of that content has an authoritative home elsewhere: the doctrine in project memory, the vocabulary in the directives doc, and the command surface in luria --help, which is derived from the dispatch table itself.

The copies drifted exactly as DP-3 predicts: the command block had to be chased when ADR-030 removed three commands, and again when ADR-036 replaced journal with new — two rounds of hand-synchronization in one week, on one file, with review catching the smell (#45).

Decision

Both CLAUDE.mds truncate to a map: a short list of links to the authoritative pages, the invitation to run luria --help for the current API, and the three ground rules terse enough that restating them costs less than a link — work goes to a branch and a PR, file the fragment in the same contribution as the work, every reference is a hyperlink.

The map states its own failure mode: when this file disagrees with the docs or the CLI, this file is the one that’s wrong. An agent reading the map is told where authority lives rather than handed a copy of it.

Alternatives considered

  • Keep restating the command surface. A fourth hand-maintained copy of COMMANDS (help text, README table, Makefile help, CLAUDE.md block), and the one that misleads an agent the fastest — it is the first thing an agent reads and the last thing anyone edits.
  • Keep restating the doctrine. A worse copy of project-memory.md that also costs agent context on every session; the doctrine is one click away and linted for staleness there, not here.
  • Generate CLAUDE.md from the record. The DP-5 mechanization instinct, premature: the map is now ten stable lines of prose, and machinery to regenerate prose that never changes is scaffolding without a building. Revisit under #45 if the map starts drifting too.

Consequences

  • The repo’s CLAUDE.md and template/CLAUDE.md stop mirroring each other’s bodies — one maps this repository, one maps an adopting project — which retires the “this file is also the template” preamble and its double-maintenance.
  • The wikilink teaching example and the directive walkthroughs leave CLAUDE.md; they live in the directives doc, which the map links.
  • The README’s command table and the Makefile’s help remain the two hand-maintained restatements, tracked by #45.

Backlinks