1. Determine scope: User-level (

   ~/.claude/

   ) or project-level (

   .claude/

   )?
2. Apply WHAT/WHY/HOW framework (project-level only)
3. Keep instructions under budget: ~50 for user-level, ~100 for project-level
4. Never use Claude as a linter: Style rules belong in tooling, not CLAUDE.md
5. Validate with quality checklist before finalizing

"The only thing that the model knows about your codebase is the tokens you put into it."

• Personal working style preferences
• Relationship dynamics (pushback, honesty, communication)
• Universal philosophy (YAGNI, root-cause debugging)
• Proactiveness boundaries

• Project-specific commands (build, test, lint)
• Tech stack details
• Style rules that vary by project
• Tool/framework references that don't exist everywhere

• Project purpose in one sentence
• Primary language/framework
• Key directories and their purposes

• Non-obvious architectural decisions
• Constraints that affect implementation choices

• Essential commands: build, test, lint, run
• Any project-specific workflows
• Where to find more documentation

• "NEVER skip tests" = 1 instruction
• "Use TypeScript for new files" = 1 instruction
• A 5-item list = 5 instructions

• Naming conventions with specific examples
• Comment formatting rules
• Whitespace/indentation requirements
• File header requirements (ABOUTME, copyright)

• ESLint/Biome for JavaScript/TypeScript style
• Black/Ruff for Python formatting
• Pre-commit hooks for file headers
• Claude Code Hooks to run formatters

• ✓ "Names should describe purpose, not implementation"
• ❌ "Never use names like ZodValidator or MCPWrapper"

• Code conventions: See

  docs/conventions.md

• API patterns: See

  docs/api-design.md

• Testing philosophy: See

  docs/testing.md

**Benefits**:
- Keeps CLAUDE.md focused
- Claude reads docs only when relevant
- Easier to maintain separate concerns

• Every instruction applies to every session (user-level) or every task in project (project-level)
• No project-specific commands in user-level config
• No tool references that may not exist

• Under instruction budget (count them)
• No redundancy with Claude Code's built-in behaviors
• Examples trimmed or moved to reference docs

• No specific naming convention examples
• No comment formatting rules
• No file header requirements
• Style guidance limited to philosophy, not specifics

• Complex topics reference external docs
• Main file under 100 lines (user) or 150 lines (project)
• Examples in reference files, not inline

• Consistent heading hierarchy
• No conflicting instructions
• Actionable directives, not vague guidance

1. Over-specification: Including every preference instead of universally critical ones
2. Style enforcement: Detailed naming/comment rules that Claude follows inconsistently
3. Stale commands: Build/test commands that drift from actual tooling
4. Auto-generation: Using

   /init

   instead of hand-crafting
5. Tool assumptions: Referencing MCP servers or tools that aren't always available
6. Conflicting rules: "Match surrounding style" + "Never use X pattern"
7. Instruction inflation: Adding rules after each frustration instead of fixing root cause

• Quick one-off projects (just use defaults)
• Projects with existing, well-maintained CLAUDE.md
• When the team already has established patterns

• User-level: Symlink to

  ~/.claude/CLAUDE.md

  or place directly
• Project-level: Commit to

  .claude/CLAUDE.md

  in repository root
• Validation: Start a new Claude Code session and observe if instructions are followed