The file is called CLAUDE.md. It lives at the root of the repository and is loaded automatically at the start of every AI session. It is 182 lines long. Every line represents something the AI doesn’t know — or would get wrong if it tried to guess.
Some of those lines are rules, others warnings, some even descriptions of patterns that exist in this codebase and nowhere else. Together they are not documentation. They are a curated history of failures.
The commit that changed how I work
On 7 March 2026, I created CLAUDE.md and committed it with the message “Claude init and Lesson Tweaks.”
The repository had been in version control since September 2025. The system it tracks had been running in production for years before that — a learning management platform, one developer, no framework, no build step, no ORM, no test suite. A decade of accumulated decisions, most of them correct, some of them now fossilised into the codebase in ways that look like mistakes to anyone who didn’t make them.
When I introduced Claude Code as a regular working tool, I immediately ran into a problem. The AI was capable and fast, but it kept making suggestions that were subtly wrong for this specific system. Not wrong in general. Wrong here. Suggestions that would have worked on any modern codebase were quietly incompatible with constraints that had evolved over years.
The constraints weren’t documented. They were just known.
Introducing AI to a legacy codebase is not a technical problem. It’s an epistemological one.
The epistemological problem
The AI doesn’t know what it doesn’t know. It has no way to:
- distinguish between “this pattern is absent because it wasn’t needed” and “this pattern is absent because it would break something.”
- know that a particular function name looks valid but doesn’t exist.
- know that HTML attributes written inside PHP double-quoted strings will blank the entire site with no error message
— not because that’s obvious, but because this is the kind of failure that only reveals itself the first time it happens.
CLAUDE.md is the mechanism for transferring that institutional knowledge. Not all of it — 182 lines isn’t a decade of decisions. It’s the decisions that would cause problems if the AI didn’t know about them.
Two rules and what they represent
The rule that comes first in CLAUDE.md:
> Never put unescaped double quotes inside a PHP double-quoted string. HTML attributes like `scope=”col”` inside `echo “…”` cause a fatal PHP parse error that blanks the entire site with no logged error.
This rule exists because on 25 April 2026, three library files had exactly this problem. The site went blank on localhost and production simultaneously. No error? 500 page? Log entry? Just silence. The production server has `display_errors` off — correct, you don’t want error details visible to users — but the consequence is that a fatal parse error produces nothing at all.
Debugging started from first principles. Was Apache running? How was PHP responding? Is it one file or all files? The cause was a single missing backslash in three places. The fix took minutes. Finding it took longer.
One rule. The incident that produced it took the whole platform down.
The second rule:
> The function `fn_General_LoadField` does NOT exist. The correct function is `fn_Gen_LoadField`. Using the wrong name causes a silent fatal error.
This one is subtler. The AI, working from naming patterns in the codebase, constructs plausible function names. `fn_General_LoadField` looks right. It follows the convention. It doesn’t exist. There is no error that tells you this — the call fails silently.
These two rules are representative. Most of CLAUDE.md follows the same structure: here is a thing that looks reasonable but isn’t, here is what happens when you don’t know it, here is the rule.
What writing it reveals
There is a secondary effect I didn’t anticipate.
Writing CLAUDE.md forces a different quality of thinking about the system. “I know the constraints” and “I have written down the constraints” are not the same state. The first is knowledge. The second is clarity. The gap between them is significant — and crossing it reveals things that informal knowledge conceals.
When I try to explain a constraint clearly enough for an AI to apply it, I have to understand it precisely. Vague understanding doesn’t survive the attempt to make it explicit. The constraints that are hard to write down are usually the constraints that are poorly understood — which is exactly the right signal.
The document that briefs the AI also briefs the developer.
How to write your own
Consequently if you have a legacy system and want to use AI tools on it, the starting point is not the tool configuration. It’s three questions you ask for every rule you add:
What would go wrong without this rule? If the answer is nothing, the rule doesn’t belong. CLAUDE.md isn’t comprehensive documentation — it’s a warning label for things that actually cause problems.
What already went wrong? The most reliable source of rules is the incident that produced them. After the blank-page incident, the rule was obvious. Before it, the risk was invisible.
What does the AI have no way to know? Modern AI tools are trained on modern codebases. If your system predates the patterns the AI expects — no framework, hand-written SQL, functions that exist only in this repository — the AI has no prior to draw on. Those are the gaps the document needs to fill.
Furthermore the document doesn’t need to be complete before the first session. It needs to be accurate. Start with the three most dangerous things the AI could get wrong, and add a rule every time something surprises you.
Nine years of decisions, accumulated in a system that runs in production today, transferred to an AI in 182 lines.
Not all of it. Just the failures.
That turns out to be enough.
