The CLAUDE.md Playbook: 12 Rules That Cut My AI Debugging Time in Half

Claude Code reads your CLAUDE.md file at the start of every session. It's the first thing it sees. It shapes every decision Claude makes about your project --- which tools to use, which patterns to follow, which mistakes to avoid.

Most developers either skip it entirely or dump 200 lines of rules that Claude promptly ignores. Both approaches waste your time. A well-crafted CLAUDE.md, however, is the single highest-leverage thing you can configure. Anthropic's own best practices documentation calls specifying your test command "the highest-leverage thing you can do."

Here are 12 rules that actually work, based on Anthropic's internal practices, community battle-testing, and hard-won experience.

Key Takeaways

• A focused CLAUDE.md under 80 lines outperforms a 200-line wall of instructions
• The most impactful rule is your test command --- it gives Claude a way to verify its own work
• Negative constraints ("NEVER do X") are followed more reliably than positive ones ("prefer Y")
• Anthropic's own team uses a "Things That Will Bite You" section --- steal this pattern
• Use hooks for rules that must be enforced 100% of the time; CLAUDE.md for everything else

Short Answer

What is CLAUDE.md? A markdown file that gives Claude Code persistent context about your project --- build commands, code conventions, architectural decisions, and common gotchas. Claude reads it automatically every session. It lives at your project root (shared with team) or ~/.claude/CLAUDE.md (personal, global). The /init command generates a starter file by analyzing your codebase.

Before the Rules: What Size Should It Be?

The HumanLayer team keeps their CLAUDE.md under 60 lines. The claude-md-templates community repo recommends under 80 lines. Research suggests that instruction compliance decreases as rule count increases --- one developer wrote 200 lines of rules and Claude ignored them all.

The principle: every line must earn its place by solving a real problem. If you can remove a rule and nothing goes wrong, it should not be there.

Rule 1: Specify Your Test Command

# Testing
- Run `npm test -- --testPathPattern=<file>` for single test files
- Run `npm run typecheck` after code changes
- NEVER run the full test suite unless explicitly asked

This is the most impactful rule in any CLAUDE.md. Without a test command, YOU are the only feedback loop. Claude writes code, you run it, you report back. With a test command, Claude writes code, runs tests, sees failures, fixes them, and verifies --- all without you.

Anthropic's own documentation calls this "the single highest-leverage thing you can do."

Rule 2: Declare Your Tech Stack with Versions

# Tech Stack
- Next.js 15.5.2 + TypeScript strict mode
- Tailwind CSS 4 (not CSS modules, not styled-components)
- Supabase for auth and database
- Edge runtime on all routes

Without this, Claude defaults to whatever patterns it learned in training --- which might be Next.js 13 conventions, CSS-in-JS, or an auth library you have never heard of. Anthropic's own CLAUDE.md for their claude-code-action project explicitly states "Runtime is Bun, not Node."

Be specific about versions. "Next.js" is not enough. "Next.js 15.5.2 with App Router" prevents a class of mistakes that would otherwise take you 20 minutes to debug.

Rule 3: List the "Things That Will Bite You"

# Gotchas
- `process.env` only works for `NEXT_PUBLIC_*` on Cloudflare Pages
- Use `getRequestContext()` for server-side env vars
- Token refresh has a race condition - always check expiry BEFORE the API call
- The rate limiter is per-isolate on edge, not global

This pattern comes directly from Anthropic's own CLAUDE.md. They have a literal section called "Things That Will Bite You" with five specific gotchas about their codebase.

These are the non-obvious behaviors Claude cannot infer from reading code. The env var issue above? Claude will use process.env on a Cloudflare Pages project and it will fail silently. Without this rule, you debug for 15 minutes. With it, Claude gets it right the first time.

Rule 4: Define Forbidden Patterns

# Forbidden
- NEVER use `any` type in TypeScript
- NEVER use CSS modules or styled-components
- NEVER use emoji as UI elements (use Lucide icons)
- NEVER suppress TypeScript errors with @ts-ignore
- NEVER commit .env files or credentials

Negative constraints are clearer than positive ones. "Prefer functional components" is vague. "NEVER use class components" is unambiguous. Claude follows "NEVER do X" more reliably than "try to do Y."

Keep this list short --- 5 to 7 items maximum. If everything is forbidden, nothing stands out.

Rule 5: Include Your Project Structure

# Structure
- src/app/         - Pages + API routes (Next.js App Router)
- src/components/  - React components (Server Components by default)
- src/lib/         - Core libraries and utilities
- supabase/schema.sql - Database schema (source of truth)
- docs/            - Internal documentation

This prevents Claude from creating files in the wrong location or misunderstanding your architecture. It's especially critical in monorepos where the same filename might exist in multiple packages.

You do not need to list every file. Just the top-level directories with a one-line description of what each contains.

Rule 6: State What Exists and What Does Not

# Status
## Working in Production
- Auth flow (magic link + OAuth)
- Full publishing pipeline
- Search with semantic + keyword

## NOT Implemented Yet
- Real-time notifications (don't build features that depend on this)
- Dispute resolution UI (schema exists, no UI)
- Update policies table (API is coded but table doesn't exist in DB)

This is a debugging time-saver that most people overlook. Without it, Claude will happily build a feature on top of another feature that does not exist, and you will not discover it until something breaks in a confusing way.

The "NOT Implemented" section is more important than the "Working" section. It tells Claude where the landmines are.

Rule 7: Add Compaction Instructions

# Context Management
When compacting or summarizing, always preserve:
- The full list of files modified in this session
- Any test commands used and their results
- Current branch name and PR context
- Any errors encountered and how they were resolved

When Claude auto-compacts (or you run /compact), it summarizes the conversation to free up context space. Without guidance, it may drop critical information like which files were changed or what tests were run.

This rule ensures that even after compaction, Claude retains the information it needs to keep working effectively.

Rule 8: Point to Docs, Don't Embed Them

# Reference Docs
- For API design decisions: read docs/MASTER-PLAN.md
- For database schema: read supabase/schema.sql
- For deployment process: read DEPLOY-PACKAGES.md
- For testing matrix: read checker.md

A common mistake is using @docs/api-guide.md to embed entire files into every session. This consumes tokens on content that may not be relevant.

Instead, tell Claude where to look and when. "For API design decisions, read docs/MASTER-PLAN.md" loads the file only when Claude is actually working on API design. The rest of the time, it stays out of the way.

Rule 9: Define Your Git Workflow

# Git
- Branch naming: feature/<name>, fix/<name>, chore/<name>
- Commit messages: conventional commits (feat:, fix:, chore:)
- Always create a new commit, never amend unless explicitly asked
- Never force push to main
- Never skip pre-commit hooks with --no-verify

Without this, Claude makes its own branching and commit decisions. These may be perfectly reasonable decisions that are completely wrong for your team's workflow.

Claude Code can create branches, commit, and push. That's powerful. It also means it can create a mess if your conventions are not explicit.

Rule 10: Set Boundaries on Autonomy

# Boundaries
- Ask before deleting files or dropping database tables
- For changes touching 5+ files, explain the plan before starting
- If tests fail twice on the same approach, stop and ask for direction
- Never modify CI/CD configuration without explicit approval

Claude Code is agentic --- it acts autonomously. This is its strength and its risk. Without boundaries, it can spiral into long chains of failed approaches, each one consuming tokens and moving further from the solution.

The "two failures then stop" rule is particularly effective. It prevents the pattern where Claude tries the same broken approach five times with minor variations, burning context and your patience.

Rule 11: Write a Self-Improvement Rule

# Learning
- When I correct you on something project-specific, add the lesson to
  .claude/lessons.md with the date, what went wrong, and the correct approach
- Before starting a task, check .claude/lessons.md for relevant past mistakes

Boris Cherny, the creator of Claude Code, describes this practice: "Anytime we see Claude do something incorrectly, we add it to CLAUDE.md so it doesn't repeat." His team also tells Claude: "Update your CLAUDE.md so you don't make that mistake again."

This creates a self-improving loop. Claude makes a mistake once. You correct it. The correction persists across every future session. Over weeks, Claude becomes dramatically better at your specific project.

Rule 12: Use Emphasis Sparingly on Critical Rules

# CRITICAL
- **ALWAYS** run typecheck after modifying TypeScript files
- **NEVER** commit .env files or credentials
- **YOU MUST** verify the build succeeds before creating a PR

Anthropic's documentation confirms that emphasis markers like "IMPORTANT" and "YOU MUST" improve adherence to specific rules. However, if everything is emphasized, nothing stands out.

Pick 3 to 5 rules maximum for emphasis. These should be the rules where a violation causes real damage --- not stylistic preferences, but things that break builds, leak secrets, or corrupt data.

The Complete Template

Here's a starter CLAUDE.md that incorporates all 12 rules. Adapt it to your project:

# Project Name

Brief description of what this project is and what it does.

# Tech Stack
- [Framework] [version]
- [Language] [mode]
- [Styling approach]
- [Database]

# Commands
- Test single file: `[command]`
- Type check: `[command]`
- Build: `[command]`
- Lint: `[command]`

# Structure
- src/app/       - [description]
- src/lib/       - [description]
- src/components/ - [description]

# Gotchas
- [Non-obvious behavior 1]
- [Non-obvious behavior 2]
- [Non-obvious behavior 3]

# Forbidden
- NEVER [pattern 1]
- NEVER [pattern 2]
- NEVER [pattern 3]

# Status
## Working: [list key working features]
## NOT Done: [list unimplemented features with warnings]

# Git
- [Branch naming convention]
- [Commit message convention]

# CRITICAL
- **ALWAYS** [critical rule 1]
- **NEVER** [critical rule 2]

# Reference Docs
- For [topic]: read [file path]

# Context Management
When compacting, preserve: modified files, test results, branch context

Keep it under 80 lines. Start with /init to generate a baseline, then add the rules that matter most for your project.

Beyond CLAUDE.md: When to Use Hooks Instead

CLAUDE.md rules are advisory. Claude follows them roughly 80% of the time. For rules that must be enforced 100% of the time, use hooks instead:

{
  "PostToolUse": [
    { "command": "eslint --fix $FILE" }
  ]
}

Think of it this way: CLAUDE.md is guidance. Hooks are law. Use CLAUDE.md for conventions and preferences. Use hooks for linting, formatting, and security checks that cannot be skipped.

FAQ

How long should my CLAUDE.md be?

Under 80 lines for the project-level file. Research suggests instruction compliance drops as rule count increases. Every line should solve a real problem you have actually encountered.

Should I commit CLAUDE.md to git?

Yes, for the project-level file. It contains project conventions that every contributor (human or AI) should follow. Keep personal preferences in ~/.claude/CLAUDE.md (global, not committed).

What's the difference between CLAUDE.md, AGENTS.md, and .cursorrules?

CLAUDE.md is for Claude Code. AGENTS.md is tool-agnostic (works with Codex, Cursor, and Claude). .cursorrules (now .mdc) is Cursor-specific. For open-source projects, ship both CLAUDE.md and AGENTS.md for maximum compatibility.

Does Claude always follow CLAUDE.md rules?

No. Compliance is roughly 80%, not 100%. For rules that must be enforced every time, use hooks instead. CLAUDE.md is guidance; hooks are deterministic.

Can Claude update its own CLAUDE.md?

Yes. You can tell Claude "add this to CLAUDE.md" or "update your CLAUDE.md so you don't make that mistake again." This is a powerful self-improvement pattern used by the Claude Code team itself.

Key Takeaways

1. Your test command is the highest-leverage rule --- it turns Claude from a code writer into a self-verifying engineer
2. Keep it under 80 lines --- compliance drops as rule count increases, so every line must earn its place
3. "Things That Will Bite You" is the most underused pattern --- stolen directly from Anthropic's own CLAUDE.md
4. Negative constraints outperform positive ones --- "NEVER use any" is clearer than "prefer strict typing"
5. CLAUDE.md is guidance, hooks are law --- use each for what it does best

Further reading: What Are AI Agent Skills? | Building MCP-Compatible Skills