1. Identify primary working directory
   └─> Use file modification counts and command context

2. Classify content type
   └─> Use Content Classification Criteria table

3. Apply decision rules:

   IF content applies ONLY to identified directory:
       └─> Target: subdirectory CLAUDE.md

   ELSE IF content applies to multiple directories:
       └─> Target: root CLAUDE.md

   ELSE IF content is architectural/cross-cutting:
       └─> Target: root CLAUDE.md

   ELSE IF uncertain:
       └─> Ask user for clarification

# [Component Name]

[One-line description of this component's purpose]

## Commands

### Development
```bash
# Component-specific development commands

# Component-specific test commands

### Content Scope Rules

**Subdirectory CLAUDE.md should contain:**
- Commands run from this directory
- Conventions specific to this component
- Architecture of this component only
- Dependencies unique to this component
- Gotchas specific to this component

**Subdirectory CLAUDE.md should NOT contain:**
- General project conventions (belongs in root)
- Commands run from project root
- Cross-component architecture
- Shared dependencies
- Monorepo-wide workflows

## Targeting Examples

See `references/targeting-examples.md` for detailed examples of target file selection.

# Auto-Loaded Files & Advanced Patterns

For detailed documentation on auto-loaded files, CLAUDE.md vs .claude/ directory, monorepo patterns, and @import syntax, see `references/advanced-patterns.md`.

**Key rules:**
- `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md` are auto-loaded at startup
- Files named `CLAUDE-API.md` or `CLAUDE-FRONTEND.md` are NOT auto-loaded -- use subdirectory CLAUDE.md or @import
- `.claude/` directories in subdirectories are IGNORED -- only project root or `~/.claude/` are recognized
- Use subdirectory `CLAUDE.md` for simple instructions; use `.claude/skills/` with `paths:` for complex scoped logic
- Use `@import` to modularize single-project documentation (e.g., `@./docs/api-guidelines.md`)

# CLAUDE.md Template Structure

See `references/template.md` for the full CLAUDE.md starter template.

## Section Priority

Order sections by frequency of use:

1. **Commands**: Most frequently needed information
2. **Architecture**: Understanding the codebase
3. **Workflow**: How to work with the project
4. **Notes/Gotchas**: Avoiding common problems
5. **Other sections**: As relevant to the project

# Example Update Scenarios

See `references/update-scenarios.md` for detailed update examples.

# Large Projects Tips

For extensive documentation:
- Use clear section headers for navigation
- Include a table of contents for long files (use @import to modularize)
- Cross-reference related sections
- Consider subdirectory CLAUDE.md files for isolated components
- Use skills with `paths:` field for complex, scoped logic

# Content Placement by Frequency

When deciding what belongs directly in CLAUDE.md versus an external file:

| Content Type | Placement | Example |
|--------------|-----------|---------|
| High-frequency (used most sessions) | Inline in CLAUDE.md | Commands, architecture, workflow |
| Low-frequency (used occasionally) | @import or inline | Testing gotchas, environment notes |
| Rarely-needed (one-time setup) | External file with summary reference | MCP setup guides, onboarding steps |

**Principle**: CLAUDE.md should prioritize content that is useful in the majority of sessions. Rarely-needed content (one-time setup, infrequent procedures) should be extracted to external files and replaced with a one-liner summary that tells Claude WHEN to offer the guide and WHERE to find it.

# Anti-Patterns

**Do NOT:**
- Create files like `CLAUDE-API.md` or `CLAUDE-FRONTEND.md` (not auto-loaded)
- Place `.claude/` directories in subdirectories (ignored by Claude Code)
- Default to root CLAUDE.md without analyzing session context
- Add subdirectory-specific content to root CLAUDE.md
- Duplicate root CLAUDE.md content in subdirectories
- Create subdirectory CLAUDE.md for trivial or single-use information
- Mix component-specific and project-wide content in same file
- Keep one-time setup procedures inline when they could be extracted with a summary reference
- Include general programming knowledge (Claude already knows this)
- Write tutorials on basic syntax
- Copy documentation that exists elsewhere (use @import instead)
- Make sections too verbose (use references/ in skills for details)
- Use inconsistent heading levels
- Include sensitive information (API keys, passwords)

**DO:**
- Systematically analyze session context before choosing target file
- Use content classification criteria to determine target
- Ask user when uncertain about target file
- Use subdirectory CLAUDE.md files for component-specific guidance
- Keep subdirectory CLAUDE.md focused and minimal
- Use @import for modularizing single-project documentation
- Focus on project-specific conventions and decisions
- Keep commands and examples up-to-date
- Include "why" behind non-obvious decisions
- Cross-reference related sections
- Use code blocks with syntax highlighting
- Extract rarely-needed content (one-time setup, infrequent procedures) to external files with summary references
- Verify no duplicate information exists across CLAUDE.md files