lesson-learned

lesson-learned skill 概览

lesson-learned skill 会把最近的 Git 活动转化为具体的软件工程经验总结。它不是给你一套抽象的“最佳实践”，而是直接检查真实的 diff、提交历史和被修改的文件，再把这些变化映射到 SRP、DRY、KISS、YAGNI 等明确命名的原则，以及相关的反模式上。因此，lesson-learned 特别适合这样一种场景：代码已经改完，你想回头回答——这次工作到底说明了什么、我们做了什么取舍、下次哪些做法该重复、哪些该避免？

lesson-learned skill 适合哪些人

最适合的使用者包括：

• 刚完成某个功能、重构、bug 修复或代码清理的开发者
• 希望在 PR 之后拿到一份偏“学习总结”而不是单纯挑错结论的 reviewer
• 想在团队里建立轻量工程复盘习惯的技术负责人
• 需要解释近期代码改动背后工程原则的 agent

如果你想要的是基于真实仓库历史的设计反思，那么 lesson-learned skill 比泛泛的“review this code”提示词更合适。

lesson-learned skill 实际解决的是什么问题

它的核心任务并不是传统意义上的代码评审，不是简单判断“过 / 不过”。lesson-learned 是回看已经完成或进行中的工作，从 diff 中提炼出 1–3 条有依据的经验结论。高质量输出通常会包含：

• 原则名称
• 这次改动如何体现该原则
• 为什么这件事重要
• 下一步建议

这种结构尤其适合用于复盘、带教，以及 PR 中的学习型备注。

lesson-learned 与通用提示词的区别在哪里

最关键的有两点：

1. 它是以 Git 历史为驱动的，分析的是实际发生过的改动，而不是假设性的代码片段。
2. 它依赖一套原则参考资料，尤其是 references/se-principles.md，这能让模型在命名模式和总结原则时使用一致的术语。

这两者结合起来，能让 lesson-learned 产出的结论更像是“代码自己说明了这些经验”，而不是从软件工程教材里生硬套出来的。

什么情况下不该选 lesson-learned

如果你的真实目标是下面这些，建议不要优先使用 lesson-learned：

• merge 之前逐行找 bug
• 做安全审计
• 只看代码风格 / lint 反馈
• 在还没有实际代码变更时做架构规划
• 面对一个范围不清晰的大型代码库做笼统审查

这些场景下，先用 code review、security 或 design 类 skill，通常更合适。

如何使用 lesson-learned skill

lesson-learned 的安装上下文

仓库没有在 skills/lesson-learned/SKILL.md 里提供专门的安装命令，因此安装方式取决于你的环境如何从 softaworks/agent-toolkit 加载 skills。如果你的环境支持从该仓库添加 skill，常见写法是：

npx skills add softaworks/agent-toolkit --skill lesson-learned

如果你的 agent 是直接从仓库加载 skill，则使用对应路径：

skills/lesson-learned

无论哪种方式，都要把 SKILL.md 当作运行时行为规范来看，而不只是 README。

首次使用前先读这些文件

如果你想快速上手、尽量少猜，建议按这个顺序阅读：

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

这里有个非常容易忽略、但很关键的采用细节：这个 skill 明确写了，在加载 se-principles.md 之前不要继续分析。

lesson-learned skill 需要什么输入

lesson-learned usage 在以下条件具备时效果最好：

• 一个带 Git 历史的仓库
• 当前分支名，或者像 main 这样的明确对比目标
• commit range、commit SHA、分支 diff，或 working tree diff
• 足够的文件上下文，能查看改动最多的那些文件

如果没有 Git 上下文，输出会很快滑向泛泛而谈。

先选对分析范围，再谈结果质量

这个 skill 的效果很大程度上取决于你给它的范围是否清晰。仓库里其实给了很实用的默认范围：

• feature branch：将当前分支与 main 对比
• main branch：分析最近 5 个 commits
• specific commit：检查单个 SHA
• working changes：查看 unstaged 和 staged diff

一份好的 lesson-learned guide，第一步就是强制把范围定清楚。范围一旦模糊，结果通常会把互不相关的经验教训混在一起。

提升 lesson-learned 使用效果的常用 Git 命令

这个 skill 自己的工作流主要围绕这些常见 Git 视图展开：

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

你不需要每次都把所有命令跑一遍。关键是选那个最能对应“你希望它解释哪段改动故事”的命令。

把模糊请求改成高质量提示词

弱提示词：

“Reflect on my recent work.”

更强的提示词：

“Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs.”

这类提示词之所以更有效，是因为它：

• 定义了范围
• 明确指出 skill 依赖的参考文件
• 限制了分析面
• 规定了输出结构

面向 Code Review 的 lesson-learned 提示词模式

lesson-learned for Code Review 最适合作为常规 review 之后的一层反思补充，而不是替代 review。本地实用的提示词可以这样写：

“Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point.”

如果你希望 review comment 不只是“拦截问题”，而是顺带形成团队学习，这种用法很有价值。

建议要求的输出格式

可以让它按这种紧凑结构输出：

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

这和仓库的设计意图是一致的，也能减少空泛填充。

大 diff 该怎么处理

面对大型 PR，不要让这个 skill “分析所有内容”。更好的做法是：

• 先找出改动最多的文件
• 按主题给改动分组
• 忽略明显的机械式修改
• 只要求输出 1–3 条 lesson

它最擅长的是提炼模式，不是穷举每个文件发生了什么。

一个省时间的常用 workflow

比较稳妥的流程是：

1. 加载 se-principles.md
2. 选定 scope
3. 查看 Git log 和 diff
4. 阅读改动最多的文件
5. 按需加载 anti-patterns.md
6. 基于证据生成 1–3 条 lesson
7. 如果结果太泛或说教味太重，再继续 refine

这个顺序是有意义的，因为原则目录会给分析提供更稳定、更准确的表达框架。

lesson-learned skill 常见问题

lesson-learned 适合初学者吗？

适合，但前提是初学者手上有真实改动可分析。这个 skill 是借助“你刚刚做过的工作”来解释工程原则，通常比先啃理论更容易吸收。反过来说，如果没有仓库访问权限，或者最近没有 diff，它的帮助就会明显下降。

lesson-learned 和 code review 是一回事吗？

不是。lesson-learned 更偏回顾式、原则导向；而 code review 一般更偏正确性、风险控制和可维护性。两者有重叠，但最终输出目标并不相同。

lesson-learned skill 必须要有 Git 访问能力吗？

如果你想要比较强的结果，答案是要。这个仓库的设计就是围绕 Git 历史和 diff 展开的。如果你只是粘贴一段代码，模型依然可以评论一些原则，但那已经不是这个 skill 最有优势的使用方式了。

为什么 lesson-learned 比普通提示词更强？

优势在于它的结构化约束：明确选择范围、强制引入原则参考、并通过一套流程把 lesson 和具体代码信号绑定起来。普通提示词往往会直接滑向泛泛的“best practices”。

lesson-learned 能用在未提交的改动上吗？

可以。这个 skill 支持通过 git diff 和 git diff --cached 分析 working changes。如果你在提交前就想弄清楚这次改动体现了什么经验或做了什么取舍，这种用法很实用。

什么情况下 lesson-learned 不太适合？

以下场景建议谨慎使用：

• 最近没有真正有意义的代码变化
• diff 主要是生成文件或格式化噪音
• 你更需要的是缺陷分诊，而不是复盘反思
• 一个分支混进了很多互不相关的任务

这时要么先缩小范围，要么先换别的 skill。

如何提升 lesson-learned skill 的使用效果

给 lesson-learned 一个更窄、更完整的“故事”

影响质量最大的杠杆就是 scope。“我过去一个月的工作”太宽了；“这次把 API 调用和 UI 渲染拆开的重构”就好很多。范围越收敛，lesson-learned 提炼出的原则越锋利，证据也越扎实。

每次都加载 principles reference

这个仓库在这点上写得非常明确：分析前应该先加载 references/se-principles.md。如果跳过它，模型也许仍然能给出一些观察，但在模式命名的一致性，以及把代码改动和公认原则对应起来这两点上，会明显变弱。

用 anti-patterns 保持平衡，不要变成纯负面点评

references/anti-patterns.md 最适合在 diff 中已经出现风险信号时使用，比如：

• 修改零散、难以收束
• 抽象过度
• “god” 模块继续膨胀

建议在提示词里要求它使用相对温和的措辞，这样结果会更有帮助，而不是像在惩罚开发者。

明确要求证据必须绑定到改动文件

一个非常常见的失败模式，就是只有高层建议，没有任何证据。想提升 lesson-learned 输出质量，可以明确要求它给出：

• 涉及了哪些 changed files
• 发生了什么结构性变化
• 这意味着什么 trade-off
• 为什么它对应某个具体原则

证据，才是把“真实 lesson”和“套话点评”区分开的关键。

限制 lesson 的数量

lesson 越多，通常每一条越弱。建议只要 1–3 条 takeaway。这样能逼它做优先级排序，输出也会更可信，更适合直接用于 PR 备注、retrospective 或带教场景。

告诉 skill 你想要哪一类 lesson

你可以给分析加一个明确视角，例如：

• maintainability lesson
• refactoring lesson
• bug-fix lesson
• design trade-off lesson
• 与代码变更相关的 team process lesson

这样能提升相关性，同时又不会违背这个 skill 原本的工作方式。

第一版太泛时，用第二轮修正，不要立刻推倒重来

如果第一次结果比较空泛，不要马上从头重跑。更高效的做法是直接追加要求：

• “Tie each lesson to a specific file or diff hunk.”
• “Replace general advice with what this branch actually demonstrates.”
• “Name the principle only if the code evidence clearly supports it.”
• “Drop any lesson that is not visible in the diff.”

相比重新写一大段宽泛提示词，这种二次收紧通常更快把输出拉到可用水平。

留意这些常见的 lesson-learned 失败模式

典型的弱输出通常有这些表现：

• 提到了原则，但没有代码证据
• 一个 diff 硬拆出太多 lesson
• 把 code review 里的 defect 和 learning takeaway 混为一谈
• 语言偏说教，而不是讨论实际 trade-off
• 试图把互不相关的改动强行总结成一条 lesson

越早识别这些问题，后续迭代就越容易。

团队重复使用 lesson-learned 的最佳改进路径

如果团队打算长期使用 lesson-learned，最好的做法是把提示词模板标准化，至少固定这些要素：

• scope rule
• comparison target
• maximum number of lessons
• required evidence format
• optional anti-pattern check

这样可以显著减少不同人、不同 PR 之间的风格漂移，让 lesson-learned skill 在 PR 和复盘里都更稳定、更可靠。