开发工作流

工程原则

六条铁律，适用于所有流程：

1. 无计划不编码 — 动手前必须有书面方案（设计文档、实施计划、或 markdown 步骤清单）
2. 无测试不改码 — 修改代码前必须有测试覆盖：新功能先写失败测试，bug 先写复现测试
3. 无审查不发布 — 代码变更必须经过审查（工具审查或自查 diff），不能跳过
4. 无根因不修复 — bug 修复前必须定位根因，禁止猜测试探
5. 无安全网不重构 — 重构前必须有测试覆盖，小步推进，每步可独立验证
6. 改了代码必须改文档 — 文档落后于代码 = 技术债务

阶段自检

完成任何阶段后，确认以下三项：

• 做了什么: 一句话描述当前阶段的产出
• 下一步是什么: 明确下一个阶段
• 有无跳过: 如跳过了某个步骤，说明原因（"觉得没必要" 不是正当理由）

场景引导

收到任务后，按以下决策链选择流程：

1. 会改代码吗？
   ├── 不会 → 纯评估/分析/调研 → 流程E
   └── 会 →
       2. 是生产紧急问题吗？（线上挂了、大面积受影响）
          ├── 是 → 流程F
          └── 否 →
               3. 是依赖/框架升级吗？
                  ├── 是 → 流程G
                  └── 否 →
                       4. 现有功能有正确行为可参考吗？
                          ├── 有，但它坏了 → 流程B
                          ├── 有，但要推倒重来 → 流程C
                          ├── 有，但要调整内部实现（行为不变）→ 流程D
                          └── 没有，这是全新的 → 流程A

边界判定:

易混淆	区分标准
Bug vs 重做	预期行为已定义但产出不对 → Bug；预期行为本身要改 → 重做
重构 vs 重做	外部接口不变 → 重构；接口/契约变化 → 重做
重构 vs 新功能	不改变用户可见行为 → 重构；用户有新能力 → 新功能
评估 vs 重构	只看不摸 → 评估；动手改 → 重构
评估 vs 新功能	回答"要不要做" → 评估；直接开始做 → 新功能
Bug vs 紧急修复	非紧急可走完整TDD → Bug；线上挂了需立刻修 → 紧急修复
升级 vs 重构	只改版本号不改代码 → 升级；改动内部实现 → 重构

一句话速判:

不知道要不要做 → E · 线上挂了 → F · 它坏了 → B · 它没错但要翻新 → C · 它没错但要更好 → D · 全新 → A · 升级依赖 → G

场景路由

场景	典型关键词	走哪个流程
新功能	"新增"、"开发"、"实现"、"添加"	流程A: 新功能开发
Bug修复	"修复"、"报错"、"bug"、"坏了"	流程B: Bug修复
功能重做	"重做"、"重写"、"翻新"XX模块	流程C: 功能重做
优化重构	"优化"、"重构"、"改进"XX模块	流程D: 模块优化重构
功能评估	"评估"、"分析"、"调研"、"是否值得"、"可行性"	流程E: 功能评估
紧急修复	"紧急"、"线上"、"hotfix"、"挂了"、"崩了"	流程F: 紧急修复
依赖升级	"升级"、"更新版本"、"依赖"	流程G: 依赖升级

不适用: 单行修复、改配置、改文案 — 直接改即可。

可选工具套件

三个工具套件可以加速流程，但不是硬依赖。下方流程步骤中每个外部技能都有"如可用/否则"双路径。

技能名称约定: 带 / 前缀的是 slash 命令（gstack），不带前缀的是技能名（Superpowers）。两者都通过 Skill 工具调用。

如何判断工具是否可用: 尝试调用技能（通过 Skill 工具）。如果技能不存在，执行"否则"路径。

工具套件	技能名	不可用时
gstack	/plan-eng-review, /review, /investigate, /ship, /document-release, /office-hours, /plan-ceo-review, /freeze	见各流程步骤中的"否则"路径
Superpowers	writing-plans, executing-plans, subagent-driven-development, requesting-code-review, test-driven-development	见各流程步骤中的"否则"路径
planning-with-files	planning-with-files-zh	手工创建和维护 task_plan.md（带复选框）、progress.md（进度记录）、findings.md（发现记录）

安装缺失套件: 当流程中反复命中"否则"路径时，提示用户安装对应套件以获得更佳体验。安装方式取决于用户环境，常见的：

套件	典型安装方式
gstack	npx gstack install 或参考 gstack 文档
Superpowers	将 Superpowers 技能目录链接到 ~/.claude/skills/ 或 ~/.qoder/skills/
planning-with-files	将技能目录链接到 ~/.claude/skills/ 或 ~/.qoder/skills/

如果用户明确表示不需要某个套件，后续不再提示。

---

流程A: 新功能开发

阶段1(意图) → 阶段2(规划) → 阶段3(执行) → 阶段4(收尾)

步骤	命令	说明
1. 架构审查	如可用: /plan-eng-review · 否则: 手写设计文档(数据流、接口、边界、权衡)	新功能必做
2. 产品决策	如可用: /office-hours 或 /plan-ceo-review · 否则: 与用户直接确认范围和验收标准	可选
3. 写实施计划	如可用: writing-plans · 否则: 手写 markdown 实施步骤清单
4. 初始化进度	如可用: planning-with-files-zh · 否则: 手工创建 task_plan.md 带复选框
5. 编码	如可用: subagent-driven-development 或 executing-plans · 否则: 逐步实现(写失败测试→通过→重构)	严格 TDD
6. 每task审查	如可用: requesting-code-review · 否则: 自查每个完成步骤的 diff
7. 全部完成审查	如可用: /review · 否则: 完整自查 diff (SQL安全/错误处理/边界/风格)
8. 更新文档	如可用: /document-release · 否则: 手工更新 README/CHANGELOG/架构文档
9. 提交发布	如可用: /ship · 否则: 手工 merge → 测试 → commit → push → 创建 PR

完成条件: 设计文档已写 → 实施计划已确认 → 所有测试通过 → 代码已审查 → 文档已同步 → PR 已创建。

禁止: 新功能跳过架构审查（步骤1不可跳过）。跳过审查直接发布。边写边改实施计划。未更新文档就提交。

---

流程B: Bug修复

核心原则: 先定位再修改，禁止先改代码再找原因。

定位根因 → 复现测试 → 修复 → 审查 → 提交

步骤	命令	说明
1. 定位根因	如可用: /investigate · 否则: 手工追踪代码路径、加日志、git bisect	禁止先改代码
2. 写复现测试	如可用: test-driven-development · 否则: 手工写失败测试复现 bug	先红
3. 修复	编码	最少改动让测试通过（绿）
4. 跑全量测试	运行全量测试	确认无回归
5. 审查	如可用: requesting-code-review · 否则: 自查 diff 的正确性和最小性
6. 更新文档	如可用: /document-release · 否则: 手工更新文档	如根因值得记录
7. 提交	如可用: /ship · 否则: 手工 commit → push → 创建 PR

跨模块 bug → 步骤1如 gstack 可用: /investigate + /freeze，否则手工锁定调查范围。同一问题失败3次 → 写入 findings.md，停止并汇报。

完成条件: 根因已定位并记录 → 复现测试已通过（修复前红，修复后绿） → 全量测试无回归 → diff 已审查确认最小性。

禁止: 跳过根因定位直接改代码。越过复现测试直接修复。修复时顺手改无关代码或重构。不跑全量测试就提交。

---

流程C: 功能重做

核心原则: 先理解旧实现的接口契约和调用方，再设计新方案。

分析旧实现 → 架构审查 → 接流程A（步骤4起：初始化进度→编码→审查→发布）

步骤	命令	说明
1. 分析旧实现	读代码 + Explore 子代理	理清：接口签名、调用方、数据流、测试覆盖
2. 架构审查	如可用: /plan-eng-review · 否则: 手写新旧方案对比文档
3. 之后	接流程A 步骤4起（初始化进度→编码→审查→发布）	已有架构审查(步骤1-2)和方案(本步骤)，跳过A的步骤1-3

关键约束: 接口签名不兼容变更时必须列出所有调用方。有测试覆盖的旧代码，先确认测试是否仍然有效。

完成条件: 旧实现所有调用方已列出 → 新旧方案已对比 → 接流程A 完成条件。

---

流程D: 模块优化重构

核心原则: 测试先行作为安全网，小步重构，每步可独立验证。

补测试 → 识别瓶颈 → 小步重构 → 逐步验证 → 审查 → 提交

步骤	命令	说明
1. 补测试	编码	如果模块测试覆盖不足，先补测试建立安全网
2. 识别瓶颈	如可用: /plan-eng-review · 否则: 手工分析性能/结构问题，定重构边界
3. 拆解计划	如可用: writing-plans · 否则: 手工写小步重构清单，每步可独立跑测试
4. 逐步重构	如可用: executing-plans · 否则: 手工逐步执行：改 → 测试 → 绿 → 下一步
5. 每步审查	如可用: requesting-code-review · 否则: 每步完成后自查 diff
6. 全量测试	运行全量测试 + 代码格式检查	确认无回归
7. 审查	如可用: /review · 否则: 完整自查 diff
8. 更新文档	如可用: /document-release · 否则: 手工更新架构文档
9. 提交	如可用: /ship · 否则: 手工 commit → push → PR

禁止: 没有测试安全网就重构。跨多模块一次性大改。重构同时加新功能。

完成条件: 测试安全网已建立 → 每步重构测试通过 → 全量测试无回归 → 行为与重构前一致。

---

流程E: 功能评估

核心原则: 基于事实分析，不凭直觉判断。评估结论必须有代码/数据支撑。

明确目标 → 信息收集 → 分析评估 → 输出结论

步骤	命令	说明
1. 明确目标	如可用: /office-hours · 否则: 与用户直接确认评估范围和判定标准
2. 收集信息	读代码 + Explore 子代理	理清现状：架构、调用链、数据流、性能数据、瓶颈
3. 分析评估	如可用: /plan-eng-review · 否则: 手工多维度分析(可行性/风险/成本/收益)	至少对比2种方案
4. 输出结论	写入 findings.md	结论+建议+行动计划，标注关键证据来源

评估维度参考:

维度	关注点
技术可行性	现有架构是否支持？需要改多少？引入新依赖？
风险	是否影响核心流程？回滚难度？数据一致性？
成本	开发量、测试量、运维复杂度
收益	解决什么问题？影响多少用户？可量化吗？
替代方案	有没有更简单的做法？不做的后果？

禁止: 没看代码就下结论。只列优点不提风险。评估后直接开写（必须先输出结论文档）。

完成条件: 至少对比2种方案 → 每种方案覆盖5个评估维度 → 结论文档已写入 findings.md → 结论明确标注证据来源。

---

流程F: 紧急修复

核心原则: 线上优先止损，恢复服务第一，根因分析第二。事后必须补测+复盘。

定位止损 → 最小修复 → 验证上线 → 事后补测

步骤	命令	说明
1. 定位止损	如可用: /investigate · 否则: 手工快速定位根因	先止血（回滚/切流/关功能）
2. 最小修复	编码	只改必要代码，跳过完整 TDD。禁止顺手重构
3. 验证上线	如可用: /ship · 否则: 手工确认修复有效并提交推送
4. 事后补测	如可用: test-driven-development · 否则: 手工补复现测试+回归测试	修复上线后同一会话内必做
5. 复盘	写入 findings.md	记录根因、修复过程、预防措施

规则: 流程F 可跳过审查和 TDD（当时），但事后必须补测试。同一问题出现 2 次紧急修复 → 升级为流程C（重做）。禁止以"紧急"为借口跳过事后补测。

完成条件: 线上已止血 → 修复已验证上线 → 事后补测已完成 → 复盘记录已写入 findings.md。

---

流程G: 依赖升级

核心原则: 升级不改功能，兼容性检查优先，保留回滚路径。

兼容分析 → 升级计划 → 逐步升级 → 全量测试 → 审查 → 更新文档 → 提交

步骤	命令	说明
1. 兼容分析	读 CHANGELOG + Explore	确认 breaking changes、废弃 API、新要求（语言/运行时版本）
2. 升级计划	如可用: /plan-eng-review · 否则: 手工确定升级范围、顺序、回滚方案
3. 逐步升级	编码	逐包升级：更新依赖 → 运行测试 → 绿 → 下一个
4. 全量测试	运行全量测试 + 代码格式检查	确认无回归
5. 审查	如可用: /review · 否则: 完整自查 diff
6. 更新文档	如可用: /document-release · 否则: 手工更新技术栈版本、依赖说明
7. 提交	如可用: /ship · 否则: 手工 commit → push → PR

升级清单:

检查项	说明
CHANGELOG	必读每个包的 release notes
breaking changes	搜索 BREAKING、deprecated、removed
版本约束	确认依赖配置文件版本范围正确
环境要求	语言版本、运行时要求、系统依赖
锁文件	提交依赖锁文件变更
回滚方案	记录回滚步骤，必要时保留旧版分支

禁止: 不看 CHANGELOG 就升级。多包混合批量升级。升级同时加新功能或重构。无回滚方案直接升级。

完成条件: CHANGELOG 已逐包阅读 → 逐包升级每包测试通过 → 全量测试无回归 → 回滚方案已记录 → 文档已更新。

---

测试隔离规则

技能测试或子代理实验禁止在主工作区执行，必须用 git worktree 隔离：

git worktree add /tmp/task-test -b test/task-name
# 子代理在 /tmp/task-test 里操作
git worktree remove /tmp/task-test --force
git branch -D test/task-name

持久化规则（强制）

有 planning-with-files 用其技能（如可用: planning-with-files-zh），否则手工维护这些文件。

时机	操作
会话开始	检查 task_plan.md 是否存在，读取当前进度
每完成一个 Task	更新 task_plan.md（打勾）+ progress.md（记录）
发现关键信息	写入 findings.md
上下文即将耗尽时	必须先更新 progress.md，然后开启新会话，新会话从 progress.md 恢复

文档更新规则

代码变更后必须确保项目文档与代码一致。各流程步骤表中已标注"更新文档"步骤及对应工具。通用原则：改了什么，就更新对应的描述文档。文档落后于代码 = 技术债务。

版本号

手工发布时（/ship 不可用）：

• 按语义版本规则 bump 版本号（通常改 VERSION 文件、package.json 或等效位置）
• 在 CHANGELOG 中记录本次变更
• 版本号和 CHANGELOG 应包含在同一个 commit 中

禁止事项

• ❌ 无书面计划直接编码
• ❌ 修改代码前不写测试
• ❌ 上下文耗尽前不更新 progress.md
• ❌ 定位根因之前修改代码
• ❌ 跳过审查直接发布
• ❌ 重构时无测试安全网
• ❌ 技能测试/子代理实验在主工作区执行

常见错误与 Red Flags

反模式	后果	正确做法
"这个bug很简单，直接改"	治标不治本、引入新bug	先定位根因（如可用 /investigate，否则手工排查），写复现测试
"重构顺手加个功能"	混杂变更、难以审查	重构和新功能必须分开走不同流程
"测试后面再补"	TDD 被反转	先写失败测试 → 实现 → 通过
"旧代码我大概懂了"	破坏调用方	必须列出所有调用方和接口签名
"跳过审查直接发布"	缺少审查	审查是强制步骤，不能只在脑中过一遍
"线上紧急，先改了再说"	事后永远不补	走流程F，事后必补测试
"升级应该没风险"	引入兼容性故障	先读 CHANGELOG，必须有回滚方案
跳过架构审查直接写代码	方案错误	新功能必走架构审查（如可用 /plan-eng-review，否则手写设计文档）
不更新 progress.md	会话中断后丢失进度	每次变更后更新

异常处理

情况	处理方式
步骤执行失败	停止当前步骤，记录失败原因到 findings.md，不要跳过继续
同一问题修复失败 3 次	停止，写入 findings.md，向用户汇报。可能是架构问题，考虑升级为流程C
测试套件无法通过	不发布。修复测试或修复代码，二选一，不允许跳过测试
发现计划有遗漏	回到规划阶段补充，不要边写边改计划
上下文即将耗尽	立即更新 progress.md → 开启新会话 → 从 progress.md 恢复
流程执行中途发现走错流程	停止当前流程，记录已完成的步骤，切换到正确流程重新开始