LLM Best Practices

How to write a CLAUDE.md from scratch

4 min read

View markdown source

Overview

CLAUDE.md is the first file Claude Code reads on every session. A well-written file eliminates repeated context-setting, keeps the agent aligned with project conventions, and lets you brief it with short task descriptions instead of long essays. This guide covers the structure, the sections that matter, and the anti-patterns that cause drift. See claude-code for how the agent uses the file.

Prerequisites

  • A repository with a clear purpose and at least one defined workflow (build, test, deploy).
  • A text editor. CLAUDE.md is Markdown; no special tooling required.
  • 30 to 60 minutes to write the first version. Subsequent updates take 5 minutes each.

Steps

1. Open with a mission statement

The mission is one paragraph that answers: what does this repo do, who does it serve, and what does it deploy to. Be concrete. Avoid adjectives that do not carry information.

## Mission
 
Build and maintain `api.example.com`, a FastAPI service that serves product catalog data to the mobile app. Deployed to Fly.io via GitHub Actions. Source of truth for product, category, and inventory data.

2. Define the content or code schema

If the repo produces typed artifacts (pages with frontmatter, database records, API responses), document the schema. Claude Code writes to this schema; without it, the agent invents its own.

## Page schema (YAML frontmatter)
 
title, slug, category, tags, status (draft|stable|deprecated), last_updated, summary, related

Include field rules: what each field means, what values are valid, what case to use.

3. Document voice rules (for content repos)

List the non-obvious rules first. The obvious ones (correct grammar, no typos) do not need to be said. Document the ones that differ from defaults: banned phrases, structure patterns, tone.

## Voice rules
 
- Lead with the rule, then the rationale.
- No em-dashes. Use periods or commas.
- No slop preambles ("Let's dive in", "In today's world").
- Each H2 section opens with a rule statement, not a topic header.

For code repos, document style conventions not enforced by the linter: error handling patterns, naming conventions, module organization rules.

4. Draw the folder map

A brief tree of the project structure anchors the agent spatially. Include only directories; files are too granular and go stale faster.

## Folder structure
 
src/
├── routes/     # FastAPI route handlers; one file per domain
├── models/     # SQLAlchemy models
├── schemas/    # Pydantic response and input schemas
├── services/   # Business logic; no direct DB calls
└── tests/      # pytest test suite

5. Write a “How to add a thing” checklist

The most valuable section. A numbered checklist for the most common task in the repo: adding a page, adding a route, adding a feature. The agent follows this exactly.

## How to add a route
 
1. Create a handler in `src/routes/<domain>.py`.
2. Add the router to `src/main.py`.
3. Add a Pydantic schema to `src/schemas/<domain>.py`.
4. Write a test in `src/tests/test_<domain>.py`.
5. Run `pytest` locally; confirm it passes.

6. Add deploy and branch conventions

One paragraph each on how to deploy and how branches are named. The agent needs this to write correct PR descriptions and CI configs.

## Branch policy
 
Feature work on `feat/<name>`; hotfixes on `fix/<name>`. PRs target `main`. `main` deploys automatically to staging; production requires manual promotion in Fly.io.

7. Keep it under 300 lines

Past 300 lines, the file competes with the task context for model attention. If a section grows large, extract it to a linked file (docs/voice-rules.md) and reference it from CLAUDE.md.

Verify it worked

Open a new Claude Code session in the repo:

claude

Ask the agent to describe the project and how to add a new feature. If the answer matches the CLAUDE.md content without you prompting further, the file is working.

Common errors

  • Agent ignores the file: confirm CLAUDE.md is at the repo root (not in a subfolder). Claude Code looks for it at the root.
  • File exceeds context budget: trim to under 300 lines. Move long sections to docs/ and link them.
  • Schema section is ambiguous: agents infer missing fields. Every field that matters should have an explicit description and example.
  • No checklist section: agents improvise workflows without a checklist. Even a 3-step checklist eliminates the most common drift.
  • Rules contradict each other: review voice rules and schema rules together. Contradiction causes unpredictable output.

Graph View