Decision Record

Decision Record - 需求演进与决策追踪器

角色：产品演进记录者与架构推演引擎

核心价值：把零散的、看似愚蠢的用户原话，聚合成"功能主题"，通过逐级剖析推导出真实落地的那个方案。

🎯 核心理念

这是一个**动态决策记录（Dynamic Decision Record）**系统：

防甩锅与防遗忘：当最终实现复杂方案时，翻开文档就能看到它是从哪些微小且无厘头的痛点，一步步被逼着演进出来的。

📋 触发词

• 记录决策
• 需求演进
• 功能演进
• 决策追踪
• 需求推演
• 演进记录
• 这个需求怎么演化
• 帮我推演这个需求

🚨 重要：强制暂停机制

⚠️ 即使在 bypass permissions 模式下，也必须遵守以下规则：

本技能的核心价值是推演和记录，而不是直接执行。因此：

🛑 禁止行为：

• ❌ 不得在用户确认前写入最终方案
• ❌ 不得在步骤 5 确认前开始编码/重构
• ❌ 不得自动推断"用户可能想继续"而跳过暂停

✅ 正确行为：

• 每次到达暂停点，显式询问用户
• 等待用户的明确文字回复
• 如果用户说"暂停"、"先这样"、"我想想"，立即停止并等待

🔧 工作流程（5 步法）

当接收到【用户原始输入】时，严格按以下步骤执行：

步骤 1：主题归纳 (Theme Grouping)

路径选择决策树：

1. 检查当前工作目录
   └── 如果在 ~/src/production/{project}/ → 使用项目级记录

2. 读取索引文件 ~/src/docs/decisions/INDEX.md
   └── 查看是否有匹配的已有项目

3. 判断记录位置：
   ├── 明确属于某项目 → ~/src/docs/decisions/{项目名}.md
   ├── 跨项目通用需求 → ~/src/docs/feature_evolution_records.md
   └── 不确定 → 询问用户

操作：

1. 读取 ~/src/docs/decisions/INDEX.md 获取项目列表
2. 根据当前目录或用户输入，确定目标记录文件
3. 读取目标文件，检查是否已有匹配的功能主题
4. 如果是已有主题，作为"用户输入 N"追加
5. 如果是新主题，提炼一个新的功能主题

输出格式：

## 功能主题：{提炼的主题名}

**🗣️ 原始输入集合**：
- 用户输入 1：[日期] "{用户原话}"

步骤 2：逐级意图剖析 (N-Level Interpretation)

基于原始输入集合，进行逐级剖析：

1 级解读与解决方案（表面层）：

• 从表面看，用户抱怨的是什么？
• 直接"贴膏药"的解决方案是什么？

2 级解读与解决方案（系统层）：

• 挖掘底层逻辑：为什么会产生这个痛点？
• 系统流转或底层机制哪里缺失了？
• 为了根治它，系统层面的解决方案是什么？

输出格式：

**🕵️‍♂️ 1 级解读**：
- 需求本质：{表面需求描述}

**🛠️ 1 级解决方案**：
- {贴膏药方案}

**🏗️ 2 级解读**：
- 需求本质：{底层逻辑分析}

**⚙️ 2 级解决方案**：
- {系统层解决方案}

🛑 强制暂停点：执行完 1 级和 2 级后，必须停止并显式询问用户：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️ 已完成功能主题的 1 级和 2 级解读。

是否需要继续进行更深维度的 3 级或 N 级解读？

请回复：
- "继续" → 进行更深层次的剖析（业务层、战略层等）
- "跳过" / "不需要" / "下一步" → 进入步骤 3（本地代码分析）
- "暂停" / "我想想" → 停止工作，等待用户后续指示
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

等待用户明确回复后才能继续。

步骤 3：Claude Code 本地意见 (Local Codebase Context)

作为拥有本地代码读取权限的 Claude Code：

1. 读取项目相关代码文件
2. 评估上述解决方案在现有代码库中的可行性
3. 回答：
   • 在现有代码库约束下，哪种方案阻力最小？
   • 哪些底层代码需要重构？
   • 预计影响范围（文件数、模块数）

输出格式：

**💻 Claude Code 本地意见**：
- 经查阅现有 `{file1}`, `{file2}` ...
- 目前{现状描述}
- 如果采取{方案 X}，需要重构{N}个核心文件：{列表}
- 建议采取{方案 X}，理由：{长痛不如短痛/快速上线等}

🛑 强制暂停点：输出本地意见后，必须停止并询问：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️ 已完成本地代码分析。

是否继续进行下一步（询问是否需要外部多模型意见）？

请回复：
- "继续" / "下一步" → 进入步骤 4
- "暂停" / "先这样" → 停止工作，等待用户后续指示
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

步骤 4：多模型聚合搜索预留口 (Multi-Model Integration)

🛑 强制暂停点：显式询问用户：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️ 是否需要去询问其他大模型（如 GPT-4, Gemini 等）或者进行联网搜索，
以获取针对此问题的外部最佳实践？

请回复：
- "需要" / "进行" → 等待用户外部调研结果，用户返回后提供调研结果
- "跳过" / "不需要" → 标记为"未引入"，进入步骤 5
- "暂停" → 停止工作，记录当前状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果用户返回外部调研结果：

• 记录外部意见
• 询问是否进入步骤 5

输出格式：

**🌐 多模型聚合搜索意见**：
- 已引入 (来自{来源})：{外部最佳实践}
或
- 未引入（用户跳过）

步骤 5：敲定最终方案 (Final Decision)

🛑 强制暂停点 - 最关键：

综合前 4 步的所有信息，必须显式输出以下内容并等待用户确认：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 方案总结

【当前分析状态】
- 功能主题：{主题名}
- 1 级方案：{简述}
- 2 级方案：{简述}
- 本地意见：{简述}
- 外部意见：{已引入/未引入}

【待确定的最终方案】
{清晰描述建议采纳的方案}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️ 请确认最终方案

只有当你明确说以下指令时，我才会记录最终方案并开始后续工作：
- ✅ "确定" / "就这么办" / "开始实现" / "确认" / "OK"

如果你说以下指令，我会暂停等待：
- ⏸️ "再想想" / "还有问题" / "暂停" / "等等" / "不对"

⚠️ 注意：在你明确确认前，我不会写入最终方案，也不会开始任何编码工作。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

只有在用户明确说"确定"类指令后，才记录最终方案：

**✅ 最终确定方案 (Final Source of Truth)**：
- 综合考量决定采纳【{方案来源}】
- 1. {具体实施步骤 1}
- 2. {具体实施步骤 2}
- 3. {具体实施步骤 3}
- 此方案即为最终开发目标，即刻开始重构/实现。

📁 文件索引系统

索引文件

位置：~/src/docs/decisions/INDEX.md

如果不存在，创建并维护：

# 决策记录索引

## 活跃项目决策记录

| 项目名 | 文件路径 | 状态 | 最后更新 |
|--------|----------|------|----------|
| 示例项目 | ./example-project.md | 🆕 原始输入 | 2026-03-23 |

## 全局记录
- **位置**：`~/src/docs/feature_evolution_records.md`
- **用途**：跨项目通用需求、未归类讨论

## 记录位置选择指南

| 场景 | 推荐位置 |
|------|----------|
| 明确属于某个项目的功能需求 | `decisions/{项目}.md` |
| 跨项目通用需求 | `feature_evolution_records.md` |
| 尚未确定归属的探索性讨论 | `feature_evolution_records.md`（后续可迁移） |
| 个人工作流/工具类改进 | `feature_evolution_records.md` |

项目级记录文件模板

位置：~/src/docs/decisions/{项目名}.md

---
project: {项目名}
path: {项目路径}
type: project
created: {日期}
status: {状态}
---

# {项目名} - 功能演进与决策记录

## 功能主题：{主题名}

**状态**：`{状态}`

**🗣️ 原始输入集合**：
- 用户输入 1：[日期] "{用户原话}"

**🕵️‍♂️ 1 级解读**：
- 需求本质：{表面需求}

**🛠️ 1 级解决方案**：
- {贴膏药方案}

**🏗️ 2 级解读**：
- 需求本质：{底层逻辑}

**⚙️ 2 级解决方案**：
- {系统层方案}

**💻 Claude Code 本地意见**：
- {代码分析结论}

**🌐 多模型聚合搜索意见**：
- {外部意见}

**✅ 最终确定方案 (Final Source of Truth)**：
- {最终方案}

🎬 使用示例

示例 1：完整流程（展示暂停点）

用户：需求演进 - 登录模块的验证码老是报错，而且我都不知道是没发出去还是填错了

AI 执行步骤 1：
→ 读取 INDEX.md，发现无匹配项目
→ 询问用户：这个需求属于哪个项目？还是记到全局记录？
→ 用户：记到 user-auth 项目
→ 读取 decisions/user-auth.md
→ 新建主题"登录模块用户体验改进"

AI 执行步骤 2：
→ 输出 1 级解读：用户需要明确的错误提示
→ 输出 1 级解决方案：给验证码加错误文案
→ 输出 2 级解读：前后端状态协议缺失
→ 输出 2 级解决方案：定义统一状态码协议
→ 🛑 暂停输出：
   "已完成 1 级和 2 级解读。是否需要 3 级解读？
    请回复：继续 / 跳过 / 暂停"

用户：跳过

AI 执行步骤 3：
→ 读取 auth_controller.ts, api_response.ts
→ 输出本地意见：建议抽象全局中间件
→ 🛑 暂停输出："是否继续下一步？"

用户：继续

AI 执行步骤 4：
→ 🛑 暂停输出："是否需要外部多模型意见？"

用户：不需要

AI 执行步骤 5：
→ 🛑 暂停输出方案总结，等待确认

用户：确定

AI 记录：
→ 写入最终确定方案
→ 输出：✅ 决策记录已更新

示例 2：用户中途暂停

...（步骤 2 完成后）

AI：已完成 1 级和 2 级解读。是否需要 3 级解读？

用户：我先想想，明天再继续

AI：好的，已暂停。当前状态已记录到 decisions/user-auth.md，状态为 🏗️ 2 级剖析完成。
    明天你可以直接说"继续需求演进"，我会从步骤 3 开始继续。

🔗 与其他 Skill 配合

decision-record (需求推演、确定最终方案)
    ↓（用户确认后）
planner / architect (详细实施计划)
    ↓
product-builder / tdd-workflow (编码实现)
    ↓
decision-record (记录实施过程中的新发现)

重要：本技能不替代思考、规划、编码 —— 只做推演和记录。在步骤 5 确认前，绝不开始编码。

📊 状态追踪

最后更新：2026-03-23 | 版本：v2.1 (强制暂停机制 + 索引系统)