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

过滤结果输出

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

对「行为约束类」：不写入规则。但不再止于"观察项"蒸发——若它是本次会话反复出现的错误，必须按步骤 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 二分：能否机械检测？决定出路

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

行为错误频次台账与 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行），判断写入位置：

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

5. 确认写入

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

注意事项

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