reflect

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

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

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）

{"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 应同时审视是否有过时规则可清理
• 如果本次会话没有产出知识类经验，完全不写入规则是正常的、正确的输出