01 - 工作流方法论
从 Sice 项目开发总结的 AI 辅助开发工作流经验。
核心原则：计划先行，分块验证，增量交付
AI 辅助开发和传统开发最大的不同在于：AI 可以帮你快速写代码，但你需要给 AI 清晰的方向。
为什么需要计划先行？
- 避免方向偏离：AI 很能写代码，但如果需求不清晰，容易写偏
- 便于分块实施：大任务拆小块，每块 AI 都能理解
- 便于暂停和继续：计划写清楚，中断后回来能快速恢复上下文
计划存储规范
.claude/plans/
├── *.md # 👉 进行中/待开始（直接放一级目录）
├── completed/ # ✅ 全部完成后移入
└── archived/ # 🗘️ 取消/废弃的移入计划文档必须包含
markdown
---
created: YYYY-MM-DD
completed: YYYY-MM-DD
status: 未完成 | 已完成 | 废弃
pending:
chunk: Chunk 名称
reason: 中断原因
---
# 计划标题
**Goal:** 清晰一句话描述目标
**Architecture:** 简要架构说明
**Tech Stack:** 技术选型列表
---
## 提交策略
| Chunk | 提交信息 |
|-------|----------|
| Chunk 1: ... | feat: ... |
---
## Chunk 1: 标题
### Task 1: 任务描述
**Files:**
- Create: 文件路径
- Modify: 文件路径
- [ ] Step 1: ...
- [ ] Step 2: 验证
- [ ] Step 3: 提交
---
## 验证清单
- [ ] 单元测试通过
- [ ] 集成验证通过
- [ ] E2E 流程验证通过分块开发原则
分块标准
一个 Chunk 应该满足：
- 独立可验证：完成后能直接验证是否工作
- 粒度适中：AI 在一个会话内能完成（通常 10-50 行代码）
- 功能完整：完成后这块功能能用
何时合并 Chunk
以下情况建议合并：
- 功能关联：多个 Chunk 共同完成一个功能
- 工具关联：都是配置类工作（ESLint + Prettier）
- 基础设施：CI/CD、编辑器配置
何时分开提交
以下情况建议分开：
- 独立功能：每个 Chunk 是独立可用功能
- 不同类型：配置和功能分开
- 验证周期长：验证时间长的单独提交
验证优先原则
顺序：编码 → 验证 → 提交，不是 编码 → 提交 → 验证。
三级验证
| 验证层级 | 时机 | 验证内容 |
|---|---|---|
| 单元验证 | 每个 Chunk 完成后 | 模块单独测试通过 |
| 集成验证 | 多个 Chunk 完成后 | 模块间能正常交互 |
| E2E 验证 | 整个功能完成后 | 完整流程能跑通 |
强制要求
- 不能跳过验证直接提交：未验证的代码可能有问题
- 不能等到全部写完再验证：最后一起找 bug 很痛苦
- 敏感功能必须测试：安全相关（令牌、权限）必须验证
增量提交原则
好处
- 便于回滚：某个提交出问题，直接回滚那个提交
- 便于复查：每个提交只改一块，review 容易
- 便于溯源：出问题能快速定位哪个引入的
提交类型规范
| 类型 | 适用场景 | 示例 |
|---|---|---|
config | 依赖安装、配置文件 | config: 配置 pnpm 工作区 |
feat | 新增功能 | feat: 添加 simple-agent 示例 |
docs | 文档更新 | docs: 添加工作流方法论总结 |
fix | Bug 修复 | fix: 修复令牌验证问题 |
refactor | 重构代码 | refactor: 重构 API 路由结构 |
提交信息格式
type: 简短描述
详细说明（可选）
Co-Authored-By: Claude <noreply@anthropic.com>中断处理
如果开发需要中断，在计划文档中记录：
markdown
---
created: 2026-03-21
status: 未完成
pending:
chunk: Chunk 3
reason: 依赖 shadcn/ui Button 组件未安装
---好处：回来继续开发时，能快速记住做到哪了，为什么停下来。
总结工作流
1. 写计划文档 → 2. 拆成 Chunk → 3. 实现 Chunk
↓
4. 验证 Chunk → 5. 提交 → 6. 下一个 Chunk
↓
全部完成 → 整体 E2E 验证 → 移动计划到 completed/AI 是强大的生产力工具，但清晰的规划和严格的验证是成功的保障。