Anatomy of a CLAUDE.md

Overview

Now that you understand why CLAUDE.md matters, it is time to learn what goes inside it. A well-structured CLAUDE.md is not a free-form essay -- it follows a deliberate structure that mirrors how an agent processes information.

In this lesson, you will learn the key sections of a CLAUDE.md, the mental model behind its organization, and how to structure each section for maximum agent effectiveness.

The Mental Model: Agent as New Team Member

Before diving into sections, consider how a CLAUDE.md gets used. When an agent starts a session, it reads CLAUDE.md as part of its system context. This means:

• The agent reads it before looking at any code
• It shapes the agent's behavior for the entire session
• Every token in CLAUDE.md consumes context window space
• The agent treats instructions as authoritative -- it will follow them

This gives us a design principle: put the most operationally critical information first, keep everything concise, and never include information the agent does not need to act on.

How CLAUDE.md sections map to the agent workflow: Section 1 (Build and Test Commands) is used during verification, Section 2 (Code Style Rules) guides code writing, Section 3 (Architecture Notes) informs planning, Section 4 (Do's and Don'ts) constrains code writing, and Section 5 (File Structure) aids planning and navigation.

Each section of CLAUDE.md maps to a phase in the agent's workflow. Build commands are needed at the end (verification), but they are listed first because they are the most frequently referenced and the most operationally critical.

Section 1: Build, Test, and Lint Commands

This is the most important section. Without correct commands, the agent cannot verify its own work. Place it at the very top.

Notice the structure:

• Exact commands -- not "run the tests" but pnpm vitest run
• Variations -- how to run a subset of tests, not just the full suite
• All verification steps -- build, test, lint, and type-check are separate concerns

Tip: Include the command for running a single test file. Agents frequently need to iterate on one test without running the entire suite.

Section 2: Code Style and Conventions

This section tells the agent how to write code that fits your codebase. Be specific about the conventions that matter most.

Focus on conventions that:

• Differ from language defaults or common practice
• Have caused problems in past agent sessions
• Would be hard for the agent to infer from existing code

You do not need to document every convention. If your project uses Prettier with a config file, the agent can read that config. Document the conventions that live in people's heads.

Section 3: Architecture Notes

This section gives the agent a map of the codebase. It helps the agent decide where to put new code and how components connect.

Keep architecture notes structural, not historical. The agent does not need to know why you chose Drizzle over Prisma -- it needs to know that Drizzle is what you use and where the queries live.

Section 4: Do's and Don'ts

This section is your guardrail. It prevents the agent from making mistakes that are hard to catch in review. The "Don'ts" are often more valuable than the "Do's" because they prevent specific failure modes.

Key insight: Every "Do NOT" rule usually comes from a real incident. When an agent makes a mistake, add a corresponding "Do NOT" rule. Your CLAUDE.md should evolve over time.

Section 5: File Structure Hints

For complex projects, a brief file tree helps the agent navigate without having to explore the filesystem.

You do not need to list every file. Focus on the top two or three levels and annotate directories whose purpose is not obvious from the name.

Putting It All Together

Here is how these sections compose into a complete CLAUDE.md:

The five CLAUDE.md sections in order: Section 1 Build and Test Commands (high frequency, high impact), Section 2 Code Style (medium frequency, high impact), Section 3 Architecture (medium frequency, high impact), Section 4 Do's and Don'ts (low frequency, high impact), Section 5 File Structure (reference only). Most operationally critical sections come first.

The ordering is intentional: most operationally critical first, reference material last. This matters because if the agent's context window is constrained, the most important information is processed first.

Length Guidelines

A common question is "how long should my CLAUDE.md be?" The answer depends on your project's complexity, but here are guidelines:

Warning: Resist the urge to document everything. Every line in CLAUDE.md consumes context window tokens. Include only information the agent needs to act correctly. If a convention can be inferred from existing code or config files, you may not need to state it explicitly.

The Iteration Loop

Your first CLAUDE.md will not be perfect, and it does not need to be. Treat it as a living document that improves through a feedback loop:

1. Write an initial CLAUDE.md with build commands and top conventions
2. Use an agent to do real work in the codebase
3. Notice where the agent makes mistakes or asks unnecessary questions
4. Update the CLAUDE.md to address those gaps
5. Repeat

Over a few sessions, your CLAUDE.md converges on the right level of detail for your project. The mistakes stop. The iterations shrink. And every team member benefits from the improvements.

Summary

• A well-structured CLAUDE.md has five core sections: commands, code style, architecture, rules, and file structure
• Order sections by operational criticality -- build and test commands come first
• Be specific and concise -- exact commands, not vague descriptions
• The "Do NOT" rules are often the most valuable section because they prevent known failure modes
• Keep length proportional to project complexity -- 40-80 lines for a typical web application
• Treat CLAUDE.md as a living document that evolves through the feedback loop of real agent sessions