CLAUDE.md

comment explaining why Claude needs this information. Remove these comments when you adapt this template for your project.

For deeper reasoning, see CLAUDE-MD-GUIDE.md in this directory. -->

This file provides guidance to Claude Code when working with this repository.

What is {{PROJECT_NAME}}?

Problem: {{Describe the problem this project solves}}

Solution: {{Describe how this project solves it}}

For: {{Who is this built for? Be specific.}}

Quick Start

# Build
{{build command}}

# Test
{{test command}}

# Run
{{run command}}

# Development
{{watch/dev command if applicable}}

Current State

Active development: {{Where is current work happening?}}

Test coverage: {{Current coverage if tracked}}

Architecture

Why This Structure

{{Layer 1}}    → {{path/}}    {{Brief description}} (WHY: {{reasoning}})
{{Layer 2}}    → {{path/}}    {{Brief description}} (WHY: {{reasoning}})
{{Layer 3}}    → {{path/}}    {{Brief description}} (WHY: {{reasoning}})

Key Flow

{{command/action}}
  → {{step 1}}
  → {{step 2}}
  → {{step 3}}
  → {{output}}

Key Decisions & Rationale

Common Tasks

{{Task 1: e.g., Adding a Feature}}

Exemplar: {{path/to/good/example}} — {{why this is a good example}}

1. {{Step 1}}
2. {{Step 2}}
3. {{Step 3}}

{{Task 2: e.g., Adding a Test}}

Exemplar: {{path/to/good/example}}

1. {{Step 1}}
2. {{Step 2}}
3. {{Step 3}}

Testing

Philosophy

• Coverage target: {{e.g., 80% — not 90%+ due to diminishing returns}}
• Test style: {{e.g., Table-driven tests, BDD, etc.}}
• Mocking approach: {{e.g., Real implementations preferred, mocks for external services}}

Exemplary Test Files

Running Tests

{{test commands with explanations}}

Constraints & Anti-patterns

Constraints

• {{Constraint 1}} — {{why this constraint exists}}
• {{Constraint 2}} — {{why this constraint exists}}
• {{Constraint 3}} — {{why this constraint exists}}

Anti-patterns to Avoid

• Don't {{anti-pattern 1}} — {{what to do instead}}
• Don't {{anti-pattern 2}} — {{what to do instead}}
• Don't {{anti-pattern 3}} — {{what to do instead}}

Questions to Ask Before Writing Code

1. {{Question 1, e.g., "Does this follow our established patterns?"}}
2. {{Question 2, e.g., "Is there an existing abstraction I should use?"}}
3. {{Question 3, e.g., "How will I test this?"}}

Data / File Structure

{{project_root}}/
├── {{dir1}}/              # {{purpose}}
│   ├── {{subdir}}/        # {{purpose}}
│   └── {{file}}           # {{purpose}}
├── {{dir2}}/              # {{purpose}}
└── {{config_file}}        # {{purpose}}

References

---