Claude md

Writing Effective CLAUDE.md Files

A CLAUDE.md is the context file Claude Code loads at the start of every session in a project. This skill captures the practices that make one productive instead of wasteful. Apply them whether you're authoring a new file, auditing an existing one, or trimming a bloated one.

The core mental model

A CLAUDE.md is a context injection file, not documentation. It is read into the context window every single session, so every line spends context-window budget that could otherwise go to the actual code. Treat it the way you'd onboard a new senior engineer: hand them the essentials, then point them to detailed docs when a task needs them — don't dump a 50-page manual on day one.

This single idea drives every rule below. When in doubt, ask: does this line earn its permanent seat in context?

Figure out the task first

Before writing anything, identify which job you're doing — they have different starting points:

• Authoring from scratch — start from assets/claude-md-template.md, then fill it using the project's real commands, structure, and conventions. Inspect the repo (package.json scripts, directory layout, lint config) rather than guessing.
• Auditing / reviewing an existing file — run it against the checklist at the end of this skill. Flag every line that fails "the test for every line," then propose cuts and restructuring.
• Trimming a bloated file — the file is too long if Claude starts ignoring rules in it. Move task-specific knowledge out into progressive-disclosure targets (see below) and delete anything self-evident.
• Setting up a monorepo — layer the files: shared conventions in the root, service-specific context in child directories (see hierarchy section).
• Agentic / long-running project — a production AI system, or any project worked across many sessions over weeks/months. The base rules still apply, but persistence across sessions, the harness pattern, and surviving compaction become central. Jump to "Agentic & long-running projects" below and read references/agentic-engineering.md.

Rule 1 — Keep it under 200 lines

The target is under 200 lines. Lean teams run as low as ~60. The practical ceiling is ~300 lines before Claude starts losing signal in the noise.

The test for every line: "If I remove this line, will Claude make mistakes?" If the answer is no, cut it. Length is not thoroughness here — it's dilution. A tight 80-line file outperforms a sprawling 250-line one because the important rules don't get buried.

Rule 2 — Include the right things, exclude the rest

The most common failure is treating CLAUDE.md like a wiki. Use this breakdown.

Include — things Claude can't infer and will get wrong without:

Content	Why it earns its place	Example
Project context (1–2 lines)	Orients Claude immediately	"SaaS doc-automation platform — Next.js, Express, MySQL"
Essential commands	Claude runs these exact strings	npm run dev, npm run test, npm run build
Architecture / directory map	Tells Claude where code lives	src/routes/ — API endpoints; src/models/ — DB models
Non-default conventions	Only rules Claude wouldn't guess	"Use Zustand stores, never Redux"
Common gotchas	Prevents repeated mistakes	"Always run sync-pricing before build"
Workflow rules	Can't be read off the code	"Branch naming: feat/JIRA-123-description"

Exclude — things that waste tokens or go stale:

Content	Why it doesn't belong
Standard language conventions	Claude already knows idiomatic TypeScript/Python/etc.
Detailed API documentation	Link to it via @imports instead
Code style a linter enforces	Don't send an LLM to do a linter's job
File-by-file codebase descriptions	Claude can read files itself
"Write clean code" platitudes	Self-evident — pure token waste
Frequently changing information	Goes stale, then actively misleads

The unifying test: if a linter, the type system, or Claude's general knowledge already covers it, leave it out. Reserve the file for the project-specific knowledge that lives only in your team's heads.

Rule 3 — Follow the WHY / WHAT / HOW structure

Order the file like a briefing for a senior engineer joining the team: context first, then commands, then structure, then conventions, then references. Each section should be scannable — Claude should be able to extract exactly what it needs without reading every word.

# Project Name                        (WHAT — 1–2 lines)
SaaS document-automation platform. TypeScript monorepo:
backend (Express), frontend (React), docs (Docusaurus).

## Commands                           (HOW — essentials only)
```bash
npm run dev       # Start dev server
npm run test      # Run tests
npm run build     # Production build
```

## Project Structure                  (WHAT — directory map)
```
src/routes/       # API endpoints
src/models/       # DB models
src/handlers/     # Business logic
```

## Conventions                        (HOW — non-default patterns only)
- Use Zustand for state, never Redux
- All API responses use `{ success, data, error }`
- Migrations go in src/database/migrations/

## Reference Documents                (progressive disclosure)
### API Architecture — `@docs/api-architecture.md`
**Read when:** Adding or modifying API endpoints

Rule 4 — Use progressive disclosure

This is the single most powerful technique: keep task-specific knowledge out of CLAUDE.md and load it only when a task needs it. Claude Code gives you four mechanisms — pick by how the knowledge is used:

Mechanism	How it loads	Best for
@imports — @path/to/file.md syntax	Pulled in on demand; recursive up to 5 levels deep	READMEs, detailed SOPs, API architecture docs
.claude/rules/*.md	Auto-loaded alongside CLAUDE.md at the same priority	Team-wide coding rules, review checklists
.claude/skills/	Loaded on demand by relevance; discovered via name + description metadata without loading full content	Domain knowledge, specialized or complex workflows
docs/ directory	Referenced from CLAUDE.md with a "Read when" trigger	Long-form docs, style guides, migration playbooks

The "Read when" pattern is what makes references work. For each linked doc, state when to read it and what it contains, so Claude pulls it in at the right moment instead of every session:

## Reference Documents
### Content SEO SOP — `@docs/CONTENT-SEO-SOP.md`
**Read when:** Creating or editing ANY content page
Covers metadata requirements, JSON-LD schemas, internal-linking minimums

### API Architecture — `@docs/api-architecture.md`
**Read when:** Adding or modifying API endpoints
Defines route patterns, request/response shapes, auth middleware

A root CLAUDE.md can reference many deep SOPs this way while staying tiny — Claude only loads each one when the task calls for it.

Rule 5 — Place files correctly (hierarchy)

Claude Code loads CLAUDE.md files from multiple locations with a clear precedence. Layer context appropriately and get the commit decision right:

Location	Scope	Commit?
~/.claude/CLAUDE.md	All sessions, all projects	No (personal)
./CLAUDE.md	Project root	Yes
./CLAUDE.local.md	Personal project overrides	No (.gitignore)
parent/CLAUDE.md	Inherited by child directories	Yes
child/CLAUDE.md	Loaded when working in that dir	Yes
.claude/rules/*.md	Auto-loaded alongside CLAUDE.md	Yes

In a monorepo: put shared conventions in the root CLAUDE.md and service-specific context in child directories — e.g. a backend dir whose CLAUDE.md covers migrations and API patterns, and a frontend dir whose CLAUDE.md covers component conventions and state management.

API integration projects

For apps that consume external APIs, the key insight is: document the conventions around API usage, not the API itself. Claude can read API docs; what it can't infer is your team's patterns for auth, error handling, retries, and webhooks.

## API Integrations
- TurboDocx API: REST, Bearer token auth, base URL in TURBODOCX_API_URL
  - SDK: @turbodocx/sdk (TypeScript) — always prefer the SDK over raw fetch
  - Docs: https://docs.turbodocx.com/API
  - Webhooks: POST to /webhooks/turbodocx, verify X-Signature header

## Error Handling Conventions
- All external API calls wrapped in try/catch
- Retry transient errors (429, 503) with exponential backoff
- Log API errors to the structured logger, never swallow silently
- Return a standardized error shape: { code, message, retryable }

Keep the full API reference in external docs; CLAUDE.md just points Claude in the right direction.

Maintaining a CLAUDE.md

A CLAUDE.md is not set-and-forget — treat it like code. Review it when things go wrong, prune regularly, and commit changes to version control.

• Run /insights periodically (e.g. weekly) to surface patterns from your sessions and turn them into rules.
• If Claude repeatedly ignores a rule, the file is too long — prune it. Ignored rules are a length symptom, not a phrasing problem.
• If Claude asks questions already answered in the file, the phrasing is ambiguous — rewrite that part.
• Prefix the critical, non-negotiable rules with IMPORTANT or YOU MUST to improve adherence. Use this sparingly — if everything is critical, nothing is.
• The most underrated trick: when Claude makes a mistake — wrong import path, broken naming convention, misread structure — don't just fix it and move on. Tell Claude to add the correction to CLAUDE.md itself. Over time the file becomes a living, self-authored record of the codebase's quirks, and a feedback loop rather than a static brief.

Audit / authoring checklist

Do

• Keep it under 200 lines
• Open with a 1–2 line project context
• List the essential commands (dev, test, build)
• Document non-default conventions only
• Use @imports for detailed docs
• Include a directory-structure overview
• Add "Read when" triggers for every referenced doc
• Use IMPORTANT for the genuinely critical rules
• Review and prune regularly; commit to git

Don't

• Exceed ~300 lines total
• Duplicate anything a linter enforces
• Paste full API documentation inline
• Write file-by-file descriptions
• Add obvious instructions ("write clean code")
• Store frequently changing information
• Put task-specific instructions in the root file (push them to progressive disclosure)
• Forget to commit changes

Agentic & long-running projects

When the project is a production AI system (an LLM calling many tools/APIs) and/or is built across many sessions over weeks or months, the base rules above still apply, but three things become central. This is a summary; references/agentic-engineering.md has the full treatment, and the agentic scaffolds live in assets/.

1. Separate the two memories. A production agentic project has two distinct persistence layers with different mechanisms: the harness you operate (Claude Code sessions — state in CLAUDE.md, auto-memory MEMORY.md, subagent memory, and git/progress files) and the agent you ship (your prod LLM — state in the Memory Tool memory_20250818 on the Agent SDK / Messages API, plus your own datastore). Most "the agent forgot X" pain is state placed in the wrong layer.

2. The durable checkpoint is the filesystem + git, not a memory file. For long-horizon work, use the initializer + coding-agent harness: an initializer run sets up feature_list.json (scope as a checklist — JSON, because the model is less likely to overwrite it than Markdown), claude-progress.txt, init.sh, and an initial commit; every coding session then reads the progress log + git log + feature list, runs init.sh and smoke-tests, works one feature, verifies it end-to-end as a real user would, commits, updates the progress log, and stops. This is what prevents the two classic failures: one-shotting (running out of context mid-feature) and declaring "done" prematurely.

3. Anything that must survive context compaction lives outside the conversation. Compaction keeps "what to do next" but drops the "why" (decision context). So durable state goes in CLAUDE.md, MEMORY.md, the progress log, or the Memory Tool — never chat history alone. Put security and other invariants in CLAUDE.local.md, which is re-read after every compaction. Compact proactively (well before the window fills) rather than waiting for "context rot."

For CLAUDE.md specifically in this regime: lead with the session/recovery protocol (prefix IMPORTANT), move domain/tool rules to .claude/rules/*.md with globs so they load just-in-time, keep volatile status out (that's the progress log's job), and document tool/API conventions (auth, retries, error shape) rather than the API reference. Start from assets/agentic-claude-md-template.md.

Bundled resources

Base authoring:

• assets/claude-md-template.md — copy-ready starter template for a standard project. Replace the bracketed placeholders with real values.
• references/examples.md — three complete worked examples (single project, monorepo root + child, API-integration project).

Agentic / long-running:

• references/agentic-engineering.md — the full reference: the four memory layers, the initializer/coding-agent harness, surviving compaction, optimizing CLAUDE.md for agentic projects, and context/tool engineering for the shipped agent. Read this whenever the task is agentic or spans many sessions.
• assets/agentic-claude-md-template.md — copy-ready CLAUDE.md with the session/recovery protocol baked in.
• assets/feature_list.json — starter scope checklist in the harness format.
• assets/claude-progress.txt — starter session-log template.
• assets/init.sh — starter environment-bootstrap script (the smoke-test target).
• assets/rules-example.md — example .claude/rules/ file showing path-scoped globs frontmatter for just-in-time rule loading.

---

Base CLAUDE.md practices distilled from TurboDocx's "How to Write a CLAUDE.md File That Actually Works" (turbodocx.com). Agentic/long-running practices drawn from Anthropic's "Effective harnesses for long-running agents," "Effective context engineering for AI agents," and "Writing tools for agents," the Claude Code memory documentation, and community syntheses — see references/agentic-engineering.md for full sources.