One artifact compressed the fix-to-feature ratio across every project I measured. It has zero application code.
My booking system's git log has a visible seam.
Commits 1 through 12: migration cascades, non-conventional messages, infrastructure that got built and thrown away. Seven commits on January 14 alone, six co-authored by Claude, none following conventional format. Then commit 13, 3e00a40, January 22. A 189-line markdown file called CLAUDE.md. Commits 14 through 69: 100% conventional format. Cleaner feature boundaries. Fewer fix-after-feature patterns.
The inflection is visible in the commit history.
That file contains zero application code. No functions, no routes, no tests. It describes the project's conventions, structure, and constraints. The AI reads it at the start of every session. Across 7 projects, the dividing line was always the same: the moment I wrote the instruction file.
what 438 lines buys you
My infrastructure project's CLAUDE.md was longer and more revealing. 438 lines. It included a "Session Bootstrap Checklist" and a "Top 10 Failure Modes" table, preloading the AI with troubleshooting knowledge from previous sessions.
Before that file existed, every session started cold. Inconsistent message format: "Fix...", "Add...", "Improve..." The AI rediscovered the project structure each time. After commit 17 of 21, when I added the file, sessions started with full context. Conventional commits from the first message.
The most productive thing I did on that project was write a file the AI reads before every session.
In my OpenClaw config project, the same story. A 148-line CLAUDE.md added around commit 5 of 18. The first 4 commits required 3 consecutive fixes. After the instruction file, the feat-to-fix ratio inverted. Features landed clean.
what goes in it
A CLAUDE.md is a contract between you and the AI. It's not documentation for humans reading a README. It's the set of instructions the AI loads before it writes a single line of code.
Project scope and file structure. What this project does, where the code lives, what each directory is for. The AI stops guessing and starts navigating.
Commit conventions. I prescribe conventional commits (feat:, fix:, docs:). Before this rule, the AI wrote freeform messages. After: 100% compliance. Permanently.
Common gotchas. My booking system's file listed four: enum case sensitivity for PostgreSQL, date validation with a 365-day max range, CORS configuration, and auth context using is_superuser instead of a separate role. Each one was a bug the AI introduced. I codified the fix.
What NOT to do. The most valuable section. "Don't generate scripts from scratch when originals exist." "Don't add comments on obvious code." "Don't create community docs until there are contributors." Every line maps to a mistake.
Line 187 of my booking system's CLAUDE.md: "No Laziness: Find root causes. No temporary fixes. Senior developer standards." That rule exists because the AI was producing surface-level fixes. I wrote the correction once. It stuck.
What doesn't belong: general-purpose documentation. API references. User guides. A CLAUDE.md should only contain instructions that change the AI's behavior.
A minimum viable version: 50 lines. Project scope, file structure, commit conventions, and your top 3 "don't do this" rules.
the feedback loop nobody designed
Traditional documentation has a fatal flaw: nobody reads it. I've written READMEs that went stale within a week. Architecture docs that described a system three refactors ago. Nobody forces anyone to keep them current, so they become fiction.
CLAUDE.md has a built-in reader. The AI reads it every session. Stale instructions produce broken output: wrong commit format, wrong file structure, wrong deployment steps. The break is visible, and it points back to the stale instruction.
My OpenClaw infrastructure project has two CLAUDE.md files totaling 300 lines across 4 repos. They were the most reliable documentation in the project. Not because I'm disciplined about docs. Because the feedback loop ran automatically.
CLAUDE.mdfiles are more accurate than the READMEs because they're read by the AI on every interaction. Stale instructions break the AI, creating a natural pressure to keep them current.
This is the first documentation format I've used where drift is immediately visible. The AI is the reader, the output is the quality signal, and the human corrects the docs when the signal degrades. I've worked with wikis, Confluence, README-driven workflows, architecture decision records. None of them had a built-in reader that broke visibly when the docs went stale.
memory files: what the AI learned the hard way
CLAUDE.md is what the AI should always know. Memory files are what it learned this session.
My OpenClaw config project has a .claude/memory/ directory with files like docker-patterns.md and openclaw-skills.md. The entries are specific:
sqlite-vec uses L2 distance, NOT cosine
node:22-bookworm-slim does NOT include Python
Volume mount shadows COPY — seed files at startup instead
pip install --break-system-packages required on Debian Bookworm
The sqlite-vec entry came from a debugging session where similarity search returned wrong results. The node:22-bookworm-slim entry came from a Docker build that failed because the AI assumed Python was included. Each one was expensive to learn and free to remember.
Each one was written to disk once. The AI never repeated any of these mistakes in subsequent sessions.
the negative space
My Docker config repo is the only project I built without a CLAUDE.md. Eight commits across three days. The patterns are predictable.
Every RUN instruction in the Dockerfile has a comment above it. Shell scripts have triple-hash dividers describing each section. The skills manifest comments explain what yt (YouTube) and system-monitor do, information available from the tool names alone. Classic AI pattern: explaining the obvious because nobody told it to stop.
The repo shipped with a CONTRIBUTING.md near-identical to GitHub's template and a verbatim CODE_OF_CONDUCT.md on day one. Zero contributors.
Config files are suspiciously clean. Every value sensible but generic. No oddball settings from troubleshooting. No commented-out experiments. No evidence of iteration.
Without a
CLAUDE.md, you're the context window. Every new session starts from scratch, and the AI re-learns your conventions through trial and error.
I paid the context cost on every session with that project. The AI had no record of my preferences, my conventions, or what to avoid. So it defaulted to what it knows: verbose comments, boilerplate documentation, generic configuration.
the industry figured this out independently
The pattern isn't unique to my repos. Multiple practitioners converged on the same solution without coordinating.
Mitchell Hashimoto calls it "harness engineering." Step 5 of his six-step AI adoption journey: "anytime an agent makes a mistake, engineer a solution so it never happens again." His Ghostty project has an AGENTS.md where every line maps to a fixed bad behavior. He arrived at the same mechanism I did, from a completely different codebase, using different AI tools.
Peter Steinberger's "just talk to it" workflow sounds like the opposite of instruction files. It works because his agent file carries hundreds of encoded decisions. He iterated heavily on the file to get clean commit history. The conversational approach functions precisely because the file carries the context that early-stage projects lack. This is the maturity curve from part 1: spec-driven and conversational aren't opposites. They're different stages.
Heinrich (@arscontexta) maintains roughly 2,000 lines of structured AI instructions, continuously refined. His philosophy: "depth over breadth. quality over speed. tokens are free." He's already pushing past the single-file model. His latest work argues for "skill graphs," networks of composable markdown files connected with wikilinks. No CLAUDE.md, then CLAUDE.md, then skill graph. The progression continues.
a16z names the primitive in their analysis of the AI dev tool stack: "natural language knowledge repositories designed purely for AI consumption" are "the birth of documentation for machines." They identified the format. What they didn't describe is the feedback loop that keeps these repositories accurate. That's the part you only discover by shipping real projects against real servers.
The YC CEO's CLAUDE.md goes further. It encodes an entire engineering process: architecture review, then code quality, then tests, then performance, as a mandatory sequence before writing code. Not just conventions. Engineering discipline, loaded into every session. A "staff engineer in a box."
Anthropic's Skills Guide, published February 14, 2026, runs 30+ pages and shifts the conversation from "prompt engineering" to "execution design." The platform vendor is now codifying what practitioners discovered independently.
CLAUDE.md, AGENTS.md, .cursor/rules, skill graphs. Different names, same instinct: a plain text file that persists context across AI sessions and improves with every mistake.
write it on commit 1
I added mine on commit 13, then on commit 17, then on commit 5. Every time, the inflection was immediate. Every time, I thought the same thing: I should have done this first.
A minimum viable CLAUDE.md takes 20 minutes:
- Project scope: what this is, what it does
- File structure: where things live
- Commit conventions: how to format messages
- Top 3 "don't do this" rules: your first debugging session will supply these
- Deployment workflow: what to check before shipping
Then update it every time the AI makes a mistake you've seen before.
CLAUDE.md captures what the AI should know. Memory files capture what it learned the hard way. Together they build institutional knowledge that doesn't disappear between conversations.
But some knowledge doesn't fit in a file. It comes from production failures, from integration bugs that surface weeks later, from the gap between what the AI generates and what actually runs. When the corrections accumulate faster than you can write them down, when the prompt itself evolves faster than the code, that's part 3.
Part 2 of a series on AI-assisted engineering. Part 1: "Your AI Productivity Metric Is a Lie" established the fix-to-feature ratio. Part 3: "The AI Doesn't Learn. The Prompt Evolves." explores what happens when the instructions outgrow a file. Part 4: "8 Tools in 12 Days" covers the memory layer.
Built in Porto. Data from real repos, real commits, real production servers.