# Reflect

> 复盘当前会话，提取可沉淀的经验。当用户要求复盘、总结经验、提取教训、回顾会话收获时使用

- Skill: `zhuqingxun/reflect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhuqingxun/reflect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuqingxun/reflect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhuqingxun (https://skillmd.com/u/zhuqingxun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhuqingxun/reflect

---


复盘本次会话，按以下流程执行：

## 1. 错误扫描（必须首先执行）

回溯会话中所有失败的工具调用（Bash exit code 非 0、Edit 被拒绝、API 报错等），**对每个错误填表**：

| 错误 | 已有规则？ | 规则遵守了？ | 诊断 |
|------|-----------|-------------|------|
| [错误描述] | 是/否 | 是/否 | [见下方诊断逻辑] |

**诊断逻辑（互斥）**：
- **无规则 + 项目特定知识** → 知识盲区，适合新增规则
- **无规则 + 通用好实践** → 不需要规则（LLM 本该知道）
- **有规则 + 未遵守** → **触发问题**，加强措辞无效（行为类反复错误），转入步骤 3.5 硬化分支（hook 提案 / 频次台账，不许蒸发）
- **有规则 + 遵守了但仍失败** → 规则内容有误，需修正（非新增）

快速修复的错误也不跳过——"一次修好"不等于"不值得反思"。

## 2. 识别经验

回顾会话中的任务，找出成功解决的问题和遇到的障碍。

## 3. 有效性过滤（核心步骤）

对每条候选经验，执行以下测试：

### 测试 A：知识 vs 行为分类

> **一个不了解本项目/平台的资深开发者，会犯同样的错吗？**

- **会** → **知识类**（项目/平台特定信息，LLM 训练数据中没有）→ 进入步骤 4
- **不会** → **行为约束类**（通用好实践，LLM 本该知道）→ **不写入规则**；若是本次会话**反复出现**的行为错误，**转入步骤 3.5 硬化分支**（不再止于"观察项"）

知识类示例：python-pptx 的 `_element` 不是 lxml element、某 API 必须用签名 URL、Git Bash 中 bw 命令会挂起

行为约束类示例：先查 git 历史再试错、API 失败后分析错误码、代码风格遵循 PEP 8、日志用 getLogger

### 测试 B：已有规则重复检查

用 Grep 在 CLAUDE.md 和 rules/ 目录中搜索是否已有语义相近的规则。

- **已有且被遵守** → 不需要任何操作
- **已有但被违反** → 诊断为触发问题（步骤 1 已标记），**不重复写入**
- **未有** → 进入步骤 4

### 过滤结果输出

对每条经验标注过滤结果：

| # | 经验 | 分类 | 已有规则？ | 结论 |
|---|------|------|-----------|------|
| 1 | [描述] | 知识/行为 | 是/否 | 写入 / 硬化:hook提案 / 硬化:台账 / 已有-跳过 |

**对「行为约束类」**：不写入规则。但**不再止于"观察项"蒸发**——若它是本次会话**反复出现**的错误，必须按**步骤 3.5 硬化分支**处理（要么 hook 提案、要么进频次台账）。仅出现一次、且明显是会话内一次性锚定的，可简要记入会话总结提醒用户关注，并在台账计 1 次（见 3.5）。

### 反向测试（进入步骤 4 的闸门）

**reflect 的默认输出是零新规则**。成功标志不是"产出 N 条规则"，而是准确识别本次会话的学习是否已在事中沉淀。

每条结论为"写入"的候选经验，在进入步骤 4 前必须通过以下两项反向测试，任一项未通过则**不写规则**——若其本质是行为/锚定问题（尤其反向测试 #2 判定的上下文锚定），**按行为类转步骤 3.5 处理（不蒸发）**：

1. **论证"不写"不够好**：本次教训如果只靠"事中 case-specific 修复 + 下次会话的 LLM 独立判断"能避免重犯吗？说不出"为什么不够"的候选直接否决
2. **区分知识盲区 vs 上下文锚定**：这个错误是因为 LLM **根本不知道**这件事（知识盲区 → 写规则有效），还是因为**本次会话的前序决策污染了后续判断**（上下文锚定 → 写规则无效，下次会话没有同样污染就不会重犯）？典型的上下文锚定信号：同一错误的多次表现都出现在同一次会话内、且可追溯到同一个前序决策或同一段 context

## 3.5 行为类反复错误硬化分支（核心 · 替代"观察项蒸发"）

> **为什么需要这一步**：行为约束类错误（"知道但没做到"）写规则**无效**——它不是缺知识。全局 CLAUDE.md 早有「根因优先」「事实承接」「验证手段匹配问题域」等规则，但反复违反，因为规则是**被动知识**，在"急于给结论"那一刻不会自动跳出来拦截，且越多越稀释。对行为类，唯一有效沉淀**不是规则文字，而是硬化**。本步骤替代旧版"标记观察项后无后续动作"。

进入本步骤的输入：步骤 3 测试 A 判为「行为约束类」、或反向测试判定为「上下文锚定」的**反复**错误。逐条执行下面三段。

### 3.5.1 先过滤：是不是"会话内一次性锚定"？

与反向测试 #2 一致：若该错误的多次表现都在**同一次会话内**、可追溯到**同一前序决策 / 同一段 context 污染**（典型上下文锚定），它在没有同样污染的新会话里不会重犯。这类**进台账计 1 次即可，不立即升级**——一次性锚定计数低，不该触发硬化。真正要硬化的是**跨会话反复**出现的模式。（这正是台账与反向测试 #2 的和解点：一次性的累计低、自然不升级；反复的才累积到阈值。）

### 3.5.2 自检：是否在"反复蒸发同一教训"？（强制）

记录前，先确认该模式是否已沉淀过——**这是防"reflect 没进化"的闭环关键**：

1. `grep` 频次台账 `~/.claude/logs/behavioral-friction.jsonl` 的 `pattern` 字段（按稳定 slug 匹配同一模式）
2. 必要时 `grep` 项目 `memory/` 与全局 `CLAUDE.md`，看是否已有相关观察
   - **已累计 ≥ 阈值（默认 3 次）** → **禁止再记一次观察项**，强制进入"升级评估"：评估该模式能否 hook 化 / 做成结构化检查清单，产出具体提案交用户确认
   - **未达阈值** → 按 3.5.3 追加一条台账记录

### 3.5.3 二分：能否机械检测？决定出路

| 能否被 harness 在**不依赖 LLM** 的情况下机械检测（grep 工具命令 / 响应即可命中）？ | 出路 |
|---|---|
| **能**（例：PowerShell 工具传 ssh 远程命令含 `$()` 被本地求值 → 命令文本含 `ssh` + `$(` 可正则命中） | 产出 **hook 提案**：注明 hook 类型（PreToolUse / PostToolUse / UserPromptSubmit）+ 触发信号（正则 / 关键词）+ 动作（PreToolUse 经 `hookSpecificOutput.additionalContext` 注入提醒**不阻断** / exit 2 阻断 / 写台账）。交用户确认后落地到 `~/.claude/hooks/` 并注册 `~/.claude/settings.json`。**现成模板**：`~/.claude/hooks/ssh-subexpr-local-eval-warn.sh`（本 feature 试点，PreToolUse 提醒型）、`root-cause-on-retry.sh`（UserPromptSubmit 关键词拦截型）、`neuromem-recall-gate.sh`（exit 2 阻断型） |
| **不能**（例："把非目标环境当验证""反复换根因假设"——无自动探测器） | 记入**行为错误频次台账**（跨会话累计），到阈值由 3.5.2 自检触发升级评估。**现成模板**：`~/.claude/hooks/powershell-friction-{collect,remind,status}.ps1` 这套台账 |

### ⚠️ 台账的诚实边界（输出时不要误导用户）

行为错误频次台账与 `powershell-friction` 台账有**本质区别**，reflect 输出时须如实说明：

- `powershell-friction` 靠 PostToolUse **自动签名扫描**采集（harness 能 grep 出信号），**不依赖 LLM**
- **认知类**行为错误**没有自动探测器**，台账**只能由 reflect 每次运行时自己手写** → **仍依赖 LLM 记得在 reflect 时检查**。它给的是"比蒸发强的持久化 + 跨会话累计升级"，**不是 harness 自动闸门**

→ 只有"能机械检测"那一类才能做成真正的 hook 强制（不依赖 LLM）。不要把认知台账当成 airtight 强制交付，否则用户会发现它照样漏，又一轮"reflect 没进化"。

### 台账记录格式（JSONL，一行一条，写入 `~/.claude/logs/behavioral-friction.jsonl`）

```json
{"ts":"YYYY-MM-DDTHH:MM:SS","pattern":"<稳定 slug，跨会话计数同一模式用>","category":"mechanical|cognitive","session_hint":"<会话主题一句话>","description":"<错误一句话描述>","upgrade_candidate":true|false}
```

`pattern` 必须是**稳定 slug**（如 `non-target-env-as-validation`、`switch-rootcause-without-falsify`、`ssh-subexpr-local-eval`），同一模式复现时复用同一 slug，否则无法正确累计。目录 / 文件不存在时先创建（仿 `powershell-friction-collect.ps1` 的建目录逻辑）。

### 铁律

行为类教训**不再止于"观察项"**——要么 **hook 提案**、要么 **进台账**，**不许蒸发**。reflect 跑完，对每条行为类反复错误的输出必须是 hook 提案 或 台账记录条目（含是否到阈值升级的判定）。

## 4. 提取规则（仅知识类）

将通过过滤的知识类经验抽象为简洁规则（3-5行），判断写入位置：

| 优先级 | 写入位置 | 判断标准 |
|--------|----------|----------|
| **1. 全局 rules 文件** | `~/.claude/rules/<topic>.md` | 跨项目通用，且已有同主题 rules 文件(如 python-development.md)。先 `ls ~/.claude/rules/` 检查 |
| **2. 全局 CLAUDE.md** | `~/.claude/CLAUDE.md` | 跨项目通用，但无匹配的 rules 文件，或属于工作流偏好/协作规范 |
| **3. 项目规则** | 项目根目录 `CLAUDE.md` | 仅限当前项目的架构/API 特定知识 |
| **4. Auto Memory** | `~/.claude/projects/*/memory/` | 参考性经验、历史决策记录 |

**决策流程**：全局规则优先写入已有的同主题 rules 文件(保持 CLAUDE.md 精简)，只有没有匹配的 rules 文件时才写入 CLAUDE.md。

## 5. 确认写入

- 使用 AskUserQuestion 让用户确认每条规则的写入位置（可选：写入建议位置 / 换位置 / 跳过）
- 用户确认后写入对应文件

## 注意事项

- 只提取具有通用性、可复用的经验，忽略一次性或特定场景的内容
- **写规则的目标是减少 CLAUDE.md 的体积而非增加**——每次 reflect 应同时审视是否有过时规则可清理
- 如果本次会话没有产出知识类经验，完全不写入规则是正常的、正确的输出