Your First CLAUDE.md

Your CLAUDE.md is the persistent system instructions for a project that a coding agent reads at the start of every session. Without it, the agent re-asks the same context questions every time and slowly drifts away from your conventions. With it, the agent has a contract.

Most CLAUDE.md files I see in client repositories are bloated, contradictory, or ignored by their own agents. The same project will have a four-page CLAUDE.md and a senior engineer complaining that "Claude never remembers our patterns." Both things are true at the same time, and both have the same cause. The file was written once, never maintained, and is now too long for the agent to take seriously.

This guide is the working pattern I would set up if I were starting a project today.

Why CLAUDE.md exists

It is read at the top of every session.

It is a contract between you and the agent: here is what this project is, here is how we work, here is what you should never do.

Without it, you spend the first fifteen minutes of every session re-explaining the same context. The agent guesses. The guesses drift. The codebase drifts.

What goes in it

Seven sections, in this order, in plain prose.

1. Context. Two paragraphs. What is this project, who is it for, what is the headline goal, what has shipped, what has not. Not a marketing description. A working brief.

2. Stack. The runtime, framework, language, key libraries, testing framework, deployment target. One line each.

3. Conventions. Code style decisions worth writing down. Naming patterns. File structure rules. Error handling philosophy. Comment style. Test patterns. Be specific. "We prefer functional components" beats "follow React best practices."

4. Domain knowledge. The vocabulary, business logic, and regulatory constraints that someone outside the project would not infer from the code alone. If you work in healthcare, write down what HIPAA actually means for this codebase. If you work in defence, write down what data classification applies. If you have a domain model with non-obvious rules, write them down.

5. Hard rules. Things the agent should never do. "Never commit directly to main." "Never call the production API from local dev." "Never log PII." Hard rules should be short, absolute, and rare. If you have more than ten, the file is becoming wishful thinking.

6. Workflow. How to run tests. How to start the dev server. How to deploy. How to roll back. The five commands that matter most.

7. Plain Language and Hypothesis Discipline. The addendum you will find at the bottom of this page. Force the agent to enumerate options, state assumptions, self-critique, and calibrate confidence before acting. This is the single most useful section for keeping the agent honest. Copy it in verbatim.

What doesn't go in it

API keys, tokens, or credentials. Use environment variables. Reference them in CLAUDE.md by name only.

A complete feature list. Use a backlog file. CLAUDE.md is for conventions, not for tracking work.

Anything the agent can infer from the codebase. If your TypeScript config or your test files already show the pattern, you do not need to also write it in prose.

Personal preferences that belong elsewhere. "Always explain your reasoning" is a user-level instruction. Put it in your Claude Code config, not in the project's CLAUDE.md.

Long code examples. A two-line example of your error handling pattern beats a 50-line code block. The point of CLAUDE.md is to compress the project's conventions into prose. Examples belong in the actual codebase.

How long should it be

Under 1,500 words. The agent will read longer files but will not weight them as heavily. Each section above should be three to ten sentences. If a section runs longer, you are probably writing documentation rather than instruction.

The discipline of maintenance

Treat CLAUDE.md as living.

Update it after any major change to conventions, stack, or domain.

Review it monthly. If the agent is consistently making the same mistake, the answer is usually a missing or unclear line in CLAUDE.md. Add the line. Re-test.

When a new contributor joins the project, human or agent, CLAUDE.md is their first read. If they finish reading and still do not understand the project, the file is incomplete.

The starter file

A working CLAUDE.md template, fully annotated, is downloadable from this page. Start from it, replace the bracketed placeholders, delete what does not apply, commit it as the first file in your repo.

The agent prompt

You can also paste the following prompt into Claude Code, pointed at an existing project, to get a draft tailored to your codebase.

You are reviewing the codebase of [project name] to produce a working CLAUDE.md file.
Walk the repository and produce a draft CLAUDE.md with the following sections, in this order:


CONTEXT
Two paragraphs. What is this project, what is the headline goal, what has shipped, what has not. Infer from README, package.json, recent commits, and code structure. Mark anything you are uncertain about with [VERIFY].


STACK
The runtime, framework, language, key libraries, testing framework, deployment target. One line each. Inferred from package.json, lockfiles, configuration files.


CONVENTIONS
Code style decisions visible in the codebase. Naming patterns. File structure rules. Error handling philosophy. Test patterns. Be specific. If you see a pattern repeated three or more times, write it down as a convention.


DOMAIN KNOWLEDGE
Any vocabulary, business logic, or regulatory constraint visible in the code that someone outside the project would not infer. If domain context is missing, write a [VERIFY] note asking the user.


HARD RULES
Anything the codebase suggests should never be done. Look for comments warning "do not", error-handling patterns that imply a hard line, configuration that suggests environment boundaries.


WORKFLOW
The five commands that matter most. How to run tests, start dev, build, deploy, roll back. Inferred from package.json scripts and any CI configuration.


PLAIN LANGUAGE AND HYPOTHESIS DISCIPLINE
Include the addendum from aerosensei.com/foundations/your-first-claude-md verbatim.

Keep the total file under 1,500 words. Where you had to infer, mark [VERIFY] so the user can confirm before committing.
Output the draft as a single markdown file ready to commit as CLAUDE.md at the project root.