Quick context: I write a context file for almost every project before an AI coding agent (Claude Code, mostly, sometimes Codex or Gemini CLI) touches the code. Going in, I assumed I'd converged on a template somewhere along the way. Same shape, reused each time, agent behaves consistently across projects.
So I pulled four of these files from four different projects and ran the numbers instead of trusting the assumption.
The numbers
| Project | File(s) | Lines | Bytes |
|---|---|---|---|
| A system that takes real, irreversible actions on my behalf | CLAUDE.md |
130 | 7,413 |
| SparkyFitness | CLAUDE.md |
1 | 15 |
| SparkyFitness |
AGENTS.md (delegated to) |
152 | 11,077 |
| A pre-product research project | CLAUDE.md |
42 | 1,754 |
| A weekend hackathon deck | PRODUCT.md |
53 | 3,786 |
| A weekend hackathon deck | DESIGN.md |
183 | 14,540 |
SparkyFitness's CLAUDE.md is one line: See @AGENTS.md. Fifteen bytes. The hackathon onboarding deck doesn't have a CLAUDE.md at all: its PRODUCT.md/DESIGN.md pair came out of a design tool's own generated schema, not a personal convention I wrote. Fourteen thousand five hundred forty bytes on the DESIGN.md side alone.
Nobody scales a template down to fifteen bytes. That's not a smaller version of the same document. It's a different decision: this project didn't need the thing I built for the last one.
What actually repeats (it's not the file)
Four instincts show up in all four projects, at wildly different amounts of ceremony:
Lock decisions explicitly. An agent with no memory of your last session treats every choice as live unless you tell it otherwise. The pre-product research project states four settled decisions under a header that says exactly what it means: "Settled decisions — not open for reinterpretation." The system that takes real, irreversible actions on my behalf locks an entire safety posture under "Core Rules (Non-Negotiable)," including a flat "never invent companies, titles, metrics, skills, projects, or achievements." Same instinct, different amount of weight, because the two projects have completely different amounts riding on the decision staying locked.
State non-goals, with a named escape hatch. Agents are helpful by default, and helpful without a boundary turns into scope creep. The pre-product research project names three excluded features with a reason for each, then gives the agent a specific instruction instead of a vague warning: "When something looks like the obvious next step and isn't on the capability list above, ask first." SparkyFitness's product spec does the same job in four words: "What V1 is NOT."
Require verifiable, recorded completion. "The script ran" is not evidence. The system that takes real, irreversible actions on my behalf states it with teeth: "No manual 'the script ran' acceptance," with a requirement to record acceptance results in the commit message. SparkyFitness ties the same bar to CI instead of inventing new process, and its ticket tracker held the line even when it would've been easy not to: one ticket sat at TODO after later commits touched the same area, because the actual bar hadn't been cleared yet. A bar that always says yes isn't a bar.
Delegate to one living source, correct it in place. Duplicated context eventually disagrees with itself. SparkyFitness's root
CLAUDE.mddelegates entirely toAGENTS.md, which states its own routing rule: "Package-level guides win... Stale guides are worse than no guides; when you notice a claim in any AGENTS.md that contradicts the code, fix the guide as part of your change." I went looking for duplication in that project's three separate coding-agent configs (.claude/skills/,.agents/skills/, a Gemini config), expecting to find three copies of the same instructions. They're not copies: the.claude/skillsfiles are one-line stubs pointing at the canonical body in.agents/skills. Same pattern, one directory deeper.
The proof-of-judgment detail
The system that takes real, irreversible actions on my behalf also shows the "correct in place" half of instinct 4 with a dated artifact: an old autonomous-submission policy, struck through rather than deleted, with a note on why it's no longer policy. That's a separate story with its own stakes; here it's evidence for one narrower point: "fix the guide as part of your change" isn't aspirational language in that project. It has a date on it, and it's still legible in the file.
What this isn't
Not a framework. No name, no version number, no diagram I reuse. It's four questions I ask myself every time I sit down to write one of these files: what's actually settled, what's explicitly out, what does "done" have to prove, and where does this project's truth live so nothing else has to repeat it. The answers come out a different length every time, because the questions are the same but the projects aren't.
If the four files had looked alike, that would've been evidence of a template, not of judgment. A 969x spread in byte count, on the same category of document, is the evidence that a template didn't happen here.
Top comments (0)