How long should a CLAUDE.md file be?

Keep it short, between 100 and 200 lines. Include general rules, a project overview, and hard constraints, then link to narrower docs for specific details.

What type of content belongs in CLAUDE.md?

Focus on project shape, the tech stack, important directories, and explicit rules. Define strict boundaries like what code should never cross, rather than general descriptions.

Where should detailed documentation go?

Place deep reference material and agent-specific context in separate markdown files. Link out to these from CLAUDE.md so the main file stays concise.

Should I let Claude update CLAUDE.md during sessions?

No. Treat CLAUDE.md as a version-controlled, human-managed document. Session-specific details and learnings belong in separate agent_docs files or PR descriptions.

How do you enforce coding rules written in CLAUDE.md?

Agents tend to treat written rules as suggestions over long sessions. The most effective method is to write deterministic code, hooks, or automated checks that catch mistakes.

How to Structure CLAUDE.md for Team Development Practices

Structuring CLAUDE.md for teams means keeping the file concise, under 200 lines, and focusing on general rules and hard constraints.

Write for a skilled but new team member, providing a project overview, tech stack, and explicit boundaries rather than descriptive text.

Link out to deeper documentation and separate markdown files to manage bloat, and use deterministic code like hooks to enforce rules agents might otherwise ignore.

How to Structure CLAUDE.md for Team Development Practices — infographic

Structuring CLAUDE.md files for development teams generally involves keeping them concise, focusing on core project rules and conventions, and integrating them with other tools like skills and separate documentation files to manage context effectively.

CLAUDE.md Content Best Practices

Concise and focused content: Keep CLAUDE.md under 100-200 lines, including only general rules, project overview, and hard constraints. "Keep the root CLAUDE.md short, then link to narrower docs for things like API conventions, UI rules, deployment, or evals."

Project overview and technical stack: Include a brief description of the project, its purpose, and the technologies used to prevent the model from making incorrect assumptions. "Project shape: stack, important directories, what is intentionally out of scope."

Coding conventions and boundaries: Define strict coding rules, naming conventions, and architectural boundaries as explicit "never cross" rules rather than descriptive text. "Domain layer must never import from infrastructure. If a domain file needs a NestJS decorator, stop and ask."

Managing Context and Avoiding Bloat

Link to external documentation: Reference deeper, more detailed information in separate .md files or specialized documentation rather than embedding it directly into CLAUDE.md. "Don't put everything in CLAUDE.md. Structure it like: CLAUDE.md → core rules only agents/roles/*.md → agent-specific context docs/architecture.md → deep reference (agents fetch when needed)"

Use skills and workflows: Implement specific workflows and reusable skills as separate files that Claude can access on demand, preventing them from bloating the main CLAUDE.md file. "The best general guideline I've read is: "pretend you're writing for a skilled-but-new member of your team; tell them about what they specifically need to know about YOUR code.""

Avoid agent-driven modifications: Prevent Claude from continuously updating CLAUDE.md with session-specific learnings; instead, treat it as a version-controlled document that is primarily human-managed. "When Claude wants to "document what we just did," that detail belongs in an agent_docs/ file (or the PR description), not CLAUDE.md."

Team Integration and Enforcement

Version control and shared access: Treat CLAUDE.md like any other file in your repository, allowing for version control and team-wide maintenance and review. "Yes, its pushed to the repo or you can also keep a copy offline and share by other means."

Enforce rules with hooks and automated checks: Supplement CLAUDE.md guidelines with executable checks, hooks, or testing to ensure compliance, as agents may treat rules as suggestions over long sessions. "The agent will always start to treat rules like suggestions over long sessions. The trick is to make deterministic code to enforce the parts of CLAUDE.md that truly matter, so agent mistakes are caught."

Hierarchical structure: Use a tiered approach where global settings apply broadly, Cowork settings apply to specific environments, and CLAUDE.md files within HQ or workstations provide more granular instructions. "CLAUDE.md is the main instruction set of your entire cowork HQ and one of the most inportant ones to make it work properly."

Do you want to explore specific examples of CLAUDE.md files used in production environments?

Best for: Development teams using Claude who want to align agent behavior with their specific codebase rules and conventions.