Chapter 19 | CLAUDE.md — Project Constitution

Chapter 19: CLAUDE.md — The Project Constitution

Learning Objectives

Write a CLAUDE.md that enables any main Claude to immediately follow project rules upon entering the project.

What is CLAUDE.md?

Every project root directory can contain a CLAUDE.md file. Claude Code automatically reads it upon startup, essentially providing main Claude with "project-specific instructions."

flowchart LR
    Start["Claude Startup"] --> Read["Automatically Read
CLAUDE.md"]
    Read --> Context["Enter Session
(Project Rules Known)"]
    Context --> Work["Operate by Rules"]

    style Read fill:#fff9c4
    style Work fill:#c8e6c9

Full Startup Loading Sequence:

sequenceDiagram
    participant CC as Claude Code
    participant FS as File System
    participant MC as main Claude

    Note over CC: User types claude
    CC->>FS: Read ~/.claude/settings.json (User-level)
    CC->>FS: Read .claude/settings.json (Project-level)
    CC->>FS: Read .claude/settings.local.json (Local)
    Note over CC: Settings merged
    CC->>FS: Read CLAUDE.md
    CC->>FS: Index .claude/agents/*.md
    CC->>FS: Index .claude/commands/*.md
    CC->>FS: Register hooks (specified in settings.json)
    CC->>MC: Start main Claude
Inject merged rules + CLAUDE.md
    Note over MC: I now know
- I am the dispatcher
- 7 agents are schedulable
- /dev command exists
- bypassPermissions mode

→ Changes to CLAUDE.md require a session restart to be reloaded (this is the source of the answer to Q11).

Essential Sections of CLAUDE.md

flowchart TB
    CLAUDE["CLAUDE.md"] --> S1["1. Project Overview
(One sentence + Tech Stack)"]
    CLAUDE --> S2["2. Single Source of Truth
(Where are specs / changes)"]
    CLAUDE --> S3["3. Role Dispatch
(Who is dispatcher, who does what)"]
    CLAUDE --> S4["4. State Machine
(How to read state, how to transition)"]
    CLAUDE --> S5["5. Dispatch Protocol
(Briefing template for each dispatch)"]
    CLAUDE --> S6["6. Things Not To Do
(Hard Constraints)"]
    CLAUDE --> S7["7. Command Quick Reference"]

    style CLAUDE fill:#fff9c4

Core Tenet: Dispatcher, Not Doer

CLAUDE.md must hardcode this statement:

You (main Claude) are the dispatcher, not the doer.
Your job is to dispatch 4 subagents, not to directly modify src/, tests/, or openspec/specs/.

→ Without this, main Claude will casually write code itself — rendering the multi-agent design useless.

Example: Our CLAUDE.md (Simplified Version)

# doc2video — Project Rules

Compile markdown tutorial documents into videos with voiceovers, subtitles, and real terminal operations.
Primary language Python 3.11+, platform macOS (MVP).

## Chapter 19: Single Source of Truth

| Information | File |
|---|---|
| Current System Commitments | openspec/specs/ |
| In-progress Changes | openspec/changes/<active>/ |
| Current Tasks | openspec/changes/<active>/tasks.md |

## Chapter 19: Role Dispatch (You are the dispatcher, not the doer)

| Agent | Responsibilities | Writable |
|---|---|---|
| developer | Implement tasks | src/, tasks.md (checkboxes only) |
| tester | Write unit tests | tests/, test-reports/ |
| ... |

Forbidden: You are not to Edit src/ or tests/.

## Chapter 19: Task Granularity: By "Group"

Dispatch units are groups defined by ## N. headings, not individual tasks.

## Chapter 19: State Machine

PENDING → DEVELOPING → TESTING → REVIEWING → GROUP_DONE
            ↑          ↓ FAIL    ↓ REJECT
            └──────────┴─────────┘

## Chapter 19: State Reading (Reread files each round, no in-memory state)

| To Know | Read What |
|---|---|
| Is Group N DEV complete | All - [ ] under tasks.md ## N. have changed to - [x] |
| Group N tests passed | test-reports/N.md contains **Status:** PASS |
| ...

## Chapter 19: Dispatch Protocol for a Group

[Briefing template to accompany dispatch at each stage...]

## Chapter 19: Things Not To Do

- Do not directly Edit src/, tests/, openspec/specs/
- Do not let the developer write tests
- ...

Why State Reading Needs to Be So Detailed

Without explicit state reading rules:
  main Claude doesn't know "how to determine if Group N is complete"
  → May make arbitrary judgments based on intuition
  → May say it's complete one moment, then not complete the next
  
With hardcoded state reading rules:
  "Check checkboxes in tasks.md + Status field in review/N.md"
  → No reliance on intuition
  → File state changes → main Claude knows immediately

→ A file-based state machine is the foundation of this system's reliability (detailed in Ch 20).

CLAUDE.md Writing Conventions

Anti-patterns

❌ CLAUDE.md written as a README ("Project is written in Python, runs tests with pytest")
   → README is for developers; CLAUDE.md is for main Claude, focusing on dispatch rules

❌ No hard constraint "You are the dispatcher"
   → main Claude will write code itself

❌ Vague terms for state reading ("check progress")
   → Cannot be executed mechanically

❌ Copying all agent system prompts into it
   → Duplication + maintenance nightmare; agent files are already independent

❌ Too long (>500 lines)
   → Consumes main conversation context, high cost per session

CLAUDE.md vs. Agent File Boundaries

CLAUDE.md describes: Cross-agent protocols (who goes first, state machine, which files to read)
Agent files describe: Specific behavior of a single agent (inputs, workflow, output format)

❌ Writing agent internal behavior into CLAUDE.md
❌ Duplicating the state machine in every agent file

What You Can Do Now

• Write a 7-section CLAUDE.md
• Explain why the "dispatcher tenet" is essential
• Distinguish the content boundaries between CLAUDE.md and agent files

The next chapter will thoroughly explain the "file-based state machine" — the source of the entire system's reliability.