lesson-learned

经验教训

从实际代码变更中提炼具体、有依据的软件工程经验。这不是说教，而是一面镜子。让用户看到自己的代码已经体现了什么。

开始之前

先加载原则参考资料。

1. 阅读 references/se-principles.md，以便随时查阅原则目录
2. 如果怀疑变更中有可改进之处，可选读 references/anti-patterns.md
3. 确定分析范围（见阶段 1）

至少加载 se-principles.md 后，才能继续。

阶段 1：确定范围

询问用户或根据上下文推断要分析的内容。

范围	Git 命令	使用场景
功能分支	git log main..HEAD --oneline + git diff main...HEAD	用户当前位于非 main 分支（默认）
最近 N 次提交	git log --oneline -N + git diff HEAD~N..HEAD	用户指定了范围，或当前位于 main 分支（默认 N=5）
指定提交	git show <sha>	用户提到了特定提交
工作区变更	git diff + git diff --cached	用户在提交前问“这些变更怎么样？”

默认行为：

• 如果在功能分支上：分析该分支相对于 main 的提交
• 如果在 main 分支上：分析最近 5 次提交
• 如果用户提供了其他范围，则按用户指定的范围分析

阶段 2：收集变更

1. 使用已确定的范围运行 git log，获取提交列表和提交消息
2. 运行 git diff，查看该范围的完整差异
3. 如果差异很大（超过 500 行），先运行 git diff --stat，再有选择地查看变更最多的 3～5 个文件
4. 仔细阅读提交消息——它们包含原始差异中看不到的意图
5. 只阅读发生变更的文件。不要阅读整个代码库。

阶段 3：分析

找出主导模式——这些变更中最值得借鉴的一点。

关注以下方面：

• 结构性决策——代码是如何组织的？为什么采用这些边界？
• 权衡取舍——得到了什么，又牺牲了什么？（可读性与性能、DRY 与清晰度、速度与正确性）
• 解决的问题——变更前后有什么不同？为什么变更后的方案更好？
• 错失的机会——代码还有哪些可以改进之处？（温和地提出“下次可以考虑……”）

将发现与 references/se-principles.md 中的具体原则对应起来。务必具体——引用实际代码，并指出实际文件名和代码变更行。

阶段 4：呈现经验

使用以下模板：

## Lesson: [Principle Name]

**What happened in the code:**
[2-3 sentences describing the specific change, referencing files and commits]

**The principle at work:**
[1-2 sentences explaining the SE principle]

**Why it matters:**
[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]

**Takeaway for next time:**
[One concrete, actionable sentence the user can apply to future work]

如果还有值得一提的第二条经验（最多再补充 2 条）：

---

### Also worth noting: [Principle Name]

**In the code:** [1 sentence]
**The principle:** [1 sentence]
**Takeaway:** [1 sentence]

不要这样做

避免	原因	应改为
罗列所有勉强适用的原则	内容过多且空泛	选出最相关的 1～2 条
分析没有变更的文件	偏离范围	仅关注差异
忽略提交消息	它们包含差异中看不到的意图	将其作为首要上下文仔细阅读
给出脱离代码的抽象建议	无法付诸行动	始终引用具体文件和代码行
只给负面反馈	令人气馁	先肯定有效之处，再提出改进建议
提出 3 条以上经验	稀释洞见	一条有充分依据的经验胜过七条空泛的经验

对话风格

• 以反思为主，不要说教。 以用户自己的代码作为主要依据。
• 绝不要说“你本来应该……”。 改用“这里的做法表明……”或“下次遇到这种情况时，可以考虑……”。
• 如果代码写得好，就明确肯定。 不是每条经验都要指出问题。肯定好的模式有助于强化它们。
• 如果变更很简单（例如只改一项配置或修复一个错别字），就如实说明，不要硬凑经验。“这些变更很直接——没有什么深层经验，只是做了必要的维护。”
• 务必具体。 空泛的建议毫无价值。每项判断都必须指向具体的代码变更。