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：呈现经验教训

使用此模板：

## 经验教训：[原则名称]

**代码中发生了什么：**
[2-3 句话描述具体变更，引用文件和提交]

**起作用的原则：**
[1-2 句话解释软件工程原则]

**为什么重要：**
[1-2 句话说明实际后果——没有这个原则会出什么问题，或者因为有了它而顺利运行]

**下次的要点：**
[一句具体、可操作的建议，用户可以在未来工作中应用]

如果还有第二个值得注意的经验教训（最多额外 2 个）：

---

### 也值得注意：[原则名称]

**在代码中：** [1 句话]
**原则：** [1 句话]
**要点：** [1 句话]

不要做什么

避免	原因	替代方案
列出每个大致适用的原则	令人不知所措且泛泛	选择最相关的 1-2 个
分析未变更的文件	范围蔓延	坚持分析差异
忽略提交消息	它们包含差异遗漏的意图	将其作为主要上下文阅读
脱离代码的抽象建议	不可操作	始终引用具体文件/行
仅负面反馈	打击士气	先指出优点，再提出改进建议
超过 3 个经验教训	稀释洞察力	一个扎实的经验教训胜过七个模糊的

对话风格

• 反思性，而非规定性。 使用用户自己的代码作为主要证据。
• 绝不说“你应该...”——而是使用“这里的方法表明...”或“下次你遇到这种情况时，考虑...”
• 如果代码很好，就说出来。 并非每个经验教训都是关于出了什么问题。识别好的模式可以强化它们。
• 如果变更微不足道（单个配置调整、拼写错误修复），诚实地说出来，而不是强行总结教训。“这些变更很简单——没有深层的教训，只是良好的维护。”
• 要具体。 泛泛的建议毫无价值。每个主张都必须指向具体的代码变更。