Originally published at https://aicoding-guide.com.
CLAUDE.md and AGENTS.md are not a revival of the design document. The one thing they have that a design doc never did is being read every time — and in exchange they carry a length ceiling and a merge order. Written in the shape of a design document, they work less well, not more.
That is not an impression. It falls out of the loading rules both tools document.
Key point
The claim
- "Read every time" is the property a design doc could never have, and it is genuinely new
- Being read is not the same as being followed, and the docs say so outright
- The length ceiling makes them a poor home for a design document's content
"Read every time" is the part design docs never had
Design documents stop being read mostly because nothing prompts anyone to open them. Context files differ here: the reading is built into the mechanism.
On the Claude Code side:
Claude Code loads
CLAUDE.mdandCLAUDE.local.mdfrom your current working directory and every directory above it.
Codex goes further and rules out a stale copy entirely:
Codex rebuilds the instruction chain on every run (and at the start of each TUI session)
followed by "so there is no cache to clear manually". No old version lingers — one of the classic routes by which a design document goes out of date is closed off structurally.
When an update takes effect is specified too. In Claude Code, one level survives compaction:
Project-root CLAUDE.md survives compaction: after
/compact, Claude re-reads it from disk and re-injects it into the session. Nested CLAUDE.md files in subdirectories and rules withpaths:frontmatter load again on demand.
Instructions given only in conversation are summarized away; what lives in a file is re-read from disk. The line between "Claude forgot what I told it" and "Claude still has it" is drawn at whether you wrote it down. For the levels and where files go, see How to write CLAUDE.md and its three levels.
Being read is not being followed
This is the main reason it does not qualify as a revival. The Claude Code docs say it directly, in their troubleshooting section:
CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.
It arrives as a user message after the system prompt. Claude tries; nothing guarantees compliance. In the section on organization-wide deployment, the boundary with enforcement is sharper still:
Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer.
The same page names where certainty lives: "To block an action regardless of what Claude decides, use a PreToolUse hook instead."
Design documents had this property too. "Don't call across this layer" was enforced by review or a linter, never by the document. That structure has not changed. What changed is that the enforcing layer now exists as settings files and hooks — see Designing allow, deny and hooks is becoming the new code review.
The length ceiling changes what the document is
A design document was allowed to be long. Context files are not.
| Tool | The constraint |
|---|---|
| Claude Code | "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence" |
| Codex | "Codex skips empty files and stops adding files once the combined size reaches the limit defined by" project_doc_max_bytes (32 KiB by default) |
Claude Code frames it as degradation — long files get followed less — and Codex frames it as truncation, dropping later files once the cap is hit. Different mechanisms, same design intent: length kills content. For how the Codex cap behaves, see Codex reads only 32 KiB of AGENTS.md by default; for the 200-line guidance, see CLAUDE.md length and the 200-line guideline.
Contradictions are handled differently from a design doc too. The docs say: "if two instructions contradict each other, Claude may pick one arbitrarily." In a design document a contradiction got noticed by a human reader and became a question. Here it goes unnoticed and one side wins.
Merge order is fixed as well. Claude Code orders "content... from the filesystem root down to your working directory", with CLAUDE.local.md appended after CLAUDE.md within each directory. Codex likewise "concatenates files from the root down, joining them with blank lines." Because later wins, where you put a line carries meaning. For how the tools differ in loading, see CLAUDE.md, AGENTS.md and GEMINI.md differ only in how they load.
Objections and limits
Four conditions make this claim fail.
On a small project the constraints never bite. If you are nowhere near 200 lines or 32 KiB, dropping in a summary of your design doc costs nothing. The argument applies to monorepos and multi-team setups where context files grow.
It depends what "revival" means. If it means a document that actually gets read came back, then part of it did. What I am rejecting is the reading that a place to put design-document content came back. With the first claim I have no quarrel.
The specifications can change. Every constraint above is from the official documentation as of 2026-11-20. If a path into the system prompt appears, the "no guarantee of compliance" premise changes. Claude Code already has a separate route for that, --append-system-prompt, documented as being for instructions you want at the system prompt level.
There is a separate place for what the machine writes. Claude Code has auto memory, and the docs' comparison table splits "Who writes it" into You for CLAUDE.md and Claude for auto memory. Lumping everything together as "files the machine reads every time" misses that split: what people write and what the machine records now live apart.
What carries over from a design document, and what does not
Given the constraints, the split is clear.
What carries over is decisions you can state briefly: naming conventions, branch workflow, how to run the tests, which directories not to touch. Each fits on a line, and being read repeatedly is exactly what makes it work.
What does not carry over is rationale: why this architecture, which alternatives were rejected, what constraints applied. That material is long, does not need re-reading every session, and crowds out the adherence of everything else. Keep it in an ADR or a design document and reference it from CLAUDE.md.
The docs provide a home for the middle ground: "Move instructions that matter for only part of the codebase into path-scoped rules, which load only when Claude works with matching files." That separates what should always apply from what should apply only when a matching file is touched.
So design documents are not going away. What went away is the assumption that one document is enough.
Summary
- The one difference from a design doc is being read every time; Codex states there is "no cache to clear manually"
- Being read is not being followed: CLAUDE.md arrives as a user message, with no guarantee of strict compliance
- There is a length ceiling: adherence drops past 200 lines in Claude Code, and Codex truncates at 32 KiB
- Contradictory instructions go unnoticed by any human, and one side is picked arbitrarily
- Short decisions belong in context files, rationale belongs in a design document; only "one document is enough" died
Top comments (0)