Lists and pages that stay true
Manifests for everything
One typed list, a list in code whose shape the type checker verifies, of every instance of one kind of thing, such as every environment variable, checked against the code in both directions.
One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.
An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.
The problem
Some facts about a codebase have no single home. An environment variable, a setting the program reads when it starts, is read in one file, given its type in another, set in a secrets store and described in no single place. So someone writes a list of them all. It is right on the day it is written. Then the code moves on and the list does not, and nothing fails, because nothing compares the two.
I've found agents make this worse. An agent reads a typed list as fact, because it looks authoritative, and agents add most of the new variables without adding a row, because that was not the task. In one service, the list of log events, the named entries it writes as it runs, lacked 295 of its 689 names.
The idea
Keep one typed file per kind of thing, a manifest, and check it against the code in both directions. Some codebases call it a registry, and so does the example below. A use with no row fails. A row that nothing uses fails too, which is the half most checks leave out, and the half that keeps the list short enough to read.
Some uses are rightly outside the rule, such as a variable only the test runner sets. Those go on a list of exceptions, each with a written reason. An exception with no reason fails, and so does one whose use has gone. Any page people read about the manifest is generated from it, and checked against a fresh render.
A version small enough to read
Three source files, a registry of two variables, and one exception. Each run below changes one thing.
// A registry of environment variables, checked against the code in both// directions. Run: bun check.tstype Row = { name: string; purpose: string };type Exception = { file: string; name: string; reason: string };
const registry: Row[] = [ { name: "DATABASE_URL", purpose: "Where the app's database lives." }, { name: "MAIL_FROM", purpose: "The sender address on outgoing email." },];const exceptions: Exception[] = [{ file: "test/setup.ts", name: "TEST_SEED", reason: "Only the test runner sets this." }];
const code: Record<string, string> = { "src/db.ts": "const url = process.env.DATABASE_URL;", "src/mail.ts": "const from = process.env.MAIL_FROM;", "test/setup.ts": "const seed = process.env.TEST_SEED;",};
const render = (rows: Row[]) => rows.map((r) => `- ${r.name}: ${r.purpose}`).join("\n");
function check(code: Record<string, string>, rows: Row[], excs: Exception[], envDoc: string): string[] { const reads = Object.entries(code).flatMap(([file, src]) => [...src.matchAll(/process\.env\.(\w+)/g)].map((m) => ({ file, name: m[1] }))); const problems: string[] = []; if (Object.keys(code).length === 0) problems.push("No source files found, so nothing was checked."); for (const r of reads) { const excused = excs.some((e) => e.file === r.file && e.name === r.name); if (!excused && !rows.some((row) => row.name === r.name)) problems.push(`${r.file} reads ${r.name}, which has no row. Add one to the registry.`); } for (const row of rows) if (!reads.some((r) => r.name === row.name)) problems.push(`${row.name} is in the registry but nothing reads it. Delete the row.`); for (const e of excs) { if (!e.reason.trim()) problems.push(`The exception for ${e.name} in ${e.file} has no reason. Write one.`); if (!reads.some((r) => r.file === e.file && r.name === e.name)) problems.push(`${e.file} no longer reads ${e.name}. Delete the exception.`); } if (envDoc !== render(rows)) problems.push("ENV.md differs from the registry. Regenerate it; do not edit it by hand."); return problems;}
const doc = render(registry);const runs: [string, string[]][] = [ ["As it stands", check(code, registry, exceptions, doc)], ["A new read with no row", check({ ...code, "src/pay.ts": "process.env.PAYMENTS_KEY" }, registry, exceptions, doc)], ["The mail code deleted", check({ "src/db.ts": code["src/db.ts"], "test/setup.ts": code["test/setup.ts"] }, registry, exceptions, doc)], ["The test seed removed", check({ "src/db.ts": code["src/db.ts"], "src/mail.ts": code["src/mail.ts"] }, registry, exceptions, doc)], ["An exception with no reason", check(code, registry, [{ ...exceptions[0], reason: "" }], doc)], ["ENV.md edited by hand", check(code, registry, exceptions, doc + "\n- DEBUG: turns on logging")], ["The scan found no files", check({}, [], [], "")],];for (const [name, problems] of runs) console.log(`${name}:\n ${problems.length ? problems.join("\n ") : "registry ok"}`);Run with Bun, a JavaScript runtime, it prints:
As it stands: registry okA new read with no row: src/pay.ts reads PAYMENTS_KEY, which has no row. Add one to the registry.The mail code deleted: MAIL_FROM is in the registry but nothing reads it. Delete the row.The test seed removed: test/setup.ts no longer reads TEST_SEED. Delete the exception.An exception with no reason: The exception for TEST_SEED in test/setup.ts has no reason. Write one.ENV.md edited by hand: ENV.md differs from the registry. Regenerate it; do not edit it by hand.The scan found no files: No source files found, so nothing was checked.Where the plain form falls short
The plain form is a list, sometimes typed, that people are asked to keep up to date. These are the ways I've seen it go wrong.
- Most of the real things are unlisted. A row is rarely added when no check asks for one. The 295 missing names above are that.
- The list holds things that no longer exist. A row for code that was deleted reads as fact. Failing on a row nothing uses removes it.
- A missing row reaches production. I've seen one environment never given a setting the code needed. Nothing compared what the environment had with what the code read, and it showed up as an error in front of users.
- An exception outlives its reason. The code it excused goes, and the exception stays to hide the next real case in the same file. Failing a stale exception closes that.
- A check passes while empty. A scan that finds no files reports no disagreement. It has to fail.
Trade-offs
- Every new thing needs a row. That is the point, and it is also friction. Some of the registries I keep run to a couple of thousand lines.
- The scan matches text. It knows a file reads a name, not why. Names built while the program runs cannot be read from the source at all. Count those per file and hold the count where it is.
- A reason can be a bad reason. The check tests that one is written, not that it is true.
- It can be the wrong tool. If a registry only copies facts that already live in one place, it is a second list to keep, and it should go.
When to use it, and when not to
It suits a kind of thing a script can find in the source, that is spread across many files, and that people need described in one place: environment variables, log events, calls to outside services, screens. It is not worth it for a handful of items that live in one file already.
Example. The two-way check, on GitHub
A draft skill for this pattern
A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/two-way-registry/. It is a draft, and I haven't tried it on anyone else's project yet.
---name: two-way-registrydescription: Use when a codebase has a kind of thing with no single home (environment variables, log events, model calls, screens, feature flags) and a hand-kept list of them has drifted. Keeps one typed list and checks it against the code in both directions.---
# Two-way registry
A registry is one typed file that lists every instance of one kind of thing.A list nobody checks is just a document, and its types make it look truer thanit is. The check has to fail both ways.
## Before you start
1. Choose one kind of thing that a script can find in the source: a function call, a naming pattern, a database column.2. Check how far the existing list has drifted. That number is the case for doing this.
## Build it
1. The registry file holds names and facts, never values. Nothing at run time should read it, so editing it cannot change what the product does.2. The check finds every use in the source by itself. Nobody keeps a list of what to check, so a new use fails until it gets a row.3. Fail on a use with no row, and on a row nothing uses. The second half is what keeps the list short enough to read.4. Exceptions are rows in a named list beside the registry: file, name and a written reason. Fail on an empty reason, and fail on an exception whose use has gone.5. Generate any page people read from the registry, commit it, and fail when the committed page differs from a fresh render.6. Fail when the scan finds no source files.7. Write every message as the next step: "Add a row", "Delete the exception".8. Run it where it can block a change, and again before each release, against the version of the registry being released.
## Prove it can fail
Cause each failure once: add a use with no row, delete the code behind arow, remove an excepted use, empty a reason, hand-edit the generated page.Watch each fail with its message, then undo it.
## What it does not do
The scan matches text. It knows a file reads a name, not why. It checks thata reason is written, not that it is true. Names built at run time cannot beread from source; count those per file and hold the count where it is.