计划文档规范
存储位置规范
计划文档按状态分类存储在 .claude/plans/ 目录：
.claude/plans/
├── *.md # 👉 进行中/待开始的计划（直接放在一级目录）
├── completed/ # ✅ 已完成的计划（整体工作完成后移入）
└── archived/ # 🗘️ 已废弃/取消的计划（移入不再执行）- 新产品功能或重构计划创建时，直接放在
.claude/plans/根目录 - 整体工作全部完成后，自动移动到
.claude/plans/completed/ - 计划被取消或不再执行时，将移动到
.claude/plans/archived/
语言规范
- 计划文档名、内容和输出优先使用中文
- 代码示例中的注释使用中文
- 提交信息可使用中文或英文，保持一致
元数据规范
每个计划文档必须包含 Meta 元数据块：
markdown
---
created: 2026-03-21
completed: 2026-03-21
status: 未完成 | 已完成 | 废弃
---更新规则
- 创建计划时：设置
created和status: 未完成 - 执行完成时：更新
completed和status: 已完成 - 未完成中断时：记录未完成的 Chunk 和原因
中断记录示例
markdown
---
created: 2026-03-21
status: 未完成
pending:
chunk: Chunk 3
reason: 依赖 shadcn/ui Button 组件未安装
---提交策略
分块提交原则
每个 Chunk 完成并验证后进行 git 提交，而非整体完成后再提交：
- 验证后提交：每个 Chunk 必须先验证（构建/测试/检查），验证通过后再提交
- 合理合并：相关联的 Chunk 可以合并提交，减少提交次数
- 提交粒度：每个提交应是一个独立、可验证的变更单元
提交类型
根据 Chunk 内容选择正确的提交类型：
| 内容类型 | 提交类型 | 示例 |
|---|---|---|
| 依赖安装、配置文件 | config | config: 配置 React Router 路由 |
| 功能实现 | feat | feat: 添加主布局和侧边栏组件 |
| 文档更新 | docs | docs: 更新安装说明 |
| Bug 修复 | fix | fix: 修复路由跳转问题 |
提交时机示例
Chunk 1 → 验证 → 提交
Chunk 2 → 验证 → 提交
Chunk 3 + Chunk 4 → 合并验证 → 提交合并 Chunk 的判断标准
以下情况建议合并多个 Chunk：
- 功能关联：多个 Chunk 共同完成一个功能（如主题切换 + 页面组件）
- 工具关联：多个 Chunk 是同一类工具的配置（如 ESLint + Prettier）
- 基础设施：CI/CD、编辑器配置等基础设施相关内容
以下情况建议分开提交：
- 独立功能：每个 Chunk 是独立可用的功能
- 不同类型：配置类和功能类分开提交
- 验证周期长：验证时间较长的 Chunk 单独提交
计划文档结构
markdown
# 标题
> **For agentic workers:** 必须使用 superpowers 执行计划
**Goal:** 目标描述
**Architecture:** 架构说明
**Tech Stack:** 技术栈
---
## 提交策略
| Chunk | 提交信息 |
|-------|----------|
| ... | ... |
---
## Chunk N: 标题
### Task X: 任务标题
**Files:**
- Create: 文件路径
- Modify: 文件路径
- [ ] **Step 1: 步骤描述**
- [ ] **Step 2: 验证步骤**
- [ ] **Step N: 提交步骤**
---
## 验证清单
- [ ] **单元验证**: 各模块单独测试通过
- [ ] **集成验证**: 服务能正常启动，关键端点可访问
- [ ] **E2E 验证**: 必须进行端到端测试验证，完成完整对话流程测试和验证
测试用例沉淀要求
每完成一个功能模块，必须同步添加对应的单元测试用例：
- 按模块组织：
agent/test/test_模块名.py，一个模块对应一个测试文件 - 一个测试验证一个行为：每个测试函数只验证一个特定功能点或边界条件
- 不依赖外部服务：单元测试不访问网络、数据库或外部 API
- 快速执行：所有单元测试应能在 10 秒内完成
- 命名清晰：
test_功能名()，清晰表达测试内容 - 使用中文：所有注释、打印信息、错误提示都使用中文，便于团队理解
收益：
- 后续重构能快速发现回归问题
- 新人能通过测试用例理解代码预期行为
- 问题排查能通过测试用例快速定位
强制验证要求
完整功能开发完成后，必须进行 E2E 端到端验证：
- 启动验证: 两种启动方式（LangGraph CLI、自定义 CLI）都能正常启动
- 端点验证:
/health返回 200，/chat能正常输出 SSE 流 - 环境变量验证:
.env文件加载和环境变量覆盖正常工作 - 流式验证: 前端能正确解析 SSE 流式响应
不能仅完成单元测试就宣告完成，必须实际启动服务并验证端到端工作流程
注意事项
- 验证优先：任何时候都应先验证再提交，未验证的代码不应提交
- 增量提交：避免大爆炸式提交，每个提交应可独立回滚
- 原子性：每个 Chunk 应是原子操作，要么全部成功，要么全部回滚