CLAUDE.md Is the New README: How to Write Project Instructions Your AI Agent Will Actually Use

Open almost any repo in 2026 and you will find two files at the root that matter. One is README.md, which is for humans who might use or contribute to the project. The other is CLAUDE.md, which is for the AI agent that is about to modify the project.

The second file is less than a year old as a widely-adopted convention, and most teams are writing it badly. Either they treat it like an afterthought — three bullet points and a prayer — or they copy a template that could describe any Next.js app and tells the agent nothing useful.

I write a CLAUDE.md for every codebase I touch as a fractional CTO. What follows is the template I use, section by section, with the mistakes I see teams make and the specific things that actually move agent quality.

Why this file matters more than your README

A README.md is read once by a human, who then builds an internal model of the project and keeps it in their head for weeks. A CLAUDE.md is read at the start of every single task, by an agent that starts fresh each time. It is the persistent memory the agent does not have.

When it is good, the agent behaves like a mid-level engineer who has been on the team for three months. When it is bad or missing, the agent behaves like a contractor who just opened the repo five minutes ago and is very confident about everything. You have met that contractor. You know how it ends.

The good news: writing a great CLAUDE.md takes about an hour and the ROI is absurd. Every subsequent task the agent runs is better. Every new engineer who joins reads it too. It is onboarding doc, style guide, and architecture summary in one file.

The eight sections I always include

I use the same structure on every engagement. Not because rigidity is a virtue, but because the sections map to the questions the agent keeps getting wrong when they are missing.

1. Project overview (3–5 sentences, no more)

What does this product do, who uses it, and what is the current stage. This is the "why" that contextualizes every decision the agent will make.

The mistake I see: marketing copy. "A revolutionary platform for..." No. Write it the way you would describe the project to a new senior hire in a Slack DM. Concrete, specific, honest about the stage.

A good example: "This is a B2B scheduling SaaS used by dental practices in the US. Currently 400 paying customers, pre-Series-A, 6 engineers. Core product is stable; most active work is on the reporting module and multi-location support."

2. Commands and environment

Every command a developer runs in a normal day. Dev server, tests, lint, typecheck, build, database migrations, seeds, deploy. Include the exact syntax, including any flags that matter.

If your project uses pnpm instead of npm, say so in letters three inches tall. Agents default to npm and will confidently break your lockfile.

3. Architecture (the actual architecture, not a diagram)

This is where most CLAUDE.md files collapse into "We use Next.js with Postgres." That tells the agent nothing. What you want is the opinionated shape of your codebase.

Things to include: directory structure and what belongs where, which modules are stable vs. actively changing, which parts of the code are shared vs. owned by one team, the data model at a conceptual level, the major external services and what they do.

A litmus test: if your architecture section could describe a generic Next.js app, rewrite it. The agent can read the package.json itself. It cannot read your team's decisions.

4. Code conventions and style

Not a 40-page style guide. The two or three conventions in your codebase that are non-obvious and that the agent would otherwise violate.

Real examples from my client repos:

"We do not use default exports. Every module exports named symbols."
"All database access goes through lib/db, never through the ORM directly from a route handler."
"React components live in components/ as folders with an index.tsx, a styles.ts, and a types.ts. Do not collapse these into a single file."
"Prefer Array.from over spread for iterables because we had a perf regression with spread in Node 20."

Notice these are all things the agent would not guess. That is the whole point.

5. Test strategy

What kinds of tests exist, where they live, how they are run, and what is expected when the agent writes new code.

Do you unit test? Integration test? Have a small E2E suite? Do you prefer table-driven tests, property-based tests, snapshots? Is there a pattern for mocking external services? Is there a test that takes 3 minutes and should be skipped in fast iteration?

Crucially: tell the agent what "I added tests" means on your team. Without that sentence, you will get one happy-path assertion and the agent will call it done.

6. Domain glossary

This is the most underrated section. Every real product has internal vocabulary that means something specific. "Account" vs. "Organization" vs. "Workspace" vs. "Tenant" are not interchangeable in your codebase, but the agent will treat them as synonyms unless you tell it otherwise.

List the 10–20 terms that matter. One sentence each. When a founder reads the finished document, they should recognize the language of their own product.

7. Things that look wrong but are intentional

My favorite section. Every codebase has three or four of these. The class that looks like it should be refactored but is touched by a customer-facing edge case. The duplicated code across two services that is duplicated on purpose because they are going to diverge. The "TODO: fix later" that is actually "TODO: never touch this."

Without this section, a helpful agent will "clean up" something load-bearing. With it, the agent understands that some ugliness is load-bearing ugliness and leaves it alone.

8. Out-of-bounds directories and files

Explicitly list the paths the agent should never modify without a human in the loop. Migrations, auth primitives, billing code, infrastructure-as-code, anything generated, vendored dependencies.

This is a safety control, not a hint. Make it visible and unambiguous.

What not to put in it

A few things I leave out on purpose.

Secrets and credentials. Obvious, but I see API keys in template files more often than you would believe. CLAUDE.md is checked into git. Treat it that way.

Deep tutorials. If your setup takes more than a page to explain, that page belongs in a linked doc, not in CLAUDE.md. Keep the file scannable.

Aspirational architecture. Write the system as it is today, not as you wish it were. The agent has to work on the real code, not the one from your dream roadmap.

Personal preferences that are not team norms. If three engineers prefer tabs and four prefer spaces, and you have not resolved that, do not sneak your preference into CLAUDE.md and call it a convention.

How long should it be?

Between 300 and 900 lines, in my experience. Shorter than that and you are leaving leverage on the table. Longer than that and you are pushing other important context out of the agent's working memory.

If your file is growing past a thousand lines, split it. Put the "things that look wrong but are intentional" section into a linked ARCHITECTURE.md. Keep the root file tight.

How to keep it alive

A stale CLAUDE.md is worse than no CLAUDE.md, because the agent will trust it.

Two habits I enforce:

Touching CLAUDE.md is part of any PR that changes a convention. If you change how tests work, you update the test strategy section in the same PR. Non-negotiable. I reject PRs that skip it.
Quarterly review. Once a quarter, the file gets a top-to-bottom read by a human. Remove the stale bits, add the new conventions that emerged organically, tighten the glossary.

Treat it the way you treat your linter config. It is infrastructure.

A quick before/after

Here is a section from a real client CLAUDE.md, rewritten. Original (what they had):

"We use Next.js 15 with TypeScript and Postgres. Run npm run dev to start. Tests are in the tests/ folder."

Rewritten:

"Next.js 15 App Router, TypeScript strict mode, Postgres 16 via Drizzle ORM, deployed on Fly.io. Dev: pnpm dev (Turbopack). Tests: pnpm test runs Vitest unit tests; pnpm test:e2e runs Playwright (slow — skip during iteration). Schema lives in db/schema/; migrations are generated via pnpm db:generate and must be reviewed by a human before commit. The lib/billing/ directory is off-limits without PR review from @craig."

Same basic information, radically more useful. The rewritten version answers the three questions the agent will otherwise get wrong: which package manager, which test command to use during iteration, and which directory not to touch.

Counterpoint: is this just prompt engineering in a fancy hat?

Sort of, and I do not care. The name matters less than the discipline. A well-written CLAUDE.md is a project-level prompt that your whole team benefits from instead of re-typing into a chat window ten times a day. That is the entire value.

The people rolling their eyes at "prompt engineering" in 2026 are the same people who rolled their eyes at "writing good commit messages" in 2012. It is a small habit with a large compounding return. Just do it.

Your next hour

If your repo does not have a CLAUDE.md, open the editor and draft one using the eight sections above. Do not optimize it. Do not polish it. Just get a real version in the repo today. You can iterate later.

If your repo has a CLAUDE.md that fits in half a screen, treat it as version zero and expand it. The sections it is missing are probably the ones the agent keeps getting wrong.

Where I help

When I start a fractional CTO engagement, writing or rewriting CLAUDE.md is one of the first things I do — usually in the first week, alongside a quick engineering audit and a plan for the next 30 days. It is a small artifact with outsized leverage, and once it exists, every subsequent piece of AI-assisted work on the codebase gets better.

If your team is using AI coding tools but is not getting the speedup you expected, there is a very good chance the root cause is not the tool — it is the missing context. Let's talk about your codebase. I will tell you what is working, what is not, and what I would change in the first two weeks.