第 05 期 | CLAUDE.md：制定多 Agent 协作的项目宪法

⏱ 预计阅读 8 分钟 更新于 2026/5/7
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

5.1 创建 CLAUDE.md — Agent 行为规则

这是 Teams 开发中最重要的文件。所有 agent 启动后首先读取此文件，了解项目规则、分工、工作流。

# Web Calculator — 项目约定

## 项目概览
面向老年人和普通用户的网页计算器。双模式 UI。
纯 HTML/CSS/JS，无框架，无后端。

## Teams 开发模式
3 个 agent 并行工作。

### Agent 配置
- 所有 agent spawn 时使用 mode: "bypassPermissions"
- 每个 agent 在独立 tmux pane 运行
- .claude/settings.json 已预授权常用命令

### Agent 分工
| Agent | 职责 | 可并行 |
|-------|------|--------|
| ui-dev | HTML + CSS + 响应式 + 无障碍 | ✅ |
| logic-dev | 计算引擎 + 键盘 + localStorage | ✅ |
| qa-engineer | 测试 | ❌ 等前两者 |

### 协作规则
- ui-dev 在 HTML 中预留 id 接口
- logic-dev 写纯函数，不依赖 DOM 结构
- 每个 agent 完成后 SendMessage 通知 team-lead

## 测试规则
TDD: RED → GREEN → REFACTOR → VERIFY

5.2 CLAUDE.md 详解：项目宪法

CLAUDE.md 是 Claude Code 在项目中读取的首要指令文件。每个 agent 启动后第一件事就是读这个文件。它相当于项目的"宪法"，定义了所有 agent 的行为边界。

5.2.1 CLAUDE.md 的加载机制

flowchart TD
    A["Claude Code 启动"] --> B{"项目根目录有
CLAUDE.md?"}
    B -->|Yes| C["自动加载到
system context"]
    B -->|No| D["使用默认行为"]
    C --> E["CLAUDE.md 内容
作为指令注入"]
    E --> F["所有 agent（包括子 agent）
都遵循这些规则"]
    
    style C fill:#c8e6c9
    style F fill:#bbdefb

关键点：

  • CLAUDE.md 在每次对话开始时自动加载，不需要手动操作
  • 内容注入到 system-reminder 标签中，优先级高于默认行为
  • 所有 agent（team-lead、ui-dev、logic-dev、qa-engineer）都会读取同一个 CLAUDE.md
  • 文件变更后，下次新会话生效

5.2.2 本项目的完整 CLAUDE.md

以下是本项目实际使用的 CLAUDE.md，每个章节有明确用途：

# Web Calculator — 项目约定

## 项目概览
面向老年人和普通用户的网页计算器。双模式 UI：老年模式和标准模式。
纯 HTML/CSS/JS，无框架，无后端。

## 设计文档
| 文件 | 内容 |
|------|------|
| requirement.md | 功能/非功能需求规格 |

## 技术栈
- HTML5 + CSS3 + Vanilla JavaScript
- 无外部依赖
- 浏览器原生 API（localStorage, Web Audio）
- 支持 Chrome、Firefox、Safari、Edge（最近 2 版本）

## Teams 开发模式
使用 Claude Code Teams 模式开发。3 个 agent 并行工作。

### Agent 配置
- 所有 agent spawn 时使用 mode: "bypassPermissions"
- 每个 agent 在独立 tmux pane 运行
- .claude/settings.json 已预授权常用命令

### Agent 分工
| Agent | 职责 | 可并行 |
|-------|------|--------|
| ui-dev | HTML 结构 + CSS 主题 + 响应式 + 无障碍标记 | ✅ 立即开始 |
| logic-dev | 计算引擎 + 表达式解析 + 键盘映射 + 模式切换逻辑 + localStorage | ✅ 立即开始 |
| qa-engineer | 测试框架 + 单元测试 + 集成测试 + E2E + 无障碍测试 | ❌ 等待 |

### 协作规则
- ui-dev 和 logic-dev 并行开发，互不阻塞
- logic-dev 写纯函数，不依赖 DOM 结构
- ui-dev 在 HTML 中预留 id 和 class 接口
- qa-engineer 在两个 agent 完成后开始测试
- 每个 agent 完成任务后通过 SendMessage 通知 team-lead

## Skill 使用规则
### 必用 Skill
复杂任务从 planning-with-files 开始。

| 任务类型 | Skill 流水线 |
|----------|-------------|
| 功能开发 | planning-with-files → brainstorming → writing-plans → test-driven-development → systematic-debugging → verification-before-completion → requesting-code-review |
| Bug 修复 | planning-with-files → systematic-debugging → test-driven-development → verification-before-completion |
| 规划调研 | planning-with-files → brainstorming → writing-plans |

### 顺序规则
- 设计不跳 brainstorming
- 设计稳定后不跳 writing-plans
- 执行阶段用 planning-with-files 追踪
- 完成前不跳 verification-before-completion
- 测试失败用 systematic-debugging，不随意重试

## 规划文件
| 文件 | 用途 | 更新频率 |
|------|------|----------|
| task_plan.md | 阶段与任务进度 | 每任务开始或完成时 |
| progress.md | 会话日志与验证证据 | 每次有意义工作后 |
| findings.md | 技术发现与决策 | 每次关键决策 |
| bugs.md | Bug 记录与修复历史 | 每次发现或修复 |

### 状态标记
- [ ] 未开始  - [/] 进行中  - [x] 已完成  - [!] 阻塞

### Bug 条目格式
## BUG-XXX: 简短标题
- 发现时间：YYYY-MM-DD HH:MM
- 严重程度：critical | major | minor
- 症状：...
- 根因：...
- 修复：...
- 回归检查：PASS | FAIL
- 自愈轮次：N / 5

## 自治理规则
### 已批准范围内不重复请示
task_plan.md 中任务直接执行。遇 blocker、矛盾、风险、安全问题时停。

### 先修再报
做有依据的修复。不重复同种失败。每次尝试记录。

### 证据先于断言
无新鲜验证证据，不声称"完成"或"通过"。

### 自愈循环
最大自动修复次数：5。超过停止并升级。

### 熔断条件
必须停止并升级：
- 5 次修复仍失败
- 需求冲突无法正确实现
- 外部依赖阻塞
- 下一步有破坏性
- 发现安全或隐私风险

### 升级必须带上
- 失败了什么
- 尝试了什么
- 收集到哪些证据
- 缺少哪项决策或输入