Forge Eng

> 文档落地路径：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见 > ~/claudecode_workspace/工具/forge-cookbook/skills/forge-doc-policy/doc-paths.md。

/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](references/verification-checklist.md)。
2. 不先写失败测试就不准写实现（严格 TDD 级别适用）— 写了实现再补测试？删掉实现，从测试重新开始。详见 [references/tdd-guide.md](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

```

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

---

第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 了解架构演进

1. 与用户多轮确认：

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

1. 产出 ENGINEERING.md 初稿（参考 [references/engineering-template.md](references/engineering-template.md)）
2. 新建 ENGINEERING CHANGELOG
3. 逐节确认后写入文件

---

第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](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](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 /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](references/engineering-template.md)
• TDD 指南：[references/tdd-guide.md](references/tdd-guide.md) — 红绿重构、分级 TDD、rationalization 对照表、测试框架安装
• Worktree 指南：[references/worktree-guide.md](references/worktree-guide.md) — 创建/清理命令、安全检查、分支收尾
• Verification 检查清单：[references/verification-checklist.md](references/verification-checklist.md) — 验证门控流程、禁用措辞、失败处理

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yike-gunshi
• Source: yike-gunshi/forge-skills
• License: MIT

Install and usage instructions live in the source repository linked above.