/forge-eng：工程文档管理与代码实现 v2

管理项目的 ENGINEERING.md（前后端合并），基于 PRD + DESIGN.md 产出工程方案并实现。 集成 Worktree 隔离、分级 TDD、Verification Gate。

流程总览

完整模式：
  第0步 定位文档 → 第0.5步 模式选择 → 第1步 范围挑战 → 第2步 理解现状
  → 第3步 四章审查 → 第4步 方案设计 → 第5步 更新文档
  → 第5.5步 创建Worktree → 第5.6步 Dev Server 端口契约 → 第5.7步 测试框架检测
  → 第6步 任务拆分(含TDD级别) → 第7步 Wave执行(TDD+Verification)
  → 第8步 必需产出 → 第9步 确认总结 → 第10步 分支收尾

轻量模式：
  第0步 定位文档 → 第0.5步 模式选择
  → 第5.5步 创建Worktree → 第5.6步 Dev Server 端口契约 → 第5.7步 测试框架检测
  → 第6步 任务拆分(含TDD级别) → 第7步 Wave执行(TDD+Verification)
  → 第9步 确认总结 → 第10步 分支收尾

全程中文。关键技术决策需用户确认后再实现。

---

AskUserQuestion 格式规范

每次提问必须遵循以下结构：

1. 重新聚焦：说明当前项目、分支和正在设计/实现的内容。（1-2句）
2. 通俗解释：用高中生能听懂的语言解释问题。说清楚"做什么"，不是"叫什么"。
3. 给出建议：推荐：选择[X]，因为[一句话原因]。标注每个选项的完整度：X/10。
4. 列出选项：A) ... B) ... C) ...——涉及工作量时同时注明：（人工：~X / AI协助：~Y）

---

完整性原则——把湖烧干

有 AI 辅助时，"做完整"的边际成本接近于零：

任务类型	人工团队	AI辅助	压缩比
样板/脚手架	2天	15分钟	~100x
写测试	1天	15分钟	~50x
功能实现	1周	30分钟	~30x
Bug修复+回归测试	4小时	15分钟	~20x
架构/设计	2天	4小时	~5x
调研/探索	1天	3小时	~3x

当完整方案只比捷径多几分钟时，永远推荐完整方案。

---

工程思维框架

1. 爆炸半径直觉 — 每个决定都评估："最坏情况是什么？影响多少系统和人？"
2. 无聊优先 — "每个公司大约只有三个创新机会。"其他一切用成熟技术。
3. 增量而非革命 — 绞杀者模式而非大爆炸。灰度发布而非全量切换。
4. 系统而非英雄 — 为凌晨3点疲惫的工程师设计。
5. 可逆性偏好 — 功能开关、A/B测试、灰度发布。让犯错的代价变低。
6. DX就是产品质量 — 慢 CI、糟糕的本地开发环境 → 更差的软件。
7. 先让修改变简单，再做简单的修改 — 先重构，再实现。永远不要同时改结构和行为。

---

三条铁律（来自 Superpowers，不可违反）

1. 不先验证就不准声称完成 — 必须运行验证命令、读取完整输出、确认 exit code 后才能 commit 或声称成功。禁用"should work"、"probably fixed"等措辞。详见 references/verification-checklist.md。
2. 不先写失败测试就不准写实现（严格 TDD 级别适用）— 写了实现再补测试？删掉实现，从测试重新开始。详见 references/tdd-guide.md。
3. 3 次修复失败就质疑架构 — 不要尝试第 4 次修复，停下来和用户讨论设计方案是否有根本问题。

---

第0步：定位项目文档

1. 定位 PRD：搜索 {项目目录}/docs/PRD.md
2. 定位 DESIGN.md：搜索 {项目目录}/docs/DESIGN.md
3. 定位 RESEARCH.md：搜索 {项目目录}/docs/*RESEARCH*（如果 forge-dev 产出了调研报告）
4. 定位视觉决策索引（如有）：搜索 .do-dev/visual-decision.md、.deliver/visual-decision.md、docs/讨论/*/assets/*.meta.json
5. 定位 ENGINEERING.md：

   搜索模式：
   - {项目目录}/docs/ENGINEERING.md
   - {项目目录}/docs/*engineering*（不区分大小写）
   - {项目目录}/docs/*工程*
   - {项目目录}/**/ENGINEERING*.md
   

6. 定位 ENGINEERING CHANGELOG：模式匹配 *engineering*changelog*
7. 分支判断：有 → 迭代模式；无 → 创建模式

---

第0.5步：模式选择

根据项目状态自动判断，或通过 AskUserQuestion 确认：

检查是否有 PRD + ENGINEERING.md
  ├── 有 → 默认完整模式
  └── 无 → 提议选择：
        A) 完整模式 — 创建工程文档，走完整流程（适合正式项目）
        B) 轻量模式 — 跳过文档管理，只做：
           Worktree 隔离 → 任务拆分 → TDD/验证驱动 → 原子提交 → 收尾
           （适合小 demo、POC、快速实验）

轻量模式保留的能力：Worktree 隔离、任务拆分、TDD/验证驱动、原子 commit、分支收尾。 轻量模式跳过的内容：ENGINEERING.md 管理、四章审查、CHANGELOG、.features/ 状态管理。

如果选择轻量模式：跳转到第 5.5 步（创建 Worktree）。

---

第1步：范围挑战

在设计任何方案之前，先回答这些问题：

1. 哪些现有代码已经部分或完全解决了每个子问题？ 能复用还是在重建？
2. 实现目标所需的最小变更集是什么？ 哪些工作可以推迟而不阻碍核心目标？
3. 复杂度检查：如果方案涉及超过 8 个文件或引入超过 2 个新类/服务，视为警告信号——同样的目标能用更少的活动部件实现吗？
4. TODOS 交叉检查：读取 TODOS.md（如果存在）。有没有推迟项在阻塞此方案？有没有推迟项可以顺带做了？

完整度检查：方案是在做完整版还是捷径版？用 AI 辅助，"完整"比人工便宜 100 倍。如果方案选择了捷径而只省了几分钟，推荐做完整版。

如果复杂度检查触发（8+ 文件或 2+ 新类/服务）：通过 AskUserQuestion 主动建议缩减范围。

---

第2步：理解现状（迭代模式）

1. 读取 PRD 最新迭代摘要，提取工程相关变更
2. 读取 DESIGN.md（如有），提取设计约束
3. 读取 RESEARCH.md（如有），提取技术调研结论
4. 读取视觉决策索引（如有），明确哪些 Image 2 / Figma 图只是观感参考，哪些真实截图是验收证据
5. 读取完整 ENGINEERING.md
6. 读取 ENGINEERING CHANGELOG（如有），做热点分析
7. 用 Agent(Explore) 扫描项目源码，理解当前架构
8. 向用户总结当前工程状态，确认理解是否正确

---

第2步（替代）：从零创建 ENGINEERING.md

1. 深度阅读项目代码：

   • Agent(Explore) 扫描项目结构
   • 读取核心源码、配置文件、数据库 schema
   • 分析前后端代码组织方式
   • 查看 git log 了解架构演进

2. 与用户多轮确认：

   • 第1轮：架构概览 — 展示 ASCII 架构图，确认是否准确
   • 第2轮：技术栈确认 — 列出检测到的框架/库/工具
   • 第3轮：模块划分 — 前端模块 + 后端模块的边界确认
   • 第4轮：数据流 — 关键数据流的流转路径
   • 第5轮：已知技术债 — 当前代码中的问题

3. 产出 ENGINEERING.md 初稿（参考 references/engineering-template.md）

4. 新建 ENGINEERING CHANGELOG

5. 逐节确认后写入文件

---

第3步：四章工程审查

章节顺序：架构 → 代码质量 → 测试 → 性能。 每个章节发现问题后，逐一通过 AskUserQuestion 确认后再进入下一章节。

第1章：架构审查

评估：

• 整体系统设计和组件边界
• 依赖关系图和耦合问题
• 数据流模式和潜在瓶颈
• 扩展性和单点故障
• 安全架构（认证、数据访问、API 边界）
• 关键流程是否值得用 ASCII 图说明
• 对每个新代码路径，描述一个真实的生产故障场景

停止。每发现一个问题，单独调用 AskUserQuestion。每次一个问题。

第2章：代码质量审查

评估：

• 代码组织和模块结构
• DRY 违反——要有侵略性
• 错误处理模式和缺失的边界情况
• 技术债热点
• 被修改文件中已有的 ASCII 图——改动后还准确吗？

停止。每个问题单独 AskUserQuestion。

第3章：测试审查

画出所有新 UX、新数据流、新代码路径、新的分支逻辑的图。对每一项，确认是否有对应测试。

测试矩阵产出：审查完成后，把测试矩阵写入工程文档，供 /forge-qa 使用。

停止。每个问题单独 AskUserQuestion。

第4章：性能审查

评估：

• N+1 查询和数据库访问模式
• 内存使用问题
• 缓存机会
• 高时间复杂度代码路径

停止。每个问题单独 AskUserQuestion。

---

第4步：工程方案设计

需要用户确认的关键技术决策

对每个变更点，通过 AskUserQuestion 确认：

1. 架构设计：用 ASCII 图展示模块关系和数据流
2. 技术选型：涉及新依赖或新模式时，说明选型理由
3. 实现清单：按依赖顺序列出需要创建/修改的文件及其职责
4. API 设计：新增/修改的 API 端点定义
5. 测试矩阵：需要覆盖的测试场景

不需要用户确认的内容

• 具体代码实现细节
• 变量命名、函数签名
• 错误处理的具体策略（遵循项目已有模式）

---

第5步：更新工程文档

A. 更新 ENGINEERING CHANGELOG

追加本次变更记录：时间、背景、技术方案、关键决策。

B. 更新 ENGINEERING.md

1. 更新版本号、日期
2. 更新迭代摘要区（保留所有版本）
3. 前端章节：更新组件/页面/交互实现说明
4. 后端章节：更新 API/数据模型/业务逻辑说明
5. 更新架构图（如有变更）
6. 更新实现清单和测试矩阵
7. 自洽性检查

---

第5.5步：创建 Worktree（会话级隔离）

核心原则：不在主工作目录写代码，创建隔离副本。每个 forge-eng 会话一个 worktree，多会话互不冲突。

详细命令参考见 references/worktree-guide.md。

流程

# 1. 检查/创建 worktree 目录
ls -d .worktrees 2>/dev/null || mkdir -p .worktrees

# 2. 安全检查：确认 .gitignore
git check-ignore -q .worktrees 2>/dev/null || {
  echo ".worktrees/" >> .gitignore
  git add .gitignore
  git commit -m "chore: add .worktrees to gitignore"
}

# 3. 创建 worktree + 分支
BRANCH="eng/{feature-slug}-$(date +%Y-%m-%d)"
WORKTREE=".worktrees/{feature-slug}"
git worktree add "$WORKTREE" -b "$BRANCH"
cd "$WORKTREE"

# 4. 安装依赖（自动检测项目类型）
[ -f package.json ] && npm install
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f go.mod ] && go mod download

# 5. 基线测试
npm test 2>/dev/null || python -m pytest 2>/dev/null || echo "无测试框架"

基线测试结果处理

结果	操作
测试通过	报告就绪，继续
测试失败	报告失败数量，询问是否继续
无测试框架	跳过，进入第 5.7 步

报告格式

Worktree 就绪：
  路径：{full-path}
  分支：{branch-name}
  基线测试：{通过 N 个 / 无测试框架}
  Backend URL：{如已启动则填写；未启动则写 未启动}
  Frontend URL：{如已启动则填写；未启动则写 未启动}
  APP_URL：{供浏览器/QA 使用的 URL；来自 dev:status，不得猜}
  准备开始实现 {feature-name}

后续所有 Wave 执行都在 worktree 目录中进行。

---

第5.6步：Dev Server 端口契约（如项目需要运行应用）

核心原则：worktree 可以并行，但 dev server 必须由项目统一入口分配和复用端口。不要在 worktree 里裸跑 uvicorn、vite、next dev 或临时 npm run dev -- --port ...，除非项目没有统一入口。

统一入口优先级

# 必须在 worktree 根目录执行
cd "$WORKTREE"

if npm run 2>/dev/null | grep -q "dev:status"; then
  npm run dev:status
  npm run dev
  npm run dev:status | tee /tmp/forge-dev-status.txt
elif [ -x scripts/dev-stack.sh ]; then
  bash scripts/dev-stack.sh status
  bash scripts/dev-stack.sh start
  bash scripts/dev-stack.sh status | tee /tmp/forge-dev-status.txt
else
  echo "未发现统一 dev server 入口；如必须启动应用，使用显式非默认端口并记录 PID/cwd/URL"
fi

硬性要求

1. 有统一入口就必须用统一入口：npm run dev:status / npm run dev / scripts/dev-stack.sh 优先于任何手写启动命令。
2. APP_URL 必须来自状态输出：浏览器测试、curl、forge-qa 的 app_url 都从 dev:status / dev-stack status 输出读取，不得凭常见端口猜测。
3. 启动前先看状态：如果当前 worktree 已有对应服务，复用；不要重复启动同一套前后端。
4. 进程身份必须核对：状态输出或 lsof -p $PID | grep cwd 必须证明监听进程 cwd 属于当前 worktree。
5. 主分支端口固定，worktree 端口自动隔离：如果项目 dev-stack 已规定 main 使用固定端口，worktree 不得抢这些端口。
6. 收尾前停本 worktree 服务：删除或合并 worktree 前运行 npm run dev:stop 或 bash scripts/dev-stack.sh stop；没有统一入口时，按记录的 PID 精确停止当前 worktree 的进程。

---

第5.7步：测试框架检测与引导

首次检测到项目无测试框架时触发。

# 检测已有测试框架
ls jest.config.* vitest.config.* .rspec pytest.ini 2>/dev/null
ls -d test/ tests/ spec/ __tests__/ e2e/ 2>/dev/null

如果无测试框架，通过 AskUserQuestion 提议安装：

检测到项目无测试框架。推荐安装以启用 TDD：

A) 安装 vitest + @testing-library（推荐，Node.js/Next.js 项目）
   npm i -D vitest @testing-library/react @testing-library/jest-dom
B) 安装 pytest + pytest-cov（Python 项目）
   pip install pytest pytest-cov
C) 跳过 — 使用验证驱动模式（每个任务定义可执行验证命令）
D) 跳过 — 不做任何验证（不推荐）

如果用户选择安装：

1. 安装依赖包
2. 创建配置文件（vitest.config.ts / pytest.ini）
3. 写一个示例测试，验证框架正常工作
4. 运行测试 → 确认通过
5. 提交：chore: add test framework (vitest/pytest)

如果已有测试框架：读取 2-3 个已有测试文件，学习命名惯例、导入风格、断言模式，供后续 TDD 使用。

详细框架安装指引见 references/tdd-guide.md。

---

第6步：任务拆分与 Wave 规划

任务拆分原则

1. 垂直切片优先 — 每个任务端到端完成一个功能
2. 每个任务足够小 — 通常 1-3 个文件，最多 5 个
3. 每个任务可独立验证 — 有明确的验证方式
4. 每个任务有 TDD 级别标注 — 根据文件类型自动判断

TDD 级别自动判断

项目有测试框架？
├── 否（且用户拒绝安装）→ 全部任务使用"验证驱动"
└── 是 → 按任务文件类型判断：
      ├── *.py / *.go / *.rs / *api* / *service* / *model*  → 严格 TDD
      ├── *.tsx / *.vue / *.jsx（前端组件）                   → 轻量 TDD
      ├── *.css / *.scss / *.config.* / *.md / *.json        → 跳过
      └── Bug 修复（任何类型）                                → 严格 TDD

任务定义格式

### Task-{N}: {任务名}

**TDD 级别**: 严格 / 轻量 / 验证驱动 / 跳过
**类型**: auto | manual
**依赖**: [Task-X, Task-Y]
**文件**:
- {file_path_1} — {做什么改动}
- {file_path_2} — {做什么改动}

**实现要求**:
{具体实现指令}

**验证命令**:
{可执行的验证命令：测试命令 / curl / 浏览器截图 / 脚本}

**完成标准**:
{什么状态算"做完了"——必须可验证}

Wave 分组

┌─────────────────────────────────────────────────────────┐
│  WAVE 1 (并行)              WAVE 2 (并行)      WAVE 3    │
│  ┌─────────┐ ┌─────────┐   ┌─────────┐        ┌──────┐ │
│  │ Task-01 │ │ Task-02 │ → │ Task-03 │      → │T-05  │ │
│  │ 严格TDD │ │ 跳过TDD │   │ 轻量TDD │        │验证  │ │
│  └─────────┘ └─────────┘   └─────────┘        │驱动  │ │
│                                                 └──────┘ │
└─────────────────────────────────────────────────────────┘

分组规则：

• 无依赖或依赖已在前序 wave 完成 → 归入当前 wave
• 同一 wave 内任务互相不依赖 → 可并行
• 修改同一文件 → 不同 wave 顺序执行，或合并为一个任务

用户确认

通过 AskUserQuestion 展示任务拆分和 wave 规划，包括每个任务的 TDD 级别。

---

第7步：Wave 并行执行（TDD + Verification Gate）

执行方式

同一 wave 内的任务使用 Agent 工具并行执行，每个任务在独立上下文中完成。所有 Agent 的工作目录为 worktree 路径。

任务执行模板（Agent Prompt）

每个 Agent 收到的完整指令：

你需要在项目 {worktree_path} 中完成以下任务：

任务：{task.name}
TDD 级别：{task.tdd_level}
文件：{task.files}
实现要求：{task.instructions}
验证命令：{task.verify_command}
完成标准：{task.done_criteria}

工程上下文：
- ENGINEERING.md: {eng_doc_path}（如有）
- DESIGN.md: {design_doc_path}（如有）
- 视觉决策索引: {visual_decision_path or "无"}（Image 2 只作观感参考，最终以 DESIGN.md、Feature Spec、真实截图和测试为准）

=== 实现流程（根据 TDD 级别） ===

[严格 TDD]
1. 读取涉及的文件，理解上下文
2. 写失败测试（测试文件路径随代码文件就近放置）
3. 运行测试 → 必须看到测试失败（失败原因是功能缺失，不是语法错误）
4. 写最小实现让测试通过
5. 运行测试 → 确认通过
6. 重构（保持测试绿色）
7. Verification Gate → commit

[轻量 TDD]
1. 读取涉及的文件
2. 实现功能
3. 写关键交互/边界测试（点击、提交、状态切换、空值、超长）
4. 运行测试 → 确认通过
5. Verification Gate → commit

[验证驱动]
1. 读取涉及的文件
2. 实现功能
3. 执行验证命令：{task.verify_command}
4. 读取完整输出，确认结果正确
5. Verification Gate → commit

[跳过 TDD]
1. 读取涉及的文件
2. 实现
3. Verification Gate → commit

=== Verification Gate（所有级别通用） ===

commit 前必须执行：
1. 运行验证命令（不截断输出）
2. 读取完整输出
3. 检查 exit code
   - = 0 且输出正确 → 允许 commit
   - ≠ 0 → 诊断修复 → 重新验证（最多 3 次）
   - 3 次失败 → 停止，报告失败原因

禁止使用："should work" / "probably fixed" / "seems to pass"
必须使用："验证通过：{命令} 输出 {结果}，exit code 0"

=== commit 规则 ===
只修改任务列出的文件（+ 测试文件）
遵循项目已有的代码风格

原子 Git 提交

每个任务完成验证后立刻创建独立的 git commit。 不可跳过。

提交格式

git add {task_files}
git commit -m "$(cat <<'EOF'
{type}({scope}): {task_name}

{一句话描述做了什么}

Task-{N} of Wave-{M}
验证：{验证命令} → {结果摘要}
EOF
)"

type 规范：feat / fix / refactor / docs / test / chore scope：模块名或文件名简写

Wave 间验证

每个 wave 完成后，进入下一 wave 前：

1. 运行全量验证 — 执行项目测试套件（如果有），确认无回归
2. 检查冲突 — 确认并行任务没有产生代码冲突
3. 状态更新 — 更新 .features/{feature-id}/status.md（完整模式下）

如果验证失败：

• 定位失败的任务
• 启动新 Agent 诊断和修复
• 修复后创建新 commit：fix({scope}): resolve {issue} in Task-{N}
• 最多 3 次修复尝试。3 次失败 → 暂停，报告给用户，质疑设计方案
• 修复成功后继续下一 wave

---

第8步：必需产出

"未纳入范围"清单

每项审查中考虑但明确推迟的工作，附一句话原因。

"已存在的内容"清单

已有的代码/流程，以及方案是复用了它们还是重复建设。

故障模式清单

对每个新代码路径，列出一种现实中可能的失败方式，并说明：

1. 有没有测试覆盖这种失败
2. 有没有错误处理
3. 用户是否会看到清晰的错误，还是静默失败

无测试 + 无错误处理 + 静默失败 = 严重缺口，需要标红。

TODOS 更新

每个潜在 TODO 作为单独 AskUserQuestion 提问。绝不批量——每次一个。

---

第9步：确认与总结

+======================================================+
|                  工程交付完成                            |
+======================================================+
| 项目：[项目名]                                          |
| 版本：vX.Y                                             |
| 模式：完整 / 轻量                                       |
| Worktree：[路径] / 分支：[分支名]                        |
+------------------------------------------------------+
| 第0步 范围挑战：[接受/缩减]（完整模式）                    |
| 第1-4章 审查：___ 个问题（完整模式）                      |
| 测试框架：[已有/新安装/验证驱动]                          |
+------------------------------------------------------+
| 任务拆分：共 ___ 个任务，分 ___ 个 wave                  |
|   严格 TDD: ___ 个 | 轻量 TDD: ___ 个                  |
|   验证驱动: ___ 个 | 跳过: ___ 个                        |
| Wave 执行：                                             |
|   Wave 1: Task-01 ✅, Task-02 ✅                        |
|   Wave 2: Task-03 ✅, Task-04 ✅                        |
| Git 提交：___ 个原子提交                                 |
| Verification Gate：___ 次通过 / ___ 次重试               |
+------------------------------------------------------+
| 代码变更：X 个文件（新增 Y / 修改 Z）                      |
| 测试：[通过 X / 失败 Y / 新增 Z]                          |
| 文件：                                                    |
|   ENGINEERING.md          — [已更新/已创建/跳过]           |
|   ENGINEERING-CHANGELOG   — [已追加/已创建/跳过]           |
+======================================================+

未解决决策

如果用户未回答某个 AskUserQuestion，列出"未解决的决策——可能在后续咬你一口"。

---

第10步：分支收尾

所有任务完成且验证通过后，处理 worktree 和分支。

通过 AskUserQuestion 展示选项：

实现完成。如何处理分支？

1. 合并回主分支 — git merge 到 main，删除 worktree
2. 推送并创建 PR — git push + gh pr create，删除 worktree
3. 保留分支 — 不清理，稍后处理
4. 丢弃 — 删除分支和 worktree（需二次确认）

选项 1：合并回主分支

cd "$(git worktree list | head -1 | awk '{print $1}')"  # 回到主目录
git checkout main && git pull
git merge {branch-name}
# 运行测试验证合并结果
npm test 2>/dev/null || python -m pytest 2>/dev/null
# 通过后清理
git branch -d {branch-name}
git worktree remove {worktree-path}

选项 2：推送并创建 PR

git push -u origin {branch-name}
gh pr create --title "eng: {feature-name}" --body "$(cat <<'EOF'
## Summary
- {变更摘要}

## Test Plan
- [ ] {验证步骤}
EOF
)"
git worktree remove {worktree-path}

选项 3：保留

不做任何清理。报告路径和分支名。

选项 4：丢弃

必须二次确认，展示将删除的分支和提交列表，用户确认后：

cd "$(git worktree list | head -1 | awk '{print $1}')"
git worktree remove {worktree-path} --force
git branch -D {branch-name}

---

Feature 状态管理（.features/ 架构，仅完整模式）

核心原则

领域文档（ENGINEERING.md）只存内容，不存运行状态。 运行状态写入 .features/{feature-id}/status.md。

状态标记协议

标记	含义
[⏳ 待处理]	已规划，未开始
[🔄 进行中]	当前正在执行
[✅ 已完成]	执行完成
[❌ 失败]	执行失败，需干预
[⏸️ 暂停]	等待用户确认或外部依赖

操作规则

1. 启动时（第0步）：读取 status.md，确认前序依赖已完成，将 eng 行更新为 [🔄 进行中]
2. 第6步任务拆分完成后：在 status.md 中追加 Engineering Tasks 表
3. 每个任务开始/完成/失败时：更新任务行状态
4. Wave 间验证：当前 Wave 所有任务为 [✅ 已完成] 后才启动下一 Wave
5. 全部完成后：eng 行状态改为 [✅ 已完成]

跨 Agent 协作

• forge-dev 调度器通过 status.md 感知工程进度
• forge-qa 启动前确认 eng 行为 [✅ 已完成]
• 多个会话可以同时在不同 feature 上执行 forge-eng（各自有独立 worktree）

---

格式规则

• 问题编号（1, 2, 3...），选项字母（A, B, C...）
• 每个选项一句话，5 秒能做决定
• 每个章节结束后暂停，等用户反馈

---

资源

• 工程文档模板：references/engineering-template.md
• TDD 指南：references/tdd-guide.md — 红绿重构、分级 TDD、rationalization 对照表、测试框架安装
• Worktree 指南：references/worktree-guide.md — 创建/清理命令、安全检查、分支收尾
• Verification 检查清单：references/verification-checklist.md — 验证门控流程、禁用措辞、失败处理