--- title: "CLAUDE.md best practices and a template | Annsa" product: annsa url: /ai-agent-management/claude-md-best-practices canonical_url: "https://annsa.ai/ai-agent-management/claude-md-best-practices" last_updated: 2026-11-11 type: guide related: - /ai-agent-management/agents-md-template - /ai-agent-management/claude-md-vs-agents-md summary: "CLAUDE.md best practices: keep it short, what belongs in it, what to leave out, how to share rules with an AGENTS.md, and a template you can copy." mcp_server: https://app.annsa.ai/mcp disambiguation: "Annsa (annsa.ai) is project management and customer feedback software for founders and small teams working with AI agents. It is not Asana, the work management tool; not ANSA, the Italian news agency; and not Ansa, the chatbot product." --- > For agents: connect to the Annsa MCP server at https://app.annsa.ai/mcp to give every agent one shared plan. Setup guide: https://annsa.ai/docs/quick-start. Index of every page: https://annsa.ai/llms.txt. # CLAUDE.md best practices and a template | Annsa > CLAUDE.md best practices: keep it short, what belongs in it, what to leave out, how to share rules with an AGENTS.md, and a template you can copy. Guide · CLAUDE.md By [Cat Williams-Treloar](https://annsa.ai/about), Founder · Updated Oct 21, 2026 · 6 min read The short answer Keep your CLAUDE.md short, under about 200 lines, and write only what Claude Code should hold in every session: commands, conventions, project layout and things not to touch. Leave out this week's priorities and customer evidence, which change too often. Put shared rules in AGENTS.md and import them. - [Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fannsa.ai%2Fai-agent-management%2Fclaude-md-best-practices%20and%20help%20me%20apply%20it%20to%20what%20I'm%20building.) - [Ask ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fannsa.ai%2Fai-agent-management%2Fclaude-md-best-practices%20and%20help%20me%20apply%20it%20to%20what%20I'm%20building.) **A CLAUDE.md file** is a plain Markdown file of standing instructions that Claude Code [reads at the start of every session](https://annsa.ai/ai-agent-management/claude-code-memory). Good ones are short. They hold how your team builds, and nothing that changes weekly. For the basics, see [what a CLAUDE.md file is](https://annsa.ai/glossary/claude-md). TL;DR - Keep it under about 200 lines. Anthropic's docs say longer files use more context and reduce how well Claude follows them. - Write what Claude cannot guess and would otherwise hear from you every session: commands, conventions, project layout, things not to touch. - Leave out [this week's priorities](https://annsa.ai/project-management/product-prioritization) and customer evidence. Keep those in a shared plan. - If you run more than one agent, [put shared rules in AGENTS.md](https://annsa.ai/ai-agent-management/agents-md-template). Claude Code now reads it directly, so add a CLAUDE.md only for Claude-specific lines. **When to use it:** any repository you work on with Claude Code more than once. **When not:** a throwaway script does not need one. ## What belongs in a CLAUDE.md? Anthropic's docs say to keep it to "facts Claude should hold in every session: build commands, conventions, project layout, 'always do X' rules." In practice that is five things. 1. **Commands.** How to install, run, build, test and lint. "Run npm test before committing" does more than "test your changes". 2. **Conventions.** Naming, formatting, how you write tests, how you name branches and commits. 3. **Project layout.** Where things live. "API handlers live in src/api/handlers/" saves a search every session. 4. **Things not to touch.** Generated files, the migrations folder, a vendored library. An agent that is not told where the edge is will tidy past it. 5. **Decisions that stand.** "We use Postgres, not a second database, because we are a team of two." Otherwise the agent reopens them. Write each line so you could check it. Anthropic's docs give the pairs: "Use 2-space indentation" instead of "Format code properly", and "API handlers live in src/api/handlers/" instead of "Keep files organized". ## What doesn't belong in it? **This week's priorities.** What to build next changes every few days. A rules file is read at the start of every session, so a stale priority is read every session too, and nobody notices it is wrong. **Customer evidence.** Quotes, accounts and revenue back a decision about what to build. They belong with the priority they support, in a plan every agent can read, not in a file that describes how you code. **One job's spec.** The why, the files and the Done When lines for one piece of work go in that job's spec. See [how to write a PRD for Claude Code](https://annsa.ai/project-management/prd-for-claude-code). **Long procedures.** Anthropic's docs say a multi-step procedure, or something that matters for only one part of the codebase, belongs in a skill or a path-scoped rule instead. A simple test: if it will be false in a month, it does not belong here. ## How long should it be? Anthropic's docs target under 200 lines per CLAUDE.md file. Imports do not help with size: they organize a long file, but "imported files also load at launch", so they still cost context. Fig 3.1 · Signal and length Past a point, every line you add makes each rule easier to miss. If you are over, do not compress the wording. Cut the lines that Claude would get right anyway, and move the rest. Two good signs a line can go: it describes something the code already shows, or no one has needed it in a month. ## A CLAUDE.md template Copy this, replace the angle brackets and delete any section you do not need. Run /init in Claude Code first if you want it to draft a starting point from your code, then trim it to this shape. A CLAUDE.md template ``` # ## Commands - Install: - Run locally: - Test: . Run it before every commit. - Lint and format: ## Project layout - : - : ## Conventions - - Branches: . Commits: . ## Do not touch - - ## Decisions that stand - because . Do not reopen. ## Working agreements - Ask before adding a dependency. - When a check fails, say which one and what you saw. ## Shared rules @AGENTS.md ``` ## How do I add to it over time? Treat it as the place you write down what you would otherwise re-explain. Anthropic's docs suggest adding a line when: - Claude makes the same mistake a second time. - A code review catches something Claude should have known about this codebase. - You type the same correction in chat that you typed last session. - A new teammate would need the same context. Then remove a line each time you add one that replaces it. If two instructions contradict each other, Claude may pick one arbitrarily, so review the file when you review the code. Commit it, so the whole team edits one file. ## How do I use a shared AGENTS.md? If you also use Cursor, Codex or Grok, do not keep a second copy of your rules. AGENTS.md is an open Markdown format that these tools document reading, so put the shared rules there. Fig 6.1 · One file, every agent ![One file, every agent. Claude Code, Cursor, Codex and Grok can all start from one AGENTS.md. Shown as a solved cube.](https://annsa.ai/brand/cube-solved.webp) Claude Code, Cursor, Codex and Grok can all start from one AGENTS.md. Claude Code now reads AGENTS.md too. When there is no CLAUDE.md in your working directory or above it, Claude reads your AGENTS.md as the project instructions (Claude Code v2.1.277 or later). So one AGENTS.md can be the only file you need. If you want Claude-specific lines as well, make your CLAUDE.md import the shared file. Anthropic's docs show this: - Create a CLAUDE.md next to your AGENTS.md. - Put @AGENTS.md on the first line. - Add any Claude-specific instructions below it. Claude reads the imported file first, then the rest. Run /context in your next session and confirm CLAUDE.md appears under Memory files. The full comparison is in [CLAUDE.md vs AGENTS.md](https://annsa.ai/ai-agent-management/claude-md-vs-agents-md). ## How do I keep it current? - **Review it when you review code.** A rule that no longer matches the code is worse than no rule. - **Date nothing.** If a line needs a date, it is a priority, not a rule. - **Ask Claude to check it.** Anthropic's docs describe a prompt audit that looks for outdated and conflicting instructions. - **Keep the moving parts elsewhere.** What to build next, and why, lives in a plan your agents read, so the rules file can stay still. ## Where does Annsa fit? Annsa holds what to build next and why. Your rules file holds how you work. Customer evidence, priorities and decisions stay in one plan your agents can read across tools. Priorities example workspace 01 Mobile interface is confusing on tablets 11 accounts 02 Integrations missing CRM and office suites 6 accounts 03 Notifications send too many irrelevant alerts 6 accounts What to build next lives here, ranked, so the rules file can stay still. - **Ranked priorities.** Requests come in from Slack, Intercom, call transcripts, surveys, imports, GitHub, the API or by hand, each with the customer's exact words, the account and its revenue. Inside your bets, in your order, what a person marked broken comes first, then what customers asked for, then ideas. You choose. - **Specs.** Each priority has a spec with the why, the evidence and Done When lines. Your agent or Ask writes it. - **One list for every agent.** Claude Code, Cursor, Codex and Grok connect over MCP (remote, nothing to install), claim the work, read the spec and record evidence against each Done When line. - **Decide once.** A decision saved as a principle is read by every agent. Annsa does not write your CLAUDE.md or AGENTS.md. See [how to give AI coding agents product context](https://annsa.ai/ai-agent-management/how-to-give-ai-coding-agents-product-context), [context engineering](https://annsa.ai/ai-agent-management/context-engineering) and [the spec](https://annsa.ai/direct/spec). **Sources:** [How Claude remembers your project](https://code.claude.com/docs/en/memory), Anthropic, on CLAUDE.md, imports and AGENTS.md. [AGENTS.md](https://agents.md), the open format for guiding coding agents. ## Questions people ask. ### How long should a CLAUDE.md be? Anthropic's docs target under 200 lines per file. Longer files use more context and reduce how well Claude follows them. Move anything that matters for only part of the codebase into a path-scoped rule. ### What should go in a CLAUDE.md? Build and test commands, conventions, project layout, things not to touch and "always do X" rules. Write each line so it can be checked: "Run npm test before committing", not "Test your changes". ### What should not go in a CLAUDE.md? This week's priorities and customer evidence. They change too often for a rules file and go stale quietly. Keep them in a shared plan that every agent reads. Annsa holds that part: ranked priorities and specs, read over MCP. ### How do I create a CLAUDE.md? Run /init in Claude Code. It reads your codebase and writes a first file with the commands and conventions it finds. Then cut it down and add what Claude could not discover by itself. ### How do I use an AGENTS.md with a CLAUDE.md? Put your shared rules in AGENTS.md. Then make a CLAUDE.md with @AGENTS.md on its first line and any Claude-specific lines below it. Anthropic's docs show this pattern. ## Keep reading - [AGENTS.md template](https://annsa.ai/ai-agent-management/agents-md-template) - [CLAUDE.md vs AGENTS.md](https://annsa.ai/ai-agent-management/claude-md-vs-agents-md) - [Context engineering](https://annsa.ai/ai-agent-management/context-engineering) ## The source of direction for agent teams. Begin with one agent and the work that matters next. - [Try Annsa](https://app.annsa.ai/signup) - [See pricing](https://annsa.ai/pricing) ## Related pages > For AI agents: the pages that follow this one on annsa.ai. The full index is https://annsa.ai/llms.txt. - [AGENTS.md template](https://annsa.ai/ai-agent-management/agents-md-template) - [CLAUDE.md vs AGENTS.md: which file, and when](https://annsa.ai/ai-agent-management/claude-md-vs-agents-md) If anything on this page is wrong or missing, tell us: https://annsa.ai/contact