在失败、用户纠正或验证成功暴露可复用教训时…

当工具/流程失败、用户纠正假设、重复出现同一 workaround 或聚焦测试证明更好方法时，捕获脱敏候选、运行可执行行为评估，并将验证与应用分离。

适用场景

解决思路

1. 每次运行必须落在且仅落在一个状态：candidate（可复用但未验证）、validated（有代表性证据支持但尚未声明修改 owner）、applied（已验证教训已安装到一个具名持久 owner 并有变更引用）、rejected（被证伪、不安全、过于特定或已过时）、superseded 或 rolled_back（已应用/已验证的教训被替换或回滚）、no-delta（未发现可复用行为变更）、open-question（证据不足并指明缺失的证明）。
2. 在编辑持久指导前，先声明 Start Packet：future behavior（下次应做何不同）、representative task（一个应能成功的具体场景）、evidence（当前来源、失败输出、用户纠正或聚焦测试）、owner（拥有它的唯一 skill、instruction 文件、脚本或运行时组件）、write boundary（允许修改的文件与必须保持本地的信息）、proof（确认新行为的命令、eval 或 review）。
3. 若 Start Packet 任一项未知，则捕获为 candidate 并在验证或应用前停止。
4. 捕获信号时优先事实而非解释，只记录最小可复用摘要；不要复制 transcript、工具输入、凭据、私有路径或客户数据。
5. 使用显式启用的 Claude Code 失败钩子（通过 apb init --hooks）调用：agent-playbook self-improve。
6. 手动纠正或成功使用显式摘要与证据标签：apb self-improve capture --kind correction --summary "Verify the current source before relying on cached state" --evidence "focused-test"。
7. CLI 将脱敏事件与去重候选存储在 ~/.agent-playbook/self-improvement/；可用 AGENT_PLAYBOOK_DATA_DIR 或 --data-dir 覆盖根目录。
8. 仅当以下全部为真时保留 candidate：描述未来行为而非仅发生的事；在单个私有任务或仓库之外有用；不与当前权威来源冲突；存在狭窄 owner 与现实的验证路径。
9. 使用 apb behavior inbox 查看优先级队列；重复证据增加 occurrence count，但不自动增加真实性。
10. 使用 apb behavior owners <candidate-id> --repo . 获取本地建议，但把每个结果当作 review candidate 而非 ownership 决定。
11. 选择能证伪 candidate 的最小证明，编码为可执行 artifact，并用 apb self-improve eval 运行；schema 与安全边界见 references/eval-artifact.md。
12. 按 candidate 类型选择最小证明：prompt 或 workflow 规则用代表性 prompt 加 rubric；CLI/runtime 行为用聚焦自动化测试；外部集成用针对当前文档/运行时的实时能力检查；安全规则用展示不安全路径被阻止的负向测试；重复启发式用多个独立 episode 或显式人工确认。
13. 区分事实、假设与缺失证据；仅结构验证不能证明指导在语义上是最新的或可被宿主执行。
14. 先运行 artifact；当旧行为可安全复现时推荐 baseline 场景，且至少需要一个 candidate 场景：apb self-improve eval cand-123 --artifact behavior-eval.json。
15. 验证时只接受同一 candidate 的、由 CLI 生成的通过 eval 结果：apb self-improve review cand-123 --decision validate --reason "baseline reproduced and candidate scenarios passed" --eval-result /path/printed/by/the/eval/command.json；这不声明运行时行为已改变。
16. 编辑 owner 前生成本地 Behavior Change Proposal：apb behavior proposal cand-123 --owner "skill:self-improving-agent" --output behavior-proposal.md；proposal 包含行为 diff 意图、eval 证明、验收标准、隐私边界与回滚计划，但不编辑 owner 也不创建远程 pull request。
17. 修改恰好一个持久 owner 后，单独记录应用：apb self-improve review cand-123 --decision apply --reason "installed after the focused test passed" --owner "skill:self-improving-agent" --change-ref "commit:abc123"。
18. 其他决策：apb self-improve review cand-123 --decision observe --reason "needs a second episode"；apb self-improve review cand-123 --decision reject --reason "project-specific exception"。
19. 应用到最狭窄的 owner：行为可强制执行时用可执行测试、脚本或 validator；需要 agent 判断时用拥有该行为的 skill 或其 reference；仅项目级约束才用项目 instructions；应被检索而非总是加载的持久事实用 knowledge notebook。
20. 绝不在捕获的副作用中静默修改仓库规则、发布包或触发外部动作。
21. 应用后运行代表性任务并报告：candidate id 与最终状态；所用证据与仍不确定之处；被修改的持久 owner；可执行 eval 结果与 artifact hash；回滚路径。
22. 若新规则未改变代表性行为，则回滚或拒绝它。
23. 导出已应用规则与开放 candidate 为 Markdown 供 Obsidian 或其他本地知识系统使用：apb self-improve export --output /path/to/vault/Agent/Learning.md；导出是 sink 而非事实来源，candidate 与 active-rule 状态仍以结构化、可审计形式保存在 CLI 数据目录。
24. 检查当前宿主再声明支持：Claude Code 仅通过显式 apb init --hooks 安装确定性失败钩子；Codex、Gemini、DeepSeek Harness 支持 skill 分发，但学习事件接线取决于各宿主当前扩展 API；不支持的钩子必须保持手动或适配器特定，绝不用未记录行为模拟。
25. 使用 apb conformance 检查本地静态契约；proven 的分发或钩子配置不证明宿主发现或运行时调用，这些在观察到宿主运行提供有界证据前保持 unverified。
26. 修改此 skill 时使用 evals/cases.json 与 evals/rubric.md。
27. 完成检查清单：candidate/no-delta 决策显式；存储文本最小、脱敏且可移植；相关时检查当前权威来源；验证使用同一 candidate 的通过可执行 eval 结果；应用指明一个持久 owner 与具体变更引用；应用后测试代表性行为；无私有项目细节进入公开 skill 资产。

适用边界 · 注意事项

• 不要用于常规会话摘要、原始 transcript 存储、无证据的推测想法或属于项目文档的项目事实。
• 当 Start Packet 任一项未知时，不要进入验证或应用，只捕获 candidate 并停止。
• 不要仅凭结构验证就声称指导语义最新或可被宿主执行；也不要在未观察到宿主运行时声称支持。