Issue 05 | CLAUDE.md: Formulating a Multi-Agent Collaboration Project Constitution

5.1 Creating CLAUDE.md — Agent Behavior Rules

This is the most important file in Teams development. All agents read this file first upon startup to understand project rules, division of labor, and workflow.

# Web Calculator — Project Conventions

## Project Overview
Web calculator for seniors and general users. Dual-mode UI.
Pure HTML/CSS/JS, no frameworks, no backend.

## Teams Development Mode
3 agents work in parallel.

### Agent Configuration
- All agents use mode: "bypassPermissions" when spawned
- Each agent runs in an independent tmux pane
- .claude/settings.json has pre-authorized common commands

### Agent Division of Labor
| Agent | Responsibilities | Can Parallelize |
|-------|------------------|-----------------|
| ui-dev | HTML + CSS + Responsive + Accessibility | ✅ |
| logic-dev | Calculation Engine + Keyboard + localStorage | ✅ |
| qa-engineer | Testing | ❌ Waits for the first two |

### Collaboration Rules
- ui-dev reserves id interfaces in HTML
- logic-dev writes pure functions, independent of DOM structure
- Each agent notifies team-lead via SendMessage upon completion

## Testing Rules
TDD: RED → GREEN → REFACTOR → VERIFY

5.2 CLAUDE.md Explained: Project Constitution

CLAUDE.md is the primary instruction file read by Claude Code in a project. The first thing every agent does after startup is read this file. It acts as the project's "constitution," defining the behavioral boundaries for all agents.

5.2.1 CLAUDE.md Loading Mechanism

flowchart TD
    A["Claude Code Startup"] --> B{"Is CLAUDE.md
in project root?"}
    B -->|Yes| C["Automatically loaded into
system context"]
    B -->|No| D["Uses default behavior"]
    C --> E["CLAUDE.md content
injected as instructions"]
    E --> F["All agents (including sub-agents)
follow these rules"]
    
    style C fill:#c8e6c9
    style F fill:#bbdefb

Key Points:

• CLAUDE.md is automatically loaded at the start of each conversation, no manual action required
• Content is injected into the system-reminder tag, with higher priority than default behavior
• All agents (team-lead, ui-dev, logic-dev, qa-engineer) read the same CLAUDE.md
• Changes to the file take effect in the next new session

5.2.2 Complete CLAUDE.md for this Project

Below is the actual CLAUDE.md used in this project, with each section having a clear purpose:

# Web Calculator — Project Conventions

## Project Overview
Web calculator for seniors and general users. Dual-mode UI: Senior Mode and Standard Mode.
Pure HTML/CSS/JS, no frameworks, no backend.

## Design Documents
| File | Content |
|------|---------|
| requirement.md | Functional/Non-functional Requirements Specification |

## Tech Stack
- HTML5 + CSS3 + Vanilla JavaScript
- No external dependencies
- Browser native APIs (localStorage, Web Audio)
- Supports Chrome, Firefox, Safari, Edge (latest 2 versions)

## Teams Development Mode
Developed using Claude Code Teams mode. 3 agents work in parallel.

### Agent Configuration
- All agents use mode: "bypassPermissions" when spawned
- Each agent runs in an independent tmux pane
- .claude/settings.json has pre-authorized common commands

### Agent Division of Labor
| Agent | Responsibilities | Can Parallelize |
|-------|------------------|-----------------|
| ui-dev | HTML Structure + CSS Theme + Responsive + Accessibility Markup | ✅ Start Immediately |
| logic-dev | Calculation Engine + Expression Parsing + Keyboard Mapping + Mode Switching Logic + localStorage | ✅ Start Immediately |
| qa-engineer | Testing Framework + Unit Tests + Integration Tests + E2E + Accessibility Tests | ❌ Wait |

### Collaboration Rules
- ui-dev and logic-dev develop in parallel, not blocking each other
- logic-dev writes pure functions, independent of DOM structure
- ui-dev reserves id and class interfaces in HTML
- qa-engineer starts testing after both agents complete
- Each agent notifies team-lead via SendMessage upon task completion

## Skill Usage Rules
### Mandatory Skills
Complex tasks start with planning-with-files.

| Task Type | Skill Pipeline |
|-----------|----------------|
| Feature Development | planning-with-files → brainstorming → writing-plans → test-driven-development → systematic-debugging → verification-before-completion → requesting-code-review |
| Bug Fixing | planning-with-files → systematic-debugging → test-driven-development → verification-before-completion |
| Planning & Research | planning-with-files → brainstorming → writing-plans |

### Sequence Rules
- Design does not skip brainstorming
- Once design is stable, do not skip writing-plans
- Use planning-with-files for tracking during execution phase
- Do not skip verification-before-completion before completion
- Use systematic-debugging for test failures, do not retry arbitrarily

## Planning Files
| File | Purpose | Update Frequency |
|------|---------|------------------|
| task_plan.md | Phases and Task Progress | Upon task start or completion |
| progress.md | Session Logs and Verification Evidence | After each meaningful work |
| findings.md | Technical Discoveries and Decisions | After each critical decision |
| bugs.md | Bug Records and Fix History | Upon each discovery or fix |

### Status Markers
- [ ] Not Started - [/] In Progress - [x] Completed - [!] Blocked

### Bug Entry Format
## BUG-XXX: Short Title
- Discovery Time: YYYY-MM-DD HH:MM
- Severity: critical | major | minor
- Symptoms: ...
- Root Cause: ...
- Fix: ...
- Regression Check: PASS | FAIL
- Self-healing Rounds: N / 5

## Self-Governance Rules
### No Repeated Requests within Approved Scope
Tasks in task_plan.md are executed directly. Stop upon encountering blockers, conflicts, risks, or security issues.

### Fix First, Report Later
Perform evidence-based fixes. Do not repeat the same type of failure. Record each attempt.

### Evidence Before Assertion
Do not claim "completion" or "pass" without fresh verification evidence.

### Self-Healing Loop
Maximum automatic fix attempts: 5. Stop and escalate if exceeded.

### Circuit Breaker Conditions
Must stop and escalate if:
- 5 fix attempts still fail
- Requirement conflicts cannot be correctly implemented
- External dependency blocked
- Next step is destructive
- Security or privacy risk discovered

### Escalation Must Include
- What failed
- What was attempted
- What evidence was collected
- What decision or input is missing