# Decision Record

> 需求演进与决策追踪器 - 当用户提出零散需求、抱怨某个功能、或讨论产品方向时，**必须**使用此技能。通过逐级剖析推导出落地方案，并在每个关键节点**强制暂停**等待用户确认。适用于：记录决策、需求演进、功能推演、架构选型、重构方案确定。触发词：记录决策、需求演进、功能演进、决策追踪、需求推演、演进记录、这个需求怎么演化、帮我推演这个需求。

- Skill: `throokie/decision-record` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add throokie/decision-record`
- Raw SKILL.md: https://api.skillmd.com/api/skills/throokie/decision-record/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Throokie (https://skillmd.com/u/throokie)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/throokie/decision-record

---


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

> **角色**：产品演进记录者与架构推演引擎
>
> **核心价值**：把零散的、看似愚蠢的用户原话，聚合成"功能主题"，通过逐级剖析推导出真实落地的那个方案。

---

## 🎯 核心理念

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

| 传统决策记录 | 需求演进与决策追踪器 |
|-------------|---------------------|
| 记录最终决定 | 记录从"碎片需求"到"落地代码"的全过程 |
| 静态、一次性 | 动态、逐级演进 |
| AI 被动记录 | AI 主动推演、剖析、质疑 |
| 无多模型整合 | 整合 Claude Code 本地视角 + 外部多模型意见 |
| 缺乏推导过程 | 保留完整的思想转变轨迹 |

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

---

## 📋 触发词

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

---

## 🚨 重要：强制暂停机制

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

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

| 步骤 | 暂停点 | 必须等待的用户指令 |
|------|--------|-------------------|
| 步骤 2 后 | 1-2 级解读完成 | "继续" / "跳过" / "不需要" |
| 步骤 3 后 | 本地意见输出 | "继续" / "下一步" |
| 步骤 4 后 | 外部意见询问 | "需要" / "跳过" / "不需要" |
| 步骤 5 后 | 最终方案确认 | **"确定" / "就这么办" / "开始实现"** |

**🛑 禁止行为**：
- ❌ 不得在用户确认前写入最终方案
- ❌ 不得在步骤 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. 如果是新主题，提炼一个新的功能主题

**输出格式**：
```markdown
## 功能主题：{提炼的主题名}

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

---

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

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

**1 级解读与解决方案**（表面层）：
- 从表面看，用户抱怨的是什么？
- 直接"贴膏药"的解决方案是什么？

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

**输出格式**：
```markdown
**🕵️‍♂️ 1 级解读**：
- 需求本质：{表面需求描述}

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

---

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

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

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

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

**如果用户返回外部调研结果**：
- 记录外部意见
- 询问是否进入步骤 5

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

---

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

**🛑 强制暂停点 - 最关键**：

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

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

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

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

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

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

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

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

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

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

---

## 📁 文件索引系统

### 索引文件

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

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

```markdown
# 决策记录索引

## 活跃项目决策记录

| 项目名 | 文件路径 | 状态 | 最后更新 |
|--------|----------|------|----------|
| 示例项目 | ./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`

```markdown
---
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 确认前，绝不开始编码。**

---

## 📊 状态追踪

| 状态 | 说明 |
|------|------|
| `🆕 原始输入` | 刚收到用户反馈 |
| `🔍 1 级剖析完成` | 表面层解读完成 |
| `🏗️ 2 级剖析完成` | 系统层解读完成 |
| `⏸️ 等待用户决策` | 暂停，等待是否继续深潜 |
| `💻 本地意见完成` | Claude Code 代码分析完成 |
| `🌐 外部意见收集中` | 等待用户引入多模型意见 |
| `✅ 最终方案已确定` | 可以开始编码 |
| `🚧 实施中` | 代码实现进行中 |
| `📦 已完成` | 功能已上线 |

---

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