把「出错 → 诊断 → 修复」的浪费，变成「动笔之前就知道不能怎么写」的规则库。给 Agent 装一个"老师"——在它动手写命令、写代码、装包之前，先把规则送到它面前。
- 🛡️ 前置防错 — 写命令前核对禁则，命中即换写法，纠错环节根本不发生
- 📋 禁则式记录 — 「禁止 X —— 因为会 Y」，一条一行、可扫描、省 token
- 🔔 常驻触发 — 元规则每轮都在上下文，杜绝"事后才想起查"
- 🧱 双层隔离 — 指令文件只放元规则 + ≤5 条铁律，完整禁则进记忆按需检索
- 🌱 渐进沉淀 — 报错 / 用户纠正 / 他处案例三时机，同类错误合并单条
- 📊 验证数据 — HIT / INCIDENT / RULE 三类事件记录，效果可量化（首份验证报告 已于 2026-09-02 回填）
| 层 | 技术 |
|---|---|
| 常驻指令层 | AGENTS.md / CLAUDE.md / REASONIX.md（每个相关 turn 自动加载） |
| 记忆层 | 平台长期记忆 / lessons.md（按需检索） |
| 校验 | scripts/validate_lessons.py（禁则格式 lint） |
| CI | GitHub Actions（push / PR 自动校验） |
┌───────────────────────────────────────┐
│ 常驻指令层（每轮在上下文，cache-stable)│
│ 元规则：写之前先查错题本 │
└──────────────────┬────────────────────┘
│ 元规则触发检索
┌──────────────────▼────────────────────┐
│ 错题本（记忆 / lessons.md，按需检索） │
│ 禁止 X —— 因为会 Y │
│ （完整禁则清单，可数百条） │
└───────────────────────────────────────┘
Step 1：创建常驻指令文件
在工作区放一个 AGENTS.md（Claude Code 用 CLAUDE.md，Reasonix 用 REASONIX.md），内容直接抄 templates/AGENTS.md（「高频铁律」的 （示例） 条目是占位，换成你自己最常踩的坑）：
## 元规则：动手前核对错题本（防错优先，不做事后纠错）
- 每次执行工具/命令、写代码、装包、调 API **之前**，按动作类型查对应领域禁则
（执行命令→[bash]/[shell]；写代码→[语言]/[编码]；装包→[安装]；调 API→[工具]/[配额]…），
命中即换预防性写法，**不等报错再纠错**。
- **可见核对**：每次调用 shell 工具前，先输出一行 `[错题本核对] 无命中 / 命中X→改用Y`。
- 命令失败 / exit code 非 0 / 工具报错后：按「禁止 X —— 因为会 Y」格式沉淀或扩充错题本。Step 2：创建错题本
复制 templates/lessons.seed.md（种子库：真实沉淀的 9 条禁则，标注了适用范围）为 lessons.md，删掉你不用的领域；纯空模板在 templates/lessons.md。
Step 3：遇到第一个错误，沉淀第一条
命令报错后，按此格式追加（同类问题第二次出现时编辑已有条目，不新增）：
- [bash/PowerShell] 禁止在 bash 双引号内嵌含 `$_` 的 `powershell -Command "..."`
—— 因为 `$_` 会被 bash 当变量展开吞掉 → 命令损坏 exit 1；
改写成 `.ps1` 脚本执行，或整串用单引号包裹让 bash 零展开| 场景 | 动作 |
|---|---|
| 准备写命令/代码/装包 | 先核对错题本相关条目，命中即换写法 |
| 命令报错 / exit code 非 0 | 沉淀为「禁止 X —— 因为会 Y」禁则 |
| 用户直接纠正 | 沉淀（不等犯错） |
| 同类错误第二次出现 | 扩充那一条（加示例/变体），不新建 |
| 清单膨胀 / 有过时条目 | 修剪：合并重复、删除不再适用的 |
- 禁则式记录：
禁止 X —— 因为会 Y，一条一行、可扫描、省 token；"如何解决"默认丢弃，只保留可复用的预防性写法 + 一行根因 - 常驻指令 > 被动检索：记忆检索在"写之前"没有关键词可搜，必须靠每轮常驻的元规则触发——这是本方案区别于所有 lessons/记忆类方案的根本点
- 双层隔离：指令文件只放元规则 + ≤5 条铁律（防膨胀失效），完整禁则进记忆/文件按需检索。实战演进（2026-08-13）：平台 pinned 记忆有字符预算（如 1500），禁则涨到一定规模后记忆无法再更新——解法是把完整禁则全文外置独立文件（如
%APPDATA%\reasonix\self-improvement-lessons.md），记忆/指令只留指针，更新走文件（无预算限制）。见 docs/implementation.md 情况 A - 渐进沉淀 + 修剪：沉淀时机有三种；同类合并单条；定期修剪防清单腐烂
完整论证见 docs/principle.md。
| 领域 | 禁则 | 来源 |
|---|---|---|
| bash | 禁止直接 ls 可能不存在的路径 → exit 2 判 failed |
实际运行：探测目录 |
| bash/Windows | 禁止把 MSYS 路径（/tmp）直接传给 Windows 程序 → 报成功但没写文件 |
实际运行：批量生成 |
| bash/PowerShell | 禁止在 bash 双引号内嵌含 $_ 的命令 → 命令被吞损坏 |
实际运行：注册表查询 |
| 浏览器自动化 | 禁止连续操作间隔 >2-3 秒 → daemon 清空闲 session | 实际运行：BrowserAct |
| 指标 | 数值 | 说明 |
|---|---|---|
| 错题本条目 | 9 → 76 | 净 +67（含合并去重） |
| 命中 HIT | 3 次 | heredoc 定界符 / 路径存在判断 / $_ 单引号 |
| 报错 INCIDENT | 6 次 | 08-06 三条 + 08-13 三条 |
| 复发（observed） | 2 次 | 「只读命令豁免核对」「标注文本拼进命令」各复发 1 次 |
| RULE 记录 | 新增 3 / 扩充 3 / 修剪 1 / 区间批量 1 | — |
⚠️ 诚实声明（指标口径已按 docs/validation.md 重构）：
- 上表是"观察到的原始事件数"，不是效果率。原报告曾写"复发率 40%"，但按 docs/validation.md 的指标定义，复发率 = incidents_after_rule / exposures_to_rule，而 exposures（规则实际被应用的次数）本周期未记录，故 "40%" 不成立，只能表述为 "observed 2 regressions"——2 个已沉淀禁则对应的重复错误，样本极小，不能作为任何真实复发率估计。
- 命中率（H/T）不统计：检索触发次数 T 未逐次记录。
- 数据集分层：08-14 ~ 09-02 跨会话沉淀的 55 条属 Dataset D（unattributed bulk import），validation-log 未逐日归因，仅可作知识库，不可用于任何效果 claim（按 v0.1 数据治理，见 docs/validation.md）。76 条中大多带"实测日期"归因（Dataset B），但未逐条关联到 RULE 事件，严谨计为 D 层。
- 结论与下一步：本周期只证明了"Agent 可被提示去记住错误"（记录达成），未证明"记住错误能让 Agent 少犯错误"（效果未验证）。2026-09-02 已升级沉淀可见仪式 + add-lesson.py（解决记录脱节）；下一周期按收敛结论做：① 规则大清洗分层（核心集 ≤12 条常驻，其余降参考附录）② 规则切片化+触发式检索 ③ 数据集分层治理，并引入规则暴露次数（exposure）记录，才能给出真实复发率。最终效果用 A/B 对照实验 验证（协议已定义，待 exposure 数据积累后执行）。
与其他方案对比（完整版见 docs/comparison.md）
| 方案 | 触发时机 | 前置防错 | 存储 | 评价 |
|---|---|---|---|---|
| 本方案（WrongBook） | 常驻指令 + 按需检索 + 平台 hook 强制层（可选） | ✅ | 指令文件 + 记忆/lessons.md + hook 事件账本 | 零依赖、平台无关；默认纯指令驱动，在支持 hooks 的平台（Claude Code 的 hooks、Reasonix 的 settings.json 等）可再生强制前置注入与失败自动记账（2026-09-02 v0.4 起） |
| Claude Code 的 CLAUDE.md rules | 常驻 | ✅ | 单一指令文件 | 思路相近；规则与指令同文件，需注意控制体积 |
| lessons 数据库类 skill | 被动检索 | 部分 | 外部 DB | 适合团队级知识库；需运行维护 |
| graphify 等 lessons 聚合器 | 会话后聚合 | 部分 | 生成的 LESSONS.md | 适合项目复盘场景 |
| mem0 / MemGPT / Letta | 语义检索 | 部分 | 向量库 | 记忆基础设施，定位不同；适合大规模记忆需求 |
wrongbook/
├── README.md # 本文档（中文）
├── README.en.md # 英文版
├── LICENSE # MIT
├── templates/
│ ├── AGENTS.md # 通用常驻指令模板（任何 Agent 可用）
│ ├── lessons.md # 错题本空模板（禁则清单）
│ ├── lessons.seed.md # 种子库：真实沉淀的 9 条禁则（推荐起点）
│ └── REASONIX.md # Reasonix 平台专用版（含存储与沉淀流程）
├── docs/
│ ├── principle.md # 原理详解
│ ├── implementation.md # 实现细节（平台适配、维护流程）
│ ├── comparison.md # 与其他方案深度对比
│ ├── validation.md # 验证方法：指标、记录协议、规则生命周期
│ ├── experiment.md # A/B 对照实验协议
│ └── hooks.md # 平台 hooks 强制层（适配器层，评审收敛版）
├── data/
│ └── validation-log.md # 验证数据日志（2026-08-06 起）
├── scripts/
│ ├── validate_lessons.py # 错题本格式校验脚本（防错本身的防错）
│ ├── add-lesson.py # 一键沉淀：追加全文+记 validation-log+同步副本
│ ├── wrongbook-audit.py # 外部审计：核对率/exposure/规则生命周期三清单
│ ├── generate-rule-index.py # 生成领域切片索引 rule-index.md
│ └── hooks/
│ ├── hook-session-start.py # SessionStart：注入核心禁则（强制前置核对）
│ └── hook-post-tool-failure.py # PostToolUseFailure：失败自动写外部事件账本
└── .github/
└── workflows/lint.yml # CI：push/PR 自动校验错题本格式
MIT —— 见 LICENSE。欢迎 PR 补充其他平台的适配模板。