Write the constitution
The file the agent reads before it does anything, and how to keep it honest
Claude Code reads a file called CLAUDE.md. Codex reads AGENTS.md. Both read it before your first message, every session, without being asked.
That file is the only thing that survives between sessions on its own. Treat it as a constitution: dense, factual, and amended only when something breaks.
Layers
One file is not enough once you have more than one project. The layout that has held up:
| Layer | Lives at | Holds | |---|---|---| | Global | your home directory | Who you are, the machines, the vault, filesystem conventions, hard don’ts | | Project | repo root | Commands, architecture, deploy, worktree convention, project-specific traps | | Area | a subdirectory | The contract for that area, such as “every app in here matches one of four archetypes” | | App | one app’s folder | Facts about this one thing, plus a state file with the next step |
The agent reads global first, then whatever is closest to where it is working. Lower layers add specifics; they do not restate the upper ones. When a worktree’s copy of the project file lags behind the main checkout, the main checkout wins, and the file says so.
What goes in
Rules with their why. A bare rule gets followed until the first edge case; a rule with a reason gets followed intelligently. Compare:
Never
git add -A.
with
Never
git add -A. Two production regressions came from staging more than the intended scope: a tile grid collapsed, and an unrelated feature shipped inside a fonts commit. Stage files by name.
The second one also teaches the agent what to do when it sees a similar situation the rule did not anticipate.
Other things that earn a place: the exact commands to check and deploy, where the source of truth for ports and hosts lives, which secrets prefix is allowed, and the short list of things it must never do without asking.
What stays out
Anything the repo already says. Do not describe the directory structure; the agent can list it. Do not restate git history. Do not write aspirations (“we value clean code”). Every line the agent reads costs context on every turn of every session, so a constitution that is twice as long as it needs to be is a tax on everything.
Keep one source of truth
Facts that change, such as ports, hosts, app lists and routes, should live in one structured file the tooling reads, not in prose. The constitution points at that file; it does not copy it. The port table on this machine went stale within weeks of being hand-written into a markdown file. The fix was a generator that rewrites the table from every app’s manifest, and a check that fails when they disagree.
Two agents, one set of facts
Claude Code and Codex read different filenames, and keeping two files in sync by hand fails the same way the symlink did. Keep project facts in one canonical document and generate the other, or keep AGENTS.md short and have it point at the canonical file. What matters is that a fact is written once.
Amend on incident, not on inspiration
The constitution grows by one paragraph each time something goes wrong twice. Not on the first occurrence, which might be noise, and not because a rule sounds wise. A file that only contains rules that were paid for stays short and gets believed.
The constitution is memory for a colleague who forgets. Keep it dense, causal, and amended only by incident, and it will do more for your output than any prompt you will ever write.