第 06 期 | 规划先行：基于文件的 Task 进度体系

6.1 使用 planning-with-files Skill 规划

在 team-lead 会话中使用 /planning-with-files skill 进行规划：

步骤 1：头脑风暴（brainstorming）

与 Claude 讨论方案：

• 哪些模块可并行？
• agent 间如何协作？
• 接口约定是什么？

步骤 2：编写计划（writing-plans）

产出 task_plan.md：

# Task Plan: 双模式网页计算器（Teams 并行方案）

## 并行架构
┌─ ui-dev ──────────────┐  ┌─ logic-dev ─────────────┐
│ Phase A: HTML/CSS 骨架 │  │ Phase A: 计算引擎纯函数  │
│ Phase B: UI 交互 + a11y│  │ Phase B: 事件 + 持久化    │
└──────────┬─────────────┘  └──────────┬──────────────┘
           └────────┬──────────────────┘
                    ▼
        ┌─ qa-engineer ─────────┐
        │ Phase C: 单元+集成测试  │
        │ Phase D: E2E+验收      │
        └───────────────────────┘

6.1.1 规划文件体系

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

---

6.2 测试规则

6.2.1 TDD 循环

RED → GREEN → REFACTOR → VERIFY 禁止：跳过 RED、注释失败测试、削弱断言伪造通过。

6.3 Git 规则

6.3.1 Commit 格式

Conventional Commits：feat|fix|refactor|test|docs|chore(scope): message 项目 scope：calc | ui | a11y | mode | history

6.4 安全边界

• 无后端、无 API 调用 — 纯客户端
• localStorage 仅存模式偏好，无敏感数据
• 不引入第三方脚本

6.5 项目结构

teamtest/ ├── CLAUDE.md ├── requirement.md ├── index.html ├── style.css ├── app.js └── .agents/workflows/

### 9.3 CLAUDE.md 各章节作用解析

| 章节 | 作用 | Agent 行为影响 |
|------|------|---------------|
| **项目概览** | 让 agent 理解项目背景 | 决策时参考技术约束 |
| **技术栈** | 限制工具选择 | 不会引入 React/Vue 等框架 |
| **Teams 开发模式** | 定义分工和协作方式 | agent 知道自己负责什么、和谁协作 |
| **协作规则** | 接口约定 | ui-dev 预留 id，logic-dev 用 id 绑定 |
| **Skill 使用规则** | 强制工作流顺序 | 不会跳过 TDD 直接写代码 |
| **规划文件** | 状态持久化标准 | 统一用 [ ] [/] [x] 标记进度 |
| **自治理规则** | 自动决策边界 | 5 次失败后停止，不无限重试 |
| **安全边界** | 硬性约束 | 不引入外部脚本，不调用 API |

### 9.4 CLAUDE.md 编写最佳实践

```mermaid
flowchart LR
    subgraph "必须包含"
        A[项目概览]
        B[技术栈限制]
        C[Agent 分工]
        D[安全边界]
    end
    
    subgraph "推荐包含"
        E[Skill 流水线]
        F[测试规则]
        G[自治理规则]
        H[规划文件格式]
    end
    
    subgraph "可选"
        I[Git 规范]
        J[插件使用规则]
        K[完成规则]
    end

原则：

1. 简洁明确 — agent 读 CLAUDE.md 也消耗 token，控制在 300 行以内
2. 用表格和列表 — 比段落更容易被准确遵循
3. 写"不做什么"比"做什么"更重要 — "不要调用 Skill" > "可以调用 Skill"
4. 接口约定提前写 — "预留 id"这种跨 agent 约定必须在 CLAUDE.md 中

---