Developer Resource

The Developer's Guide to CLAUDE.md

Structure, organize, and scale your AI coding context. Everything you need to know about configuring Claude Code for projects of any size.

David González

Updated Mar 2026

15 min read

Read the Best Practices Blog Post Start Reading

What Is CLAUDE.md?

CLAUDE.md is a special markdown file that Claude Code (Anthropic's AI coding assistant for the terminal) loads into context at the start of every session. Think of it as an onboarding document for an extremely capable developer who joins your team fresh every morning — they know programming deeply, but they don't know your project's specific conventions, architecture, or workflows.

Unlike regular documentation that developers read once, CLAUDE.md is consumed by an AI assistant on every interaction. This means every line has a cost: it takes up context window space that could otherwise be used for your actual code and conversation. The official Anthropic recommendation is to keep it under 200 lines.

Key Insight

CLAUDE.md isn't documentation — it's a context injection file. Its purpose is to prevent mistakes and orient Claude, not to teach it programming.

File Types and Placement

Claude Code supports several context file types, each with a different scope and loading behavior. Understanding this hierarchy is essential for organizing context in complex projects and monorepos.

File	Location	Loaded	Commit?
CLAUDE.md	Project root	Every session	Yes
CLAUDE.local.md	Project root	Every session	No (.gitignore)
~/.claude/CLAUDE.md	Home directory	Every session, all projects	No (personal)
.claude/rules/*.md	Project .claude/ dir	Auto-loaded (same priority as CLAUDE.md)	Yes
.claude/skills/*.md	Project .claude/ dir	On-demand (by relevance)	Yes
child/CLAUDE.md	Subdirectory	When working in that directory	Yes

Monorepo Pattern

Put shared conventions (commands, project overview, team workflow) in the root CLAUDE.md. Put service-specific context (database patterns, component conventions, deployment details) in child directory CLAUDE.md files. Claude loads both when working in a subdirectory.

What to Include

Every item in your CLAUDE.md should pass this test: “Would removing this cause Claude to make mistakes?” If not, cut it. Here's what earns its place:

Essential Commands

Build, test, lint, deploy commands that Claude will run directly. These must be exact.

Project Architecture

A brief directory map showing where routes, models, handlers, and tests live. Not every file — just the structure.

Non-Default Conventions

Only patterns that differ from language/framework defaults. If ESLint or Prettier handles it, don't repeat it here.

Workflow Rules

Branch naming conventions, PR requirements, commit message format — things that can't be inferred from code.

Common Gotchas

Non-obvious behaviors that cause repeated mistakes. "Always run sync-pricing before build" saves hours of debugging.

Reference Document Pointers

Point to detailed docs with "Read when" triggers. Claude only loads them when the task matches.

For hands-on examples from a real project, see our CLAUDE.md best practices blog post where we walk through TurboDocx's own CLAUDE.md configuration, including how we handle API integration context for Claude Code.

What to Exclude

Knowing what to leave out is just as important. These common inclusions waste context tokens and dilute the signal:

Standard language conventions

Claude already knows TypeScript, Python, Go, etc. Don't tell it to "use const over let" or "prefer async/await."

Detailed API documentation

Link to external docs with @imports instead. Claude can read them on demand.

Code style rules enforced by linters

If ESLint or Prettier handles it, CLAUDE.md shouldn't. Don't send an LLM to do a linter's job.

File-by-file codebase descriptions

Claude can read your files directly. A high-level directory map is enough.

Obvious best practices

"Write clean code" and "handle errors" add zero value — Claude does this by default.

Frequently changing information

Stale info is worse than no info. Keep volatile details in environment variables or separate docs.

The @imports System

The @path/to/file import syntax is the most powerful feature for managing CLAUDE.md at scale. It lets you keep your root file lean while giving Claude access to detailed documentation when needed.

# In your CLAUDE.md:

## Reference Documents

### API Architecture — `@docs/api-architecture.md`
**Read when:** Adding or modifying API endpoints

### Deployment SOP — `@docs/deployment.md`
**Read when:** Deploying to staging or production

### Personal Overrides — `@~/.claude/my-project-prefs.md`
**Read when:** Always (personal styling preferences)

Recursive

Imports can reference other files with @imports, up to 5 levels deep.

Flexible Paths

Use relative paths, absolute paths, or ~ for home directory references.

On-Demand

Claude reads imported files when the task matches the “Read when” trigger you define.

This is the mechanism that enables progressive disclosure — the strategy of keeping your root CLAUDE.md lean (under 200 lines) while still giving Claude access to thousands of lines of documentation. At TurboDocx, our CLAUDE.md references six detailed SOPs for content creation, SEO architecture, document automation workflows, and deployment — but Claude only loads them when the task requires it.

Structure Patterns

The right CLAUDE.md structure depends on your project type. Here are proven patterns:

Single Project

One CLAUDE.md at the root. Keep it simple — project overview, commands, structure, conventions.

CLAUDE.md          ← Everything in one file (under 200 lines)
docs/              ← Referenced via @imports
.claude/rules/     ← Auto-loaded team rules

Monorepo

Root CLAUDE.md for shared context. Child CLAUDE.md files for service-specific conventions.

CLAUDE.md          ← Shared: commands, overview, team workflow
backend/
  CLAUDE.md        ← DB patterns, API conventions, middleware
frontend/
  CLAUDE.md        ← Component patterns, state management
docs/
  CLAUDE.md        ← Content conventions, build process

API / SDK Project

Emphasize integration patterns, auth conventions, and error handling. API-first projects need explicit SDK and webhook context.

CLAUDE.md          ← Auth patterns, error shapes, SDK usage
  @docs/api-endpoints.md    ← Full endpoint reference
  @docs/webhook-patterns.md ← Webhook verification & retry
.claude/rules/
  error-handling.md ← Standardized error conventions

Best Practices Summary

Do

Keep under 200 lines (300 absolute max)
Use WHY/WHAT/HOW structure
Apply progressive disclosure via @imports
Document only non-default conventions
Include essential commands (exact strings)
Add "Read when" triggers for referenced docs
Use IMPORTANT for critical rules
Treat it like code — review, prune, version control
Run /insights weekly to surface new patterns

Don't

Exceed 300 lines total
Duplicate what linters/formatters enforce
Include full API documentation
Write file-by-file codebase descriptions
Add obvious instructions ("write clean code")
Store frequently changing information
Put task-specific instructions in CLAUDE.md
Forget to commit changes to git

For a detailed walkthrough with code examples and real-world templates, read our CLAUDE.md best practices blog post.

CLAUDE.md vs Other AI Config Files

Several AI coding assistants have their own context configuration files. Here's how they compare:

File	Tool	Key Differences
CLAUDE.md	Claude Code	Supports @imports, .claude/rules/, .claude/skills/, CLAUDE.local.md, hierarchical loading
.cursorrules	Cursor	Single file, no import system, project-level only
.github/copilot-instructions.md	GitHub Copilot	GitHub-specific, lives in .github/ directory, no hierarchical loading

CLAUDE.md's progressive disclosure system (@imports, rules, skills) is unique among AI coding tools. If you're migrating from another tool, focus on extracting your most critical rules and putting them in CLAUDE.md, then moving everything else into referenced docs.

Using CLAUDE.md for API Integrations

When your project integrates with external APIs — whether it's adding e-signatures with JavaScript, Python, or Go — your CLAUDE.md should document the patterns, not the API itself:

Authentication Pattern

Which auth method (Bearer, API key, OAuth) and where credentials are stored (env vars, secrets manager).

SDK Preferences

Which SDK or client library to use. "Always use @turbodocx/sdk, never raw fetch calls."

Error & Retry Conventions

Your team's standardized error shape, which status codes to retry, backoff strategy.

Webhook Processing

Endpoint paths, signature verification approach, idempotency key handling.

For comprehensive API integration patterns, see our API integration best practices guide. And if you're building a developer-facing platform that generates documents or collects signatures, the TurboDocx API is designed to be embedded with minimal configuration — your CLAUDE.md integration section can be as simple as three lines pointing to the SDK and base URL.

Ready to Build with Claude Code + TurboDocx?

Use Claude Code to integrate document generation and e-signatures into your application in minutes.

Schedule a Demo Developer Hub