---
disable-model-invocation: true
name: exp-reflect
description: 当任务完成、解决困难问题、用户要求总结经验/记录项目理解/更新项目规范，或 spec-end/spec-update 需要从当前 Spec 文档判断是否沉淀经验、知识、SOP、工具记忆、长期项目规范时使用。不要用于普通文档摘要、历史记忆检索或已明确内容的直接写入。
allowed-tools: Read, Write, Edit, Glob, Grep
---
# exp-reflect - 经验反思 Skill
## 运行契约
> 把本 Skill 当成一个有边界的反思循环单元：明确读什么、能动什么、怎么算完成、什么时候停、什么时候交还给人。
| 项 | 本 Skill 的约定 |
|----|----------------|
| 输入 | 当前 Spec 目录下的角色产物文档、用户附加提示词、现有记忆索引（查重用） |
| 权限 | 只做"识别 + 分类 + 展示草稿"；实际写入交给 exp-write/skill-creator，规范变更需用户确认后再编辑 AGENTS.md/rules |
| 验证 | 按记忆类型分流（经验/知识/SOP/工具/规范），重大经验与轻量经验分开，已做重复检测 |
| 停止 | 不是所有内容都沉淀；常识、一次性操作、已有文档覆盖的内容不记；判定无可沉淀即停止 |
| 升级 | 发现与现有记忆冲突、或规范变更影响面大时，展示差异并交回用户确认，不自行落盘 |
## 概述
基于 MUSE 框架的"反思 → 结构化 → 记忆化"理念，读取当前任务产出的 Spec 文档，提取可沉淀的记忆，并按记忆类型分流到不同存储层。
**记忆类型识别**：
- **困境-策略对**（经验记忆）→ 按权重分流（重大→exp-write 写入 `spec/context/experience/` / 轻量→Auto Memory）
- **项目理解**（知识记忆）→ exp-write 写入 `spec/context/knowledge/`（架构、数据流、模块分析）
- **技术调研**（知识记忆）→ exp-write 写入 `spec/context/knowledge/`（框架对比、选型分析）
- **程序记忆**（SOP）→ 创建 `sop-xxx` Skill
- **工具记忆**→ 更新 Skill 末尾
- **项目规范/规则记忆**→ 更新薄入口 `AGENTS.md` 或 `.agents/rules/*.md`
**可沉淀的记忆类型**：
1. **经验记忆**：困境-策略对 → 按权重分流（重大→exp-write / 轻量→Auto Memory）
2. **知识记忆**：项目理解、技术调研 → exp-write 写入 `spec/context/knowledge/`
3. **程序记忆**：可复用的多步骤 SOP → 创建 `sop-xxx` Skill
4. **工具记忆**：Skill 执行后的固定后续动作 → 更新 Skill 末尾
5. **项目规范/规则记忆**：长期项目约束与项目偏好 → 更新薄入口 AGENTS.md 或 .agents/rules/
## 触发场景
- 任务完成后，自动提示反思
- 解决了困难问题后
- 用户主动触发：`/exp-reflect`
- 用户带提示词触发：`/exp-reflect 记录数据流`、`/exp-reflect 记录架构`
- 用户要求记录项目规范：`/exp-reflect 更新规范`、`/exp-reflect 记录规则`
## 核心原则
**先分析内容，再判断记忆类型**
不是所有内容都值得记录，需要判断：
| 问自己 | 是 | 否 |
|--------|-----|-----|
| 这是一个"困境→解决方案"的经验？ | **经验记忆** | 继续下一问 |
| 这是项目理解（架构/数据流/模块分析）？ | **知识记忆** | 继续下一问 |
| 这是技术调研（框架对比/选型分析）？ | **知识记忆** | 继续下一问 |
| 这是一个可复用的多步骤流程（>5步）？ | **程序记忆（SOP）** | 继续下一问 |
| 这是以后每次都要遵守的项目规范或规则？ | **项目规范/规则记忆** | 继续下一问 |
| 这是某 Skill 执行后应该做的固定动作？ | **工具记忆** | 不需记忆 |
---
## 执行流程
```
反思流程：
- [ ] 步骤 1：读取当前任务的 Spec 文档
确定当前任务的 Spec 目录（由用户提供，或从上下文推断）
使用 Glob 列出目录下存在的文档，按以下顺序依次读取：
| 文档 | 包含内容 | 主要产出记忆类型 |
|------|----------|-----------------|
| `exploration-report.html` | 项目背景、代码探索、技术选型调研 | 知识记忆（项目理解/技术调研） |
| `plan.html` | 架构决策、接口设计、实现思路及理由 | 经验记忆（设计决策）、知识记忆（架构） |
| `test-plan.html` | 测试边界、验证方法 | 程序记忆（测试流程） |
| `summary.html` | 实际实现细节、与 plan 的偏差及原因 | 经验记忆（实现踩坑、偏差理由） |
| `debug-*.html` | 问题诊断、根因分析 | 经验记忆（困境-策略对，最高价值） |
| `debug-*-fix.html` | 修复方案、影响范围 | 经验记忆（修复策略） |
| `test-report.html` | 测试结果、发现的问题、日志/审计要求 | 经验记忆（测试发现的边界问题）、项目规范/规则记忆 |
| `update-*.html` | 已有功能的迭代需求与修改方案 | 经验记忆（需求变化原因）、知识记忆（功能演进） |
| `update-*-summary.html` | 更新实现结果、影响范围、规范维护审查 | 经验记忆、项目规范/规则记忆 |
| `update-*-review.html` | 更新审查结论、未完成项、不符项 | 经验记忆（审查发现的问题） |
| `lead/team-context.md` | 运行账本（任务进度/问题闭环/决策记录） | 经验记忆（决策理由）、项目规范/规则记忆 |
注意：
- 报告类产物是 HTML，用 Read 直接读取正文即可；`lead/team-context.md` 仍是 Markdown 账本
- 报告的元信息在 `` 的 ``（类型/Spec 目录/角色/创建与更新日期/修订号/分支/PR），
`` 声明关联报告，正文末尾 `rk-links` / `rk-backlinks` 给出双向关联——追溯上下文时读这些
- 读 HTML 报告时以「终稿」内容为准；`` 标记的是已被修订删除的旧文，不要当成有效结论沉淀
- 「修订历史」表记录了每轮改了什么、为什么，是「困境-策略对」和决策理由的高价值来源
- 修订与决策联动：修订历史「原因」列若写了 `D-xxx`（如「按 D-003」），决策过程正文在
`lead/team-context.md` 的「决策记录」里，顺着编号回查选项/结论/理由再沉淀；
「原因」列没有编号的属于笔误、措辞或补充，不要倒推编造决策
- 不存在的文档跳过，不报错
- 注意用户的附加提示词（如"记录数据流"、"记录架构"），优先关注对应文档内容
- [ ] 步骤 2：识别可沉淀的记忆
分析并分类：
| 内容特征 | 记忆类型 | 存储位置 |
|----------|----------|----------|
| 解决了什么问题？为什么这样解决？ | 经验记忆 | spec/context/experience/ |
| 项目架构、数据流、模块分析？ | 知识记忆 | spec/context/knowledge/ |
| 技术调研、框架对比、选型分析？ | 知识记忆 | spec/context/knowledge/ |
| 完成了哪些多步骤操作（>5步）？是否可复用？ | 程序记忆 | sop-xxx Skill |
| 以后每次都要遵守的项目身份、编码、安全、日志、测试、审计、目录/命名规范、产品/前端偏好？ | 项目规范/规则记忆 | AGENTS.md / .agents/rules/*.md |
| 某 Skill 执行后总是需要做什么？ | 工具记忆 | Skill 末尾后续动作 |
- [ ] 步骤 2.5：记忆权重判断
对步骤 2 中识别出的记忆，进行权重分流：
**经验记忆（困境-策略对）**：
| 判断维度 | 重大经验 → exp-write | 轻量经验 → Auto Memory |
|----------|---------------------|------------------------|
| 复杂度 | 涉及多组件协调、非显而易见的解决方案 | 单点技巧、简单调试经验 |
| 关联性 | 需要链接到 Spec/代码文件的结构化记录 | 独立的、无需关联其他文档 |
| 共享性 | 团队/项目级别需要共享的经验 | 个人编码习惯和偏好 |
| 持久性 | 长期有效的架构决策和设计模式 | 临时性的调试技巧 |
**知识记忆（项目理解/技术调研）**：
- 所有知识记忆都通过 exp-write 写入 `knowledge/`
- 不区分权重，因为项目理解类内容本身就是结构化知识
**项目规范/规则记忆**：
- 项目名称/一句话身份、核心技术栈摘要、AGENTS 路由或 import 变化 → `AGENTS.md`
- 启动/部署方式、开发流程细则、长期编码规范、安全规则、日志/审计要求、测试约束、目录/命名规范、产品/前端偏好 → `.agents/rules/*.md`
- `AGENTS.md` 只做入口清单，不承载长篇规范或详细偏好
- 只记录长期规则，不记录一次性实现细节
分流结果：
- 重大经验 → 继续走 exp-write 流程（写入 spec/context/experience/）
- 轻量经验 → 提示用户让 Auto Memory 处理（见「轻量经验引导」）
- 知识记忆 → 继续走 exp-write 流程（写入 spec/context/knowledge/）
- 项目规范/规则记忆 → 展示拟修改的 AGENTS.md / rules 文件，用户确认后直接编辑
- [ ] 步骤 3：检查现有记忆（防止重复）
根据步骤 2 识别的类型，检查对应位置：
- 经验记忆 → 读取 spec/context/experience/index.md
- 知识记忆 → 读取 spec/context/knowledge/index.md
- 程序记忆 → 列出 .agents/skills/ 下所有 sop-* 目录
- 项目规范/规则记忆 → 读取 AGENTS.md 和 .agents/rules/ 下相关规则文件
- 工具记忆 → 读取目标 Skill 的「后续动作」章节
- [ ] 步骤 4：向用户展示分析结果
按记忆类型分组展示
- [ ] 步骤 5：用户确认后执行写入
- 经验记忆（重大）→ 调用 /exp-write type=experience
- 知识记忆 → 调用 /exp-write type=knowledge
- 程序记忆 → 调用 /skill-creator 创建 SOP Skill
- 项目规范/规则记忆 → 直接编辑 AGENTS.md 或 .agents/rules/*.md
- 工具记忆 → 直接编辑目标 Skill 文件
```
---
## 经验草稿格式
```markdown
📝 经验反思结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 经验记忆（困境-策略对）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**标题**：[简短描述问题]
**权重**：🔴 重大经验（建议 exp-write）/ 🟡 轻量经验（建议 Auto Memory）
**判断依据**：[多组件协调 / 需要关联 Spec / 团队共享 / ...]
**关键词**：[关键词1], [关键词2], [关键词3]
**适用场景**：[什么情况下这个经验有用]
**困境**：[描述遇到的问题或挑战]
**策略**：
1. [解决步骤1]
2. [解决步骤2]
**理由**：[为什么这个策略有效]
→ 🔴 重大经验：确认后调用 /exp-write type=experience
→ 🟡 轻量经验：Auto Memory 会自动处理，无需手动写入
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 知识记忆（项目理解/技术调研）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**标题**：[知识主题]
**类型**：项目理解 / 技术调研 / 代码分析
**关键词**：[关键词1], [关键词2], [关键词3]
**内容概述**：
[简要说明这个知识点的核心内容]
**详细内容**：
[根据类型组织内容]
项目理解类：
- 项目概述
- 核心架构
- 数据流
- 关键模块
技术调研类：
- 背景
- 方案对比
- 结论
→ 确认后调用 /exp-write type=knowledge
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 程序记忆（SOP）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**SOP 名称**：sop-xxx-[名称]
**触发场景**：[什么时候使用这个 SOP]
**主要步骤**：
1. [步骤1]
2. [步骤2]
...
→ 确认后调用 /skill-creator 创建 SOP Skill
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 工具记忆（Skill 后续动作）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**目标 Skill**：[Skill 名称]
**新增后续动作**：
1. [动作1]
2. [动作2]
→ 确认后直接编辑 Skill 文件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📏 项目规范/规则记忆（AGENTS.md / rules）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**目标文件**：AGENTS.md / .agents/rules/[规则文件].md
**规则类型**：入口路由 / 项目身份摘要 / 编码规范 / 安全规则 / 日志审计 / 测试约束 / 目录命名 / 开发流程 / 产品体验 / 前端风格
**新增或修改的规则**：
1. [规则1]
2. [规则2]
**触发依据**：[本次 Spec 中哪个决策、问题或测试结果要求长期遵守]
**适用范围**：[全项目 / 某模块 / 某类任务]
→ 确认后直接编辑目标规范文件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
是否执行以上记忆操作？
```
---
## 记忆质量判断标准
### 值得沉淀的记忆
| 记忆类型 | 值得沉淀的特征 |
|----------|---------------|
| **经验记忆** | 解决了反复出现的问题、非显而易见的解决方案、涉及多组件协调、踩过的坑 |
| **知识记忆** | 项目架构理解、数据流分析、技术调研结果、框架对比、模块设计解读 |
| **程序记忆** | 多步骤流程（>5步）、可复用、有明确的触发条件和验证方法 |
| **工具记忆** | 某 Skill 执行后总是需要的固定动作、形成工作流衔接 |
| **项目规范/规则记忆** | 长期有效、未来每次都要遵守、能防止反复犯错；入口变化放 AGENTS.md，详细规则和偏好放 rules |
### 不值得沉淀的记忆
| 特征 | 示例 |
|------|------|
| 常识性内容 | "变量命名要有意义" |
| 一次性操作 | "修复了某个 typo" |
| 项目特定的临时方案 | "临时注释掉某行代码" |
| 已有文档覆盖 | 框架官方文档已说明的内容 |
| 一次性实现细节 | 某个临时变量名、某次特殊修补 |
| 不稳定偏好 | 尚未验证、只对本次任务有效的个人偏好 |
---
## 重复检测规则
### 相似性判断标准
```
Q1: 困境描述的核心问题是否相同？
Q2: 策略的主要方法是否相同？
Q3: 适用场景是否相同？
如果 Q1 和 Q2 都是"是" → 视为重复
如果 Q1 是但 Q2 否 → 可能是同一问题的不同解法，询问用户
如果 Q1 否 → 不重复，可以新增
```
### 重复处理示例
```markdown
⚠️ 发现相似经验
现有经验 [EXP-001]：WebSocket 连接超时
- 困境：长时间任务导致连接断开
- 策略：三层防护（Nginx超时+心跳+重连）
本次经验与现有经验高度相似。
请选择：
1. 不记录（现有经验已足够）
2. 更新现有经验（补充新内容）
3. 新增经验（场景确实不同）
```
---
## 自动触发信号
Agent 应在以下场景**主动建议**是否需要反思（建议性，非强制）：
| 信号 | 提示话术 |
|------|----------|
| 解决了困难问题 | "这个问题的解决方案可能值得记录，要反思一下吗？" |
| 做出了架构决策 | "这个决策及其理由可能对未来有帮助，要沉淀吗？" |
| 用户说"以后都这样" | "好的，我来提取这个经验以便未来参考。" |
| 任务完成 | "任务完成了，我来读取本次 Spec 文档进行反思，请确认 Spec 目录路径（或直接回复确认当前目录）。" |
---
## 与其他 Skill 的协作
| 场景 | 协作 Skill |
|------|-----------|
| 被 spec-end 调用 | spec-end 需提供当前任务的 Spec 目录路径，exp-reflect 据此定位文档 |
| 写入经验记忆 | → `/exp-write type=experience` 写入经验文件和索引 |
| 写入知识记忆 | → `/exp-write type=knowledge` 写入知识文件和索引 |
| 创建程序记忆（SOP） | → `/skill-creator` 创建 SOP Skill |
| 更新项目规范/规则 | → 直接编辑 `AGENTS.md` 或 `.agents/rules/*.md` |
| 更新工具记忆 | → 直接编辑目标 Skill 文件末尾 |
| 检查是否重复 | → 读取 `spec/context/experience/index.md` 和 `spec/context/knowledge/index.md` |
| 更新现有记忆 | → `/exp-write` 更新模式 |
---
## 轻量经验引导
当步骤 2.5 判断为轻量经验时，不走 exp-write，而是提示用户：
```markdown
💡 这条经验比较轻量，建议让 Auto Memory 自动处理：
**经验**：[一句话描述]
Auto Memory 会自动记住这类日常经验，无需手动写入 exp/ 目录。
如果你认为这条经验足够重要需要结构化记录，请告诉我，我会走 exp-write 流程。
```