dev-flow

工程原则

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

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

阶段自检

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

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

场景引导

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

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

边界判定:

一句话速判:

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

场景路由

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

流程定义

流程定义文件按需加载。根据场景引导选定流程后，读取对应文件执行：

加载方式: 用 Read 工具读取对应文件路径（如 flows/A.md），然后按其步骤执行。

可选工具套件

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

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

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

自动安装依赖套件: 当流程中反复命中"否则"路径时，按以下流程处理：

1. 检测: 用 Bash 检查技能是否存在
2. 询问: 向用户确认是否安装（仅首次询问）
3. 安装: 用户确认后执行对应命令
4. 验证: 再次检测确认安装成功

路径约定: 所有检测和安装统一使用 SKILLS_DIR 变量，优先 ~/.qoder/skills（如存在），否则 ~/.claude/skills。

安装命令:

gstack 自动安装:

SKILLS_DIR=$(test -d ~/.qoder/skills && echo ~/.qoder/skills || echo ~/.claude/skills) && if [ -d "$SKILLS_DIR/gstack" ]; then cd "$SKILLS_DIR/gstack" && git pull && bash ./setup; else git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git "$SKILLS_DIR/gstack" && cd "$SKILLS_DIR/gstack" && bash ./setup; fi

Superpowers 自动安装（从插件缓存链接到 skills 目录）:

SUPERPOWERS_SRC=$(find ~/.claude/plugins/cache -path "*/superpowers/*/skills" -type d 2>/dev/null | sort -V | tail -1) && if [ -z "$SUPERPOWERS_SRC" ]; then echo "ERROR: Superpowers plugin not found in cache. Install the plugin in Claude Code first."; exit 1; fi && SKILLS_DIR=$(test -d ~/.qoder/skills && echo ~/.qoder/skills || echo ~/.claude/skills) && for skill in "$SUPERPOWERS_SRC"/*/; do name=$(basename "$skill"); ln -sfn "$skill" "$SKILLS_DIR/$name"; done && echo "Superpowers installed: $(ls "$SKILLS_DIR" | grep -cE 'writing-plans|executing-plans|subagent-driven|requesting-code|test-driven') skills linked"

planning-with-files 自动安装（从插件缓存链接）:

PWF_SRC=$(find ~/.claude/plugins/cache -path "*planning-with-files*/planning-with-files-zh" -type d 2>/dev/null | sort -V | tail -1) && if [ -z "$PWF_SRC" ]; then echo "ERROR: planning-with-files plugin not found in cache. Install the plugin in Claude Code first."; exit 1; fi && SKILLS_DIR=$(test -d ~/.qoder/skills && echo ~/.qoder/skills || echo ~/.claude/skills) && ln -sfn "$PWF_SRC" "$SKILLS_DIR/planning-with-files-zh" && echo "planning-with-files-zh installed"

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

流程入口前置检查

启动任何流程前，先确认以下事项（所有流程通用）：

• [ ] 已在项目 Git 仓库根目录
• [ ] 依赖已安装（npm install / pip install / 等），无安装错误
• [ ] 测试套件基线已通过（记录当前测试状态，作为回归基准）
• [ ] 已读取项目 CLAUDE.md / CONTRIBUTING.md / README（如有）

如任一项不满足，先修复再进入流程。

子代理使用判断

走"否则"路径（无 Superpowers 的 subagent-driven-development / executing-plans）时，按以下标准决定是否用 Task 子代理：

并行条件：2+ 个子任务彼此无共享状态、无顺序依赖。否则串行。

测试隔离规则

技能测试或子代理实验禁止在主工作区执行，必须用 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:

# 任务计划：[任务标题]

- [ ] 步骤1：[描述]
- [ ] 步骤2：[描述]
- [x] 步骤3：[描述] ← 完成后打勾

progress.md:

# 进度记录

## [日期] 会话 N
- 完成了：[描述]
- 当前状态：[在步骤 X / 已完成]
- 下一步：[描述]
- 阻塞项：[无 / 描述]

findings.md:

# 发现记录

## [主题]
- **日期**：YYYY-MM-DD
- **发现**：[内容]
- **证据**：[文件路径 / 代码行 / 数据]
- **影响**：[描述]
- **建议**：[描述]

文件位置与 Git 策略:

文档更新规则

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

版本号

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

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

禁止事项

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

常见错误与 Red Flags

异常处理