用途：把“为什么这样修”的决策写成 Agent Note，并用回归测试锁定行为，使后续改动不会无声地撤销修复。核心理念是：修复原因若可能被后人丢失，就在同一次改动中同时提交一条说明（why）和一个回归测试（lock）。
主要能力：提供 new-note.py 脚手架生成笔记并绑定测试；verify-notes.py 校验笔记树（退出非零即失败）；--find 按正则搜索已有笔记；--for-path 反向查找引用某文件的笔记；--audit-commits 从提交历史发现疑似修复但缺笔记/测试的提交；支持归档（--archive）、退役（--retire）与封印。笔记按 {proposed,implemented,rejected,archived}/{class}/yyyy-mm-dd-topic.md 组织，class 为封闭集合：bug-fix、feature、architecture、process、testing、simplification。
使用方式：先定位脚本目录（Claude Code 用 ${CLAUDE_SKILL_DIR}/scripts，其他环境在 ~/.agents/skills 等标准位置查找）。安装到仓库根目录：python3 "$SCRIPTS/new-note.py" --install --dry-run 预览，再执行 --install，会创建笔记树、写入 pre-commit 钩子并向 AGENTS.md（或已有 CLAUDE.md）追加常驻规则。创建笔记示例：python3 "$SCRIPTS/new-note.py" --status implemented --test tests/test_login.py login-retry-race。校验：python3 regression-notes/scripts/verify-notes.py --notes-dir .agents/notes。
适用场景：修复原因不明显、修复代码看似冗余或错误、存在被否决的诱人替代方案、做了权衡取舍，或修复跨文件/共享契约时。普通缺陷只需回归测试，不必写笔记。
限制：笔记树默认 .agents/notes/，可用 --notes-dir 或 NOTES_DIR 覆盖；校验器只读打开笔记、不执行项目代码，绑定与陈旧检查只是存在性检查，绿色仅代表树内部一致，不代表修复有效；Proved: 行可能被伪造，需人工复核；Windows 无 python3 时用 python 或 py -3。