aitable-workflow-cli 0.1.28 → 0.1.29-beta.1790736949347

package/templates/ai-native-sdlc/docs/plans/2026-09-29-borrow-from-joe-design.md

@@ -0,0 +1,943 @@
+# Joe 优秀设计借鉴方案
+
+> **日期**: 2026-09-29  
+> **状态**: 草案（待评审，暂不落地）  
+> **范围**: 从 Joe 项目中提炼可借鉴的设计模式，增强 AI Native SDLC 的 Prompt 质量与 Agent 行为可控性
+
+---
+
+## 一、背景
+
+### 1.1 两个项目的定位差异
+
+| 维度 | AI Native SDLC（双数字员工） | Joe |
+|------|---------------------------|-----|
+| 核心隐喻 | PM + Dev 双 Agent 协作 | 单 Agent + Skills 方法论切换 |
+| 覆盖范围 | 完整 SDLC：需求 → PRD → 技术方案 → 编码 → 评审 | 聚焦 bug-fix：理解 → 排查 → 修复 → 审查 → 部署 |
+| 工作流定义 | YAML 声明式步骤图 | JS 命令式动态脚本 |
+| 质量门禁 | 每阶段 CR merge 硬门禁 | 证据铁律 + 对抗性审查 |
+| 工程成熟度 | 框架支撑，测试覆盖待完善 | 95%+ 测试覆盖，Dashboard 可观测 |
+
+### 1.2 借鉴动机
+
+Joe 在以下方面有显著优势，值得引入 AI Native SDLC：
+
+1. **Prompt 工程**：对抗性 framing、证据铁律、结构化输出
+2. **Skills 系统**：可插拔的方法论模块（TDD、验证、审查、计划）
+3. **Agent 行为控制**：Gate 门禁、有界重试、管线感知
+4. **架构设计**：Resume Shim、Tool 能力注入、人工反馈文档化
+
+---
+
+## 二、Prompt 设计模式借鉴
+
+### 2.1 证据铁律（Iron Law）— 注入 Coding 阶段
+
+**来源**: Joe 的 `verification-before-completion` Skill
+
+**核心原则**: 没有当场跑过验证命令并看到输出 → 不能声称通过。
+
+**解决的问题**: LLM 幻觉测试结果——Agent 声称"测试通过"但实际从未运行测试命令。
+
+**Joe 的实现**:
+
+```markdown
+## ⚖️ 证据铁律
+**没有当场跑过验证命令并看到输出 → 不能声称通过。**
+
+### 操作规程
+1. 识别验证命令（测试/类型检查/构建）
+2. 运行完整命令（不是部分）
+3. 阅读完整输出（不是尾部）
+4. 确认输出支持你的声明
+5. 只有此时才能声称"通过"
+
+### 🚩 红旗信号
+- 使用"应该"、"大概"、"可能" → 你还没有验证
+- 在验证前说"太好了"、"搞定了" → 停下来，先跑验证
+- 准备提交但没跑测试 → 不允许
+- 信任另一个 Agent 的成功报告 → 自己验证
+
+### 回归验证（关键 Bug 修复必须）
+编写修复 → 跑测试（通过）→ 回退修复 → 跑测试（必须失败）→ 恢复修复 → 跑测试（通过）
+```
+
+**AI Native SDLC 的当前差距**:
+
+当前 `coding.recipe.ts` 只有一句"失败不能伪造通过"，缺乏具体操作规程和红旗信号。
+
+**建议注入位置**: `coding.recipe.ts` 的 prompt 模板中新增 `## ⚖️ 证据铁律` 段落。
+
+**预期工件增强**: `03-coding.md` 必须包含以下证据段落：
+
+```markdown
+## 测试证据
+- ✅ 测试命令: `pnpm test`
+- ✅ 实际输出: （粘贴完整输出，不是"应该通过"）
+
+## 类型检查证据
+- ✅ 命令: `pnpm typecheck`
+- ✅ 实际输出: （粘贴完整输出）
+
+## Git Diff 证据
+- ✅ `git diff HEAD~1` 输出: （粘贴实际 diff）
+```
+
+---
+
+### 2.2 对抗性 Framing — 注入 Review 阶段
+
+**来源**: Joe 的 `requesting-code-review` Skill + 动态工作流 Review prompt
+
+**核心原则**: 翻转 Agent 的默认倾向——从"确认正确"变为"尽力找问题"。
+
+**Joe 的实现**:
+
+```markdown
+## 审查者角色设定
+你现在是一个**独立的代码审查者**。
+- 你没有参与前面的设计和编码过程
+- 你只看到 diff 和原始需求
+- 你的职责是**尽力找出问题**，而不是确认修复正确
+- 假设代码有 Bug，你的任务是找到它
+
+### 问题分级
+- 🔴 Critical：必须立即修复（逻辑错误、数据丢失风险）
+- 🟡 Important：必须修复后才能合并（性能问题、缺少错误处理）
+- 🔵 Minor：可以后续处理（代码风格、命名优化）
+```
+
+**AI Native SDLC 的当前差距**:
+
+当前 review recipe 是同一个 Agent session 继续处理 CR 评论，存在"自我确认偏误"。Review 阶段的 prompt 只是说"逐项修复评论"，缺乏对抗性思维。
+
+**建议注入位置**: 各 review recipe（`prd-review.recipe.ts`、`spec-review.recipe.ts`、`review.recipe.ts`）的 prompt 中增加对抗性角色设定。
+
+**各阶段的对抗性 prompt 变体**:
+
+| 阶段 | 对抗性 Framing |
+|------|---------------|
+| PRD Review | "你的职责是找出 PRD 中的遗漏和矛盾，而不是确认 PRD 写得好" |
+| Spec Review | "假设技术方案有致命缺陷，你的任务是找到它" |
+| Code Review | "假设代码有 Bug，你的任务是找到它" |
+| 需求澄清 | "如果你没有提出问题，说明你理解得不够深——至少找出 3 个不确定点" |
+
+---
+
+### 2.3 反幻觉守卫 — 注入所有阶段
+
+**来源**: Joe 的 `WORKFLOW.skills.md` 中的反 hedging 语句
+
+**核心原则**: 直接针对 LLM 的模糊表达倾向，强制具体证据。
+
+**Joe 的实现**:
+
+```markdown
+如果你发现自己在用"可能"、"应该"、"大概"——你还没有找到根因，继续排查。
+```
+
+**建议注入位置**: 所有 recipe 的 `## 约束` 段落中增加：
+
+```markdown
+## 约束
+- 禁止使用"应该"、"大概"、"可能"、"或许"等模糊表述
+- 每个结论必须有代码级证据（文件路径 + 行号 + 实际输出）
+- 如果不确定，通过 SDLC_QUESTIONS 向人工确认，而不是猜测
+```
+
+---
+
+### 2.4 Gate 门禁模式 — 注入阶段转换
+
+**来源**: Joe 的 `WORKFLOW.skills.md` 中每个 Phase 后的 Gate checklist
+
+**核心原则**: 每个阶段结束时必须满足明确的 ✅ 条件才能进入下一阶段。
+
+**Joe 的实现**:
+
+```markdown
+### Gate
+- ✅ 根因已定位，有代码级证据（不是推测）
+- ✅ 失败测试已编写并看到失败输出
+- ✅ 修复代码已编写，测试通过（有实际运行输出）
+- ✅ 代码已提交
+```
+
+**建议**: 在 AI Native SDLC 的每个阶段末尾增加 Gate 检查，Agent 在声称完成前必须自检：
+
+| 阶段 | Gate 条件 |
+|------|----------|
+| PRD | ✅ 需求点全部覆盖 ✅ 验收标准可量化 ✅ 依赖项已列出 ✅ 无 TBD/待补充 |
+| PRD Review | ✅ 所有 CR 评论已处理 ✅ CR 已合并（isMerged=true） |
+| Spec | ✅ 选中仓库及理由 ✅ 实施步骤原子化 ✅ 每步有验证命令 ✅ 无 placeholder |
+| Spec Review | ✅ 所有 CR 评论已处理 ✅ CR 已合并 |
+| Coding | ✅ 代码已提交 ✅ 测试有实际运行输出 ✅ 类型检查有实际运行输出 |
+| Review | ✅ 所有 CR 已合并 ✅ CI 全绿 ✅ 无遗留 TODO/FIXME |
+
+---
+
+## 三、Skills 方法论借鉴
+
+### 3.1 Brainstorming — 注入 PRD / Spec 阶段
+
+**来源**: Joe 的 `brainstorming` Skill（vendor: obra/superpowers）
+
+**核心流程**: 探索上下文 → 逐一澄清 → 提出 2-3 方案 → 分节展示设计 → 确认后才进入下一步
+
+**AI Native SDLC 的当前差距**: PRD recipe 直接让 PM Agent "读需求、写 PRD"，缺少结构化的需求探索过程。Agent 容易直接跳到一个方案。
+
+**建议注入 PRD prompt**:
+
+```markdown
+## 工作方法：需求探索
+
+在撰写 PRD 之前，你必须按以下步骤思考：
+
+### 1. 上下文探索
+阅读业务仓库的以下内容，理解当前系统：
+- README.md
+- 目录结构（src/ 下的主要模块）
+- 最近 10 条 commit message
+
+### 2. 澄清问题
+列出需求中不明确的地方（最多 5 个），通过 SDLC_QUESTIONS 向人工确认。
+每个问题提供 2-3 个选项和推荐答案。
+
+### 3. 方案对比
+提出 2-3 个实现方案，每个方案写明：
+- 优势
+- 劣势
+- 风险
+- 预估工作量
+
+### 4. 推荐方案
+给出你的推荐及理由。
+
+### 5. 详细 PRD
+在人工确认方案方向后，撰写完整的 PRD 文档。
+
+⛔ 硬性门禁：未经人工确认方案方向，不得进入详细 PRD 撰写。
+```
+
+**建议注入 Spec prompt**:
+
+```markdown
+## 工作方法：技术方案探索
+
+### 1. 阅读 PRD
+先阅读 PRD 工件（路径见下方），理解需求全貌。
+
+### 2. 仓库评估
+对每个候选仓库，评估：
+- 与本次需求的关联度（高/中/低）
+- 修改范围预估（文件数、行数）
+- 风险等级
+
+### 3. 方案对比
+提出 2-3 个技术方案，对比维度：
+- 实现复杂度
+- 对现有代码的侵入性
+- 可测试性
+- 回滚难度
+
+### 4. 推荐方案
+给出推荐及理由，明确列出选中/未选中仓库及原因。
+```
+
+---
+
+### 3.2 Writing-Plans — 注入 Spec 阶段
+
+**来源**: Joe 的 `writing-plans` Skill（vendor: obra/superpowers）
+
+**核心原则**: 实施计划必须假设执行者"零上下文"——每个步骤是 2-5 分钟的原子操作。
+
+**Joe 的关键约束**:
+
+- **原子步骤**: 每个步骤是一个 2-5 分钟的原子操作
+- **零 Placeholder**: 禁止 "TBD"、"后续补充"、"适当处理"
+- **精确路径**: 每个步骤指明要修改的文件路径（精确到行号范围）
+- **完整代码**: 关键函数给出完整代码，不是伪代码
+- **验证命令**: 每个步骤附带验证命令和预期输出
+- **自检清单**: Spec 覆盖度 + placeholder 扫描 + 类型一致性
+
+**建议注入 Spec prompt**:
+
+```markdown
+## 工作方法：技术方案编写
+
+你的 Spec（02-spec.md）必须满足以下标准：
+
+### 原子步骤
+每个实施步骤是一个 2-5 分钟的原子操作，格式如下：
+
+#### 步骤 N: <标题>
+- **文件**: `src/path/to/file.ts` (行 42-58)
+- **操作**: <具体描述>
+- **代码**: （关键函数给出完整代码）
+- **验证**: `<命令>` → 预期输出: `<预期>`
+
+### 禁止项
+- ❌ "TBD"、"后续补充"、"适当处理"
+- ❌ 伪代码（必须给出可运行的代码）
+- ❌ "添加适当的错误处理"（必须指明具体错误类型和处理方式）
+
+### 自检清单（写入 Spec 末尾）
+- ✅ 每个需求点都有对应步骤
+- ✅ 无 placeholder 扫描通过
+- ✅ 类型一致性检查通过
+- ✅ 每个步骤有验证命令和预期输出
+```
+
+---
+
+### 3.3 TDD（测试驱动开发）— 注入 Coding 阶段
+
+**来源**: Joe 的 `test-driven-development` Skill（vendor: obra/superpowers）
+
+**核心原则**: 没有失败的测试，就不写生产代码。
+
+**Joe 的实现**:
+
+```markdown
+## TDD 铁律
+**没有失败的测试 → 不写生产代码。**
+
+### Red-Green-Refactor 循环
+1. **RED**: 写一个最小的失败测试，验证它确实失败
+2. **GREEN**: 写最简单的代码让测试通过，验证所有测试仍然绿色
+3. **REFACTOR**: 只在绿色之后才重构，不添加新行为
+
+### 如果你先写了代码再写测试 → 删掉代码，从头来过
+没有例外。不要保留作为"参考"，不要"改编"。
+
+### 常见借口及反驳
+- "太简单不需要测试" → 简单的代码也可能有边界情况
+- "我先写代码后补测试" → 后补的测试无法证明代码正确
+- "TDD 会拖慢我" → 第一次就做对比返工快
+```
+
+**建议注入 Coding prompt**:
+
+```markdown
+## 工作方法：测试驱动开发
+
+在编写实现代码之前，你必须遵循 TDD 循环：
+
+### 1. RED — 编写失败测试
+- 针对需求中的每个行为点，编写一个测试
+- 运行测试，确认它**确实失败**（看到失败输出）
+- 将失败输出记录到 03-coding.md
+
+### 2. GREEN — 最小实现
+- 编写最简单的代码让测试通过
+- 运行测试，确认**所有测试通过**（看到通过输出）
+- 将通过输出记录到 03-coding.md
+
+### 3. REFACTOR — 重构（可选）
+- 只在测试全绿后才重构
+- 重构后再次运行测试，确认仍然通过
+
+### ⛔ 硬性约束
+- 如果你先写了实现代码再写测试 → 删掉实现代码，从 RED 开始
+- 每个新增函数必须有对应测试
+- 测试必须使用真实代码，避免不必要的 mock
+```
+
+---
+
+### 3.4 Finishing-a-Branch — 注入 Review 完成阶段
+
+**来源**: Joe 的 `finishing-a-development-branch` Skill
+
+**建议注入 Review 完成条件**:
+
+```markdown
+## 分支完成门禁
+
+在标记为 shipped 之前，必须确认：
+- ✅ 所有 CR 已合并（isMerged=true for all）
+- ✅ CI 全绿（有截图/链接证据）
+- ✅ 无遗留 TODO/FIXME/HACK 注释
+- ✅ commit message 符合 Conventional Commits
+- ✅ 工件文档（03-coding.md）与实际代码变更一致
+- ✅ 无未推送的本地 commit
+```
+
+---
+
+## 四、架构设计借鉴
+
+### 4.1 Persona 真正注入 Prompt
+
+**来源**: Joe 的 `AGENTS.md` + `execution-context.ts` 分层注入
+
+**AI Native SDLC 的当前差距**:
+
+`profile/profile.yml` 定义了 PM/Dev 的 persona 和 guardrails，但**从未注入到 prompt 中**。当前 recipe 只说"你是 Dev"甚至什么都不说。AGENTS.md 依赖 Agent 自己去读，不可靠。
+
+**建议**: 在 prompt builder 中显式注入 persona + guardrails：
+
+```typescript
+// lib/prompt-builder.ts（新增）
+function buildRoleSection(role: 'pm' | 'dev', profile: Profile): string {
+  const roleConfig = profile.roles[role];
+  return `
+## 角色
+${roleConfig.persona}
+
+## 行为约束（铁律）
+${roleConfig.guardrails}
+
+## 详细规程
+请阅读工作目录下的 AGENTS.md 获取完整操作规程。
+`.trim();
+}
+```
+
+**注入效果示例**:
+
+```markdown
+## 角色
+你是 PM（产品经理），负责需求分析、PRD 撰写和验收标准定义。
+
+## 行为约束（铁律）
+所有结论必须写入 Git 工件（changes/ 目录下的 Markdown 文件），不能只出现在对话中。
+
+## 详细规程
+请阅读工作目录下的 AGENTS.md 获取完整操作规程。
+```
+
+---
+
+### 4.2 管线位置感知（Pipeline Awareness）
+
+**来源**: Joe 的 `dynamic-workflow.ts` 中 phase 进度注入
+
+**AI Native SDLC 的当前差距**: Agent 不知道自己在 6 步流程中的哪一步，也不知道产出会被谁消费。
+
+**建议**: 在每个 recipe 的 prompt 中注入管线上下文：
+
+```typescript
+// lib/prompt-builder.ts（新增）
+function buildPipelineContextSection(
+  currentStep: string,
+  steps: string[],
+  stepLabels: Record<string, string>
+): string {
+  const currentIndex = steps.indexOf(currentStep);
+  const total = steps.length;
+  const progress = steps.map((s, i) => {
+    const icon = i < currentIndex ? '✅' : i === currentIndex ? '🔵' : '⬜';
+    return `${icon} ${stepLabels[s]}`;
+  }).join(' → ');
+
+  const downstream = steps.slice(currentIndex + 1).map(s => stepLabels[s]);
+  const downstreamConsumer = downstream[0] ?? '完成';
+
+  return `
+## 管线位置
+你正在 SDLC 流水线的 **第 ${currentIndex + 1} 步 / 共 ${total} 步**：
+${progress}
+
+### 你的产出将被谁消费？
+${downstreamConsumer === '完成' 
+  ? '你是最后一步，你的产出将直接交付。' 
+  : `你的工件将被 **${downstreamConsumer}** 阶段的 Agent 阅读和使用。`}
+`.trim();
+}
+```
+
+**各阶段的注入效果**:
+
+| 阶段 | 管线位置 | 下游消费者 |
+|------|---------|-----------|
+| PRD | 第 1 步 / 共 6 步 | PRD Review 阶段的 CR 审查者 |
+| PRD Review | 第 2 步 / 共 6 步 | Spec 阶段的 Dev Agent |
+| Spec | 第 3 步 / 共 6 步 | Spec Review 阶段的 CR 审查者 |
+| Spec Review | 第 4 步 / 共 6 步 | Coding 阶段的 Dev Agent |
+| Coding | 第 5 步 / 共 6 步 | Review 阶段的 CR 审查者 |
+| Review | 第 6 步 / 共 6 步 | 你是最后一步，你的产出将直接交付 |
+
+---
+
+### 4.3 Tool Capabilities 自动注入
+
+**来源**: Joe 的 `tool-capabilities.ts` — 启动时运行 `a1 --help` / `dws --help` 并缓存
+
+**AI Native SDLC 的当前差距**: Agent 不知道 `ctx.toolkit` 提供了什么能力，全靠 AGENTS.md 里手写（可能过时）。
+
+**建议**: 在 prompt 中动态注入 toolkit 能力清单：
+
+```markdown
+## 可用工具
+
+你可以通过以下方式与系统交互：
+
+### Git 操作
+- 确保 worktree 存在: 已在下方列出路径
+- 提交并推送: `git add -A && git commit && git push`
+- 创建 Code Review: 通过平台 API 或 CLI
+
+### AI Table 操作
+- 更新记录字段: 由工作流引擎自动处理
+- 读取记录: 由工作流引擎自动处理
+
+### 消息通知
+- 发送钉钉通知: 由工作流自动化规则处理
+
+### 约束
+- 你不能直接修改 AI Table 的"当前步骤"字段（由引擎管理）
+- 你不能执行 git merge（由人工在 CR 平台操作）
+- 你不能直接发送钉钉消息（通过自动化规则触发）
+```
+
+---
+
+### 4.4 有界重试循环（Bounded Retry）
+
+**来源**: Joe 的 `WORKFLOW.dynamic.js` 中 review 循环最多 2 轮
+
+**AI Native SDLC 的当前差距**: 当前 CR 评论修复没有轮次限制，理论上可以无限循环。
+
+**建议**: 在 review recipe 中加入轮次计数：
+
+```typescript
+// review.recipe.ts
+const MAX_REVIEW_ROUNDS = 3;
+
+async execute(ctx) {
+  const row = await ctx.toolkit.table.readRow(ctx.rowId);
+  const currentRound = Number(recordValue(row, '审查轮次') ?? 1);
+  
+  if (currentRound > MAX_REVIEW_ROUNDS) {
+    // 超过最大轮次，升级为人工处理
+    await ctx.toolkit.table.updateRow(ctx.rowId, {
+      '状态': 'blocked',
+      '阻塞原因': `审查已超过 ${MAX_REVIEW_ROUNDS} 轮，请人工介入`,
+    });
+    return blocked(`审查已超过 ${MAX_REVIEW_ROUNDS} 轮，请人工介入`);
+  }
+  
+  // ... 正常 review 逻辑
+  
+  // 每轮修复后递增轮次
+  await ctx.toolkit.table.updateRow(ctx.rowId, {
+    '审查轮次': currentRound + 1,
+  });
+}
+```
+
+**Tracker 字段新增**:
+
+```yaml
+field_definitions:
+  - name: 审查轮次
+    type: number
+    default: 1
+    description: 当前 CR 审查修复的轮次，超过上限则升级人工
+```
+
+---
+
+### 4.5 Resume Shim（断点恢复缓存）
+
+**来源**: Joe 的 `dynamic-script.ts` — 代码变换技巧
+
+**核心思想**: 不靠 session 持久化恢复上下文，而是缓存已完成阶段的结果，resume 时直接跳过。
+
+**Joe 的实现原理**:
+
+```javascript
+// 原始工作流脚本被包装：
+const __cached = args.__cachedResults || [];  // 上次已完成的结果
+let __idx = 0;
+
+async function __cachedAgent(prompt, opts) {
+  const i = __idx++;
+  if (i < __cached.length && __cached[i] != null) {
+    return __cached[i];  // ← 命中缓存，跳过执行（0 token）
+  }
+  // 首次调用（人工介入后）：注入人工反馈
+  if (__humanCtx && !__humanCtxUsed) {
+    prompt += '\n\n## 人工反馈\n\n' + __humanCtx;
+  }
+  return await __originalAgent(prompt, opts);
+}
+```
+
+**AI Native SDLC 的当前做法**: 靠 `sessionId` 恢复对话上下文。问题：
+- 每次 resume 都要重新加载完整历史（token 浪费）
+- session 可能过期或被清理
+- 无法跳过已完成的阶段
+
+**建议**: 在 recipe 层引入 stage-level 产出缓存：
+
+```typescript
+// lib/resume-cache.ts（新增）
+interface ResumeCache {
+  // key: stage name, value: artifact content + metadata
+  artifacts: Record<string, {
+    content: string;
+    timestamp: string;
+    agentSessionId: string;
+  }>;
+  // 人工答复历史
+  humanAnswers: Array<{
+    timestamp: string;
+    question: string;
+    answer: string;
+  }>;
+}
+
+// prd.recipe.ts
+async execute(ctx) {
+  const cache = ctx.resume.getCache();
+  
+  // 检查是否已有 PRD 产出缓存
+  const cachedPrd = cache.artifacts['prd'];
+  if (cachedPrd && !ctx.resume.hasNewHumanAnswers()) {
+    // 直接复用，不调 Agent（节省 token）
+    return success({ 
+      artifact: cachedPrd.content, 
+      cached: true,
+      message: '复用上次 PRD 产出（无人工新反馈）' 
+    });
+  }
+  
+  // 首次执行或有新的人工答复 → 调 Agent
+  const prompt = buildPrompt(ctx, { 
+    previousArtifact: cachedPrd?.content,  // 注入上次产出供参考
+    newHumanAnswers: ctx.resume.getNewAnswers(),  // 注入新的人工反馈
+  });
+  
+  const result = await ctx.toolkit.coding.run(prompt, { sessionId });
+  
+  // 缓存本次产出
+  ctx.resume.setArtifact('prd', result);
+  
+  return success({ artifact: result, cached: false });
+}
+```
+
+**收益**:
+- Resume 时跳过已完成阶段，节省 token
+- 人工反馈精准注入到断点处的 prompt
+- 不依赖外部 session 存储的可用性
+
+---
+
+### 4.6 渐进式上下文压缩（Progressive Context Accumulation）
+
+**来源**: Joe 的 `WORKFLOW.dynamic.js` — 后续阶段只收到前序阶段的 `summary`
+
+**AI Native SDLC 的当前差距**: Spec 阶段只拿到 PRD 的文件路径让 Agent 自己读，没有预提取关键信息。Review 阶段直接 dump JSON 评论，没有摘要。
+
+**建议**: 在 recipe 中增加上下文摘要 helper：
+
+```typescript
+// lib/context-compression.ts（新增）
+async function extractArtifactSummary(
+  artifactPath: string,
+  options: { sections: string[]; maxLength: number }
+): Promise<string> {
+  // 读取工件文件，提取指定章节，压缩到 maxLength
+  const content = await fs.readFile(artifactPath, 'utf-8');
+  const sections = extractSections(content, options.sections);
+  return truncate(sections.join('\n\n'), options.maxLength);
+}
+
+// spec.recipe.ts — 注入 PRD 摘要
+const prdSummary = await extractArtifactSummary(prdArtifactPath, {
+  sections: ['需求概述', '验收标准', '依赖项', '非功能需求'],
+  maxLength: 2000,
+});
+
+const prompt = `
+## 前序阶段产出：PRD 摘要
+${prdSummary}
+
+## PRD 完整文件
+路径：${prdArtifactPath}（需要细节时请阅读原文件）
+`;
+```
+
+**CR 评论摘要**（注入 review repair prompt）:
+
+```typescript
+// review.recipe.ts
+function summarizeComments(comments: CRComment[]): string {
+  const bySeverity = groupBy(comments, c => c.severity);
+  return `
+### 评论摘要
+- 🔴 Critical: ${bySeverity.critical?.length ?? 0} 条
+- 🟡 Important: ${bySeverity.important?.length ?? 0} 条
+- 🔵 Minor: ${bySeverity.minor?.length ?? 0} 条
+
+### Critical 评论（必须优先处理）
+${bySeverity.critical?.map(c => `- ${c.path}:${c.line} — ${c.body}`).join('\n') ?? '无'}
+
+### 全部评论
+${comments.map(c => `- [${c.severity}] ${c.path}:${c.line} — ${c.body}`).join('\n')}
+`;
+}
+```
+
+---
+
+### 4.7 结构化输出 Schema
+
+**来源**: Joe 的 `WORKFLOW.dynamic.js` — 每个 `agent()` 调用传 JSON Schema
+
+**AI Native SDLC 的当前差距**: Agent 产出是自由格式 Markdown，解析全靠正则（如 `SDLC_QUESTIONS`），脆弱。
+
+**建议**: 定义标准化的输出契约（YAML front matter）：
+
+```markdown
+## 输出契约
+
+你的回复必须包含以下结构化部分（用 YAML front matter 包裹）：
+
+\`\`\`yaml
+---
+status: success | blocked | failed
+confidence: high | medium | low
+questions:          # 仅 status=blocked 时填写
+  - id: q1
+    question: "..."
+    options: ["A", "B", "C"]
+    recommendation: "A"
+    reason: "..."
+artifacts:
+  - path: "changes/CHG-xxx/02-spec.md"
+    type: spec
+    sections: ["方案概述", "仓库选择", "实施步骤"]
+gate_checklist:     # 对应阶段的 Gate 条件
+  - condition: "需求点全部覆盖"
+    met: true
+  - condition: "无 placeholder"
+    met: true
+---
+\`\`\`
+
+然后是你的工件正文内容。
+```
+
+**解析增强**:
+
+```typescript
+// lib/output-parser.ts（新增）
+function parseStructuredOutput(response: string): {
+  frontMatter: OutputContract;
+  body: string;
+} {
+  const match = response.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    // fallback: 尝试从自由文本中提取 SDLC_QUESTIONS
+    return { frontMatter: inferFromFreeText(response), body: response };
+  }
+  return {
+    frontMatter: YAML.parse(match[1]) as OutputContract,
+    body: match[2],
+  };
+}
+```
+
+---
+
+### 4.8 分层 Prompt 组合（架构改造）
+
+**来源**: Joe 的 `src/agent/prompt/` 目录分层
+
+**AI Native SDLC 的当前差距**: 每个 recipe 都是一个大模板字符串，重复代码多，难以维护。
+
+**建议**: 引入分层 Prompt 组合器：
+
+```
+Prompt = System Layer + Role Layer + Skill Layer + Context Layer + Task Layer
+```
+
+| 层 | 内容 | 来源 | 复用范围 |
+|---|---|---|---|
+| System | 证据铁律、Git 规程、中文输出、反幻觉守卫 | `prompts/system.md` | 所有 recipe |
+| Role | PM/Dev 的 persona + guardrails | `profile/profile.yml` | 同角色 recipe |
+| Skill | 当前阶段的方法论（brainstorming/TDD/review） | `prompts/skills/<name>.md` | 同方法论 recipe |
+| Context | 管线位置 + 前序摘要 + worktree 路径 | recipe 动态注入 | 当前 recipe |
+| Task | 本轮具体任务 + 产出要求 + Gate 条件 | recipe 动态注入 | 当前 recipe |
+
+**代码结构**:
+
+```typescript
+// lib/prompt-builder.ts（新增）
+class PromptBuilder {
+  private layers: string[] = [];
+
+  system(): this {
+    this.layers.push(loadTemplate('prompts/system.md'));
+    return this;
+  }
+
+  role(role: 'pm' | 'dev', profile: Profile): this {
+    this.layers.push(buildRoleSection(role, profile));
+    return this;
+  }
+
+  skill(skillName: string): this {
+    this.layers.push(loadTemplate(`prompts/skills/${skillName}.md`));
+    return this;
+  }
+
+  pipelineContext(currentStep: string, steps: string[]): this {
+    this.layers.push(buildPipelineContextSection(currentStep, steps));
+    return this;
+  }
+
+  task(taskContent: string): this {
+    this.layers.push(taskContent);
+    return this;
+  }
+
+  build(): string {
+    return this.layers.join('\n\n---\n\n');
+  }
+}
+
+// prd.recipe.ts 使用示例
+const prompt = new PromptBuilder()
+  .system()                                    // 证据铁律 + 反幻觉
+  .role('pm', profile)                         // PM persona + guardrails
+  .skill('brainstorming')                      // 需求探索方法论
+  .pipelineContext('prd', executionSteps)       // 第 1 步 / 共 6 步
+  .task(buildPrdTaskSection(ctx))              // 本轮任务
+  .build();
+```
+
+---
+
+### 4.9 人工反馈文档化
+
+**来源**: Joe 的 `execution-context.ts` — `buildHumanLoopContext()`
+
+**AI Native SDLC 的当前做法**: 人工在 AI Table 的 `人工答复` 字段填写文本，recipe 直接读取字段值注入 prompt。
+
+**差距**: Table 字段空间有限，人工很难写清楚复杂反馈（截图、代码片段、多段分析）。
+
+**建议**: 支持"文档级"人工反馈：
+
+```typescript
+// lib/human-feedback.ts（新增）
+async function consumeHumanFeedback(ctx: RecipeContext, row: TableRow): Promise<string> {
+  const feedbackType = recordValue(row, '反馈类型'); // 'field' | 'doc'
+  
+  if (feedbackType === 'doc') {
+    const docUrl = recordValue(row, '反馈文档');
+    // 让 Agent 自己读文档，而不是把内容塞进 prompt
+    return `
+## 人工反馈（文档）
+
+请阅读以下文档获取详细反馈：
+${docUrl}
+
+阅读后，提取关键信息继续执行任务。
+如果文档中有多个问题点，请逐一处理。
+`.trim();
+  }
+  
+  // 兼容原有的字段模式
+  const answers = recordValue(row, '人工答复');
+  return `## 已消费的人工答复\n${answers}`;
+}
+```
+
+**Tracker 字段新增**:
+
+```yaml
+field_definitions:
+  - name: 反馈类型
+    type: single_select
+    options: ['field', 'doc']
+    default: 'field'
+  - name: 反馈文档
+    type: url
+    description: 当反馈类型=doc 时，填写钉钉文档链接
+```
+
+---
+
+## 五、实施路线图
+
+### 第一周：P0 — 纯 Prompt 改动（零架构风险）
+
+| 改动项 | 涉及文件 | 改动量 | 预期收益 |
+|--------|---------|--------|---------|
+| 证据铁律注入 Coding | `coding.recipe.ts` | ~30 行 prompt | 消除测试结果幻觉 |
+| 对抗性 Review prompt | `prd-review.recipe.ts`, `spec-review.recipe.ts`, `review.recipe.ts` | ~20 行/文件 | 提升 CR 修复质量 |
+| 有界重试循环 | `review.recipe.ts` + tracker schema | ~20 行代码 + 1 字段 | 防止无限修复循环 |
+| 反幻觉守卫 | 所有 recipe 的 `## 约束` | ~5 行/文件 | 减少模糊表述 |
+
+### 第二周：P1 — 小改动大收益
+
+| 改动项 | 涉及文件 | 改动量 | 预期收益 |
+|--------|---------|--------|---------|
+| Persona 注入 prompt | 新增 `lib/prompt-builder.ts`，改所有 recipe | ~80 行新代码 | 角色行为稳定 |
+| 管线位置感知 | 新增 helper，改所有 recipe | ~40 行新代码 | Agent 理解上下文 |
+| Gate 门禁模式 | 改所有 recipe 的完成条件 | ~10 行/文件 | 阶段转换可审计 |
+| Tool capabilities 注入 | 新增 helper | ~30 行新代码 | Agent 知道可用工具 |
+
+### 第三周：P2 — 方法论注入
+
+| 改动项 | 涉及文件 | 改动量 | 预期收益 |
+|--------|---------|--------|---------|
+| Brainstorming 注入 PRD | `prd.recipe.ts` + 新增 `prompts/skills/brainstorming.md` | ~50 行 | PRD 质量提升 |
+| Writing-plans 注入 Spec | `spec.recipe.ts` + 新增 `prompts/skills/writing-plans.md` | ~50 行 | Spec 可执行性 |
+| TDD 注入 Coding | `coding.recipe.ts` + 新增 `prompts/skills/tdd.md` | ~40 行 | 代码质量提升 |
+| 渐进式上下文压缩 | 新增 `lib/context-compression.ts`，改 spec/review recipe | ~60 行 | 减少 context 浪费 |
+
+### 后续迭代：P3 — 架构改造
+
+| 改动项 | 涉及文件 | 改动量 | 预期收益 |
+|--------|---------|--------|---------|
+| 分层 Prompt 组合 | 新增 `lib/prompt-builder.ts`，重构所有 recipe | ~200 行 | 可维护性 |
+| Resume Shim | 新增 `lib/resume-cache.ts`，改 engine | ~150 行 | Resume 省 token |
+| 结构化输出 Schema | 新增 `lib/output-parser.ts`，改所有 recipe | ~100 行 | 产出解析可靠 |
+| 人工反馈文档化 | 新增 `lib/human-feedback.ts`，改 tracker schema | ~50 行 | 复杂反馈支持 |
+
+---
+
+## 六、风险与注意事项
+
+### 6.1 Prompt 膨胀风险
+
+注入更多方法论和约束会增加 prompt 长度，可能挤压 Agent 的有效 context window。
+
+**缓解措施**:
+- 使用渐进式上下文压缩，控制总 prompt 在 8K token 以内
+- 方法论指令用精炼的语言，避免冗长
+- 优先注入 P0（证据铁律、对抗性审查），观察效果后再决定 P1/P2
+
+### 6.2 Agent 遵循度
+
+注入更多约束不等于 Agent 会遵循。LLM 的指令遵循能力有上限。
+
+**缓解措施**:
+- 关键约束（证据铁律、Gate 门禁）放在 prompt 开头和结尾（注意力最强位置）
+- 用 ⛔、🚩 等视觉标记强调关键约束
+- 通过 AGENTS.md 和 recipe prompt 双重强化
+
+### 6.3 向后兼容
+
+所有改动必须保持向后兼容——现有的 workflow.yml、profile.yml、tracker schema 不需要修改即可运行。
+
+**缓解措施**:
+- P0/P1 只改 prompt 文本，不改 schema
+- P2 新增的 tracker 字段设 default 值，旧记录不受影响
+- P3 架构改造通过 feature flag 控制
+
+---
+
+## 七、参考
+
+- Joe 项目: `/Users/s/Documents/code/workflow/other/Joe/`
+- Joe Skills (vendor: obra/superpowers): `skills/` 目录
+- AI Native SDLC: `packages/cli/templates/ai-native-sdlc/`
+- 前期对比分析: 2026-09-29 会话记录