案例库与个人沉淀

手册真正有价值的部分，不是复制官方文档，而是把自己的真实任务沉淀下来：原始需求、关键 prompt、agent 的失误、diff 观察、验证证据、最后写进哪一层规则。

本章目标

知道一个可复用案例应该记录哪些字段。
能把一次失败或返工转化成规则、模板或 Skill。
能维护一份个人 coding agent playbook。

一个案例应该长什么样

任务背景：原始需求是什么，为什么要交给 agent。
初始 prompt：你怎么描述目标、上下文、约束和验收。
关键转折：它在哪里跑偏，你怎么纠正。
diff 观察：最终改了哪些文件，有没有无关改动。
验证证据：命令结果、页面检查、截图、CI 状态。
沉淀结果：留在 prompt、写进规则、做成命令/Skill/Hook/MCP，或不沉淀。

案例：重整手册章节

CASE

从“内容很空”到“研发工作流手册”

场景

手册已有很多内容，但目录看不出主线：选择任务、完整教程、工程原则、prompt、验证、安全、规则、扩展混在一起。需要对照官方最佳实践重排。

可以这样说

请先读取当前手册目录和正文密度，再对照 Codex 与 Claude Code 官方 best practices。目标不是逐段改字，而是判断章节是否形成研发工作流。给出新目录和每章要补的核心内容，确认后再改。

压缩 transcript

先识别问题：任务输入和上下文管理被埋在中间。
对照官方：Codex 强调 context、AGENTS.md、config、MCP、skills、automation；Claude 强调 verification、explore-plan-code、context/session。
调整方向：把手册重排成边界、输入、工作流、上下文、验证、规则、安全、扩展、Git、案例、工具对照。

diff 观察

目录从工具功能顺序改成研发交付顺序。
完整教程变成贯穿案例，不再承担全部入门解释。
新增案例库章节，把使用沉淀独立出来。

验收点

目录第一眼能看出做什么。
每章都有判断标准或案例。
Claude 内容只作对照，不喧宾夺主。
最终运行 lint。

案例：手册配图溢出

CASE

截图比文字描述更有效

场景

移动端手册配图超出边界。只说“图片质量有问题”太泛，截图、页面 URL、元素位置和视口尺寸更能指导修复。

可以这样说

目标：修复手册所有配图在移动端超出边界的问题。
上下文：当前页面 /manual/agent/complete-tutorial，截图标出的 img 在 648x662 视口下边界不协调。
约束：不重做页面设计，不替换内容，不新增图片生成流程。
验收：检查所有手册配图在移动端和桌面端不横向溢出，caption 不遮挡，运行 npm run lint。

验收点

输入包含页面、元素和视口。
修复覆盖所有同类配图。
浏览器截图验证。
没有顺手重做视觉系统。

从案例沉淀到规则

只出现一次的问题，不急着写进规则文件。
同一类问题出现两次，先写成 prompt 模板。
同一流程稳定跑三次，再考虑做成命令或 Skill。
必须每次执行的检查，用 Hook，而不是提醒 agent 记得做。
涉及外部实时数据的流程，优先 CLI；CLI 不够再接 MCP。

案例复盘 prompt

请复盘这次 agent 协作，整理成案例：任务背景 / 初始 prompt / agent 跑偏点 / 我如何纠正 / 最终 diff 观察 / 验证证据 / 应该沉淀到哪里。只记录能复用的经验，不写流水账。