A ledger of AI tools and building sites for overseas traffic.

Home / Workflows & MCP / How to Write CLAUDE.md: Handing Project Common Sense to the Model

How to Write CLAUDE.md: Handing Project Common Sense to the Model

It's not documentation — it's context reread every session. Writing too much is the same as writing nothing.

Oct 3, 2026 3 min read naket.top Updated 2026-10-09
How to Write CLAUDE.md: Handing Project Common Sense to the Model

CLAUDE.md gets read into context at the start of every session. That means every line of it burns tokens, and it means the more verbose it is, the easier it is for the rules that actually matter to get ignored.

Only four kinds of content

  1. How to run it: start command, test command, ports
  2. What not to touch: directories that must not be modified, files that must be kept
  3. Conventions: naming, commit format, the parts of code style where "leaving it out causes mistakes"
  4. Known traps: those two or three places that look safe to change but will actually break

Everything else (architecture notes, design philosophy) goes into the README — don't stuff it in here.

Keep it under 100 lines

Past 100 lines, the model starts losing the second half. My actual file is 40–60 lines, all short sentences and commands.

A workable skeleton

# Project
PHP 8.5, no Composer. Entry point index.php, routing in router.php.

# Getting it running
php -S 127.0.0.1:8090 router.php
After changing templates you must run php bin/cache-clear.php

# Do not change
- The md files under content/ are content; don't rewrite them to "optimize"
- Keep .htaccess in sync with nginx.conf.example

# Conventions
- No business logic in views
- Adding a category means changing both config and locales

# Known gotchas
- localhost:8090 hits Docker, so you must use 127.0.0.1
- If the cache isn't cleared you'll see old pages

"Don't" works better than "should"

The model ignores things like "prefer PSR-12"; it obeys prohibitions like "no business logic in views". The reason is that the former has no clear criterion for judgment.

Write every rule as a sentence whose right or wrong can be judged: if it can be verified, it will be followed.

A maintenance habit

Every time the model makes the same mistake twice, add that rule. CLAUDE.md is grown, not written in one sitting.

Why prohibitions work

The model has no criterion for "suggestions", but it does for "prohibitions": Don't modify content/ is decidable, keep the code clean is not. When writing a rule, ask yourself: can this be verified by a machine?

Three counter-examples

  • "Watch performance" — can't be verified, same as not writing it
  • "Follow best practices" — each model will interpret it its own way
  • "Code should be elegant" — a subjective word

Replace them with: "no more than 3 DB round trips per query", "new endpoints must have a timeout", "no SQL in views".

Update cadence

CLAUDE.md isn't documentation, it's an incremental patch. Every time the model makes the same mistake, add a line. After three months it naturally converges to a few dozen lines, all of them traps you actually stepped in.

In one line

Documentation written for other people aims at completeness; context written for a model aims at accuracy. Few and accurate beats complete and vague.

One more lesson: use absolute paths in CLAUDE.md. Relative paths depend on the current working directory, and the moment the model runs from a subdirectory it can't find the file and starts guessing.

CLAUDE.mdcontextengineering habits

Further reading

Claude Code documentation ↗