learnings 是一个面向提交前阶段的复盘技能,目标是回答一个问题:本次会话中是否出现了下一位维护者(人或 AI 代理)会后悔没被记录下来的经验。它明确强调门槛很高,多数会话没有值得新增的内容,直接给出“没有值得沉淀的内容”也是有效结果,不应为了证明技能有用而虚构发现。
用途:在提交代码或发起 PR 之前使用,或在用户提出相关要求时使用,用于判断是否应把经验写入 CLAUDE.md(面向后续 AI 代理的仓库工作说明)或 README.md(面向克隆仓库的人类开发者的说明)。
主要能力与判定标准:只有满足至少一项的候选经验才值得沉淀,包括:非显而易见的坑(本次耗费时间、下次仍会耗费时间);代码本身无法自说明的约定(模式、命名规则、结构选择);可复用的用户纠正(用户对某做法的反对可推广到本任务之外);外部依赖或环境要求(新克隆项目缺少就无法运行);带原因记录的架构决策。明确拒绝的候选包括:PR 内容摘要、重述代码已明显表达的内容、与项目无关的通用最佳实践、不会复发的一次性调试修复、以及现有 CLAUDE.md/README.md 已覆盖的内容。
使用方式(资料给出的步骤):第一步并行收集上下文,包括 git diff(未暂存)、git diff --cached(已暂存)、git status、git log --oneline -20,读取 CLAUDE.md(项目根目录,其次 .claude/CLAUDE.md)与 README.md,并回顾本次会话中用户纠正过什么、自己卡在哪里、发现了什么非显而易见的代码库知识。第二步按上述门槛筛选候选。第三步决定目标文件:CLAUDE.md 面向下一次 AI 会话,README.md 面向人类开发者;若项目没有 CLAUDE.md 且确有内容,可提议创建,但不应创建空脚手架。第四步只提议、不提交:按固定格式列出建议加入 CLAUDE.md 与 README.md 的具体条目及一行理由,并列出“考虑过但被拒绝”的内容,然后询问是否应用这些编辑;未经明确批准不得修改这两个文件。若没有内容过门槛,则输出“没有值得沉淀的内容”并给出一句原因。
适用场景:仓库提交前检查、PR 前收尾、把会话中的非显而易见经验整理为长期文档。限制:不修改代码;不自动提交或编辑文档;不编造发现;判断依赖会话与仓库实际内容。