lesson-learned

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lesson Learned

经验总结

Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.

从实际代码变更中提取具体、贴合场景的软件工程经验。这不是说教，而是镜像呈现——向用户展示他们的代码已经体现出的实践。

Before You Begin

开始之前

Load the principles reference first.

Read
```
references/se-principles.md
```
to have the principle catalog available
Optionally read
```
references/anti-patterns.md
```
if you suspect the changes include areas for improvement
Determine the scope of analysis (see Phase 1)

Do not proceed until you've loaded at least
se-principles.md
.

请先加载原则参考文档。

阅读
```
references/se-principles.md
```
以获取原则目录
若怀疑变更中存在可改进的地方，可选择性阅读
```
references/anti-patterns.md
```
确定分析范围（详见第一阶段）

在至少加载
se-principles.md
之前，请勿继续。

Phase 1: Determine Scope

第一阶段：确定分析范围

Ask the user or infer from context what to analyze.

Scope	Git Commands	When to Use
Feature branch	`git log main..HEAD --oneline` + `git diff main...HEAD`	User is on a non-main branch (default)
Last N commits	`git log --oneline -N` + `git diff HEAD~N..HEAD`	User specifies a range, or on main (default N=5)
Specific commit	`git show <sha>`	User references a specific commit
Working changes	`git diff` + `git diff --cached`	User says "what about these changes?" before committing

Default behavior:

If on a feature branch: analyze branch commits vs main
If on main: analyze the last 5 commits
If the user provides a different scope, use that

询问用户或根据上下文推断分析对象。

范围	Git命令	适用场景
功能分支	`git log main..HEAD --oneline` + `git diff main...HEAD`	用户处于非主分支（默认情况）
最近N次提交	`git log --oneline -N` + `git diff HEAD~N..HEAD`	用户指定了范围，或处于主分支（默认N=5）
特定提交	`git show <sha>`	用户提及了特定提交
本地未提交变更	`git diff` + `git diff --cached`	用户询问“这些变更怎么样？”且尚未提交时

默认行为：

若处于功能分支：分析分支提交与主分支的差异
若处于主分支：分析最近5次提交
若用户指定了其他范围，则使用该范围

Phase 2: Gather Changes

第二阶段：收集变更信息

Run
```
git log
```
with the determined scope to get the commit list and messages
Run
```
git diff
```
for the full diff of the scope
If the diff is large (>500 lines), use
```
git diff --stat
```
first, then selectively read the top 3-5 most-changed files
Read commit messages carefully -- they contain intent that raw diffs miss
Only read changed files. Do not read the entire repo.

运行对应范围的
```
git log
```
命令，获取提交列表和提交信息
运行
```
git diff
```
命令获取该范围的完整差异内容
若差异内容过大（超过500行），先使用
```
git diff --stat
```
查看统计信息，再选择性阅读变更最多的3-5个文件
仔细阅读提交信息——其中包含了原始差异无法体现的意图
仅阅读有变更的文件，不要遍历整个仓库

Phase 3: Analyze

第三阶段：分析过程

Identify the dominant pattern -- the single most instructive thing about these changes.

Look for:

Structural decisions -- How was the code organized? Why those boundaries?
Trade-offs made -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness)
Problems solved -- What was the before/after? What made the "after" better?
Missed opportunities -- Where could the code improve? (present gently as "next time, consider...")

Map findings to specific principles from

references/se-principles.md

. Be specific -- quote actual code, reference actual file names and line changes.

识别核心模式——即这些变更最具指导意义的一点。

重点关注：

结构决策——代码是如何组织的？为何设置这些边界？
做出的权衡——得到了什么，又牺牲了什么？（可读性vs性能、DRY原则vs代码清晰度、开发速度vs正确性）
解决的问题——变更前后有何不同？“变更后”好在哪里？
错失的机会——代码还有哪些可改进的地方？（以温和的方式提出，比如“下次可以考虑...”）

将分析结果与

references/se-principles.md

中的具体原则对应起来。要具体——引用实际代码、提及具体文件名和行号变更。

Phase 4: Present the Lesson

第四阶段：呈现经验总结

Use this template:

markdown

undefined

使用以下模板：

markdown

undefined

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]


If there is a second lesson worth noting (maximum 2 additional):

```markdown
---

代码中的具体表现： [2-3句话描述具体变更，提及相关文件和提交]

背后的软件工程原则： [1-2句话解释该软件工程原则]

重要性： [1-2句话说明实际影响——没有这个做法会出什么问题，或者这么做带来了什么好处]

后续实践建议： [一句具体、可落地的句子，用户可将其应用到未来工作中]


若还有第二个值得提及的经验（最多额外2个）：

```markdown
---

Also worth noting: [Principle Name]

补充经验：[原则名称]

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

undefined

代码表现： [1句话] 对应原则： [1句话] 实践建议： [1句话]

undefined

What NOT to Do

禁忌事项

Avoid	Why	Instead
Listing every principle that vaguely applies	Overwhelming and generic	Pick the 1-2 most relevant
Analyzing files that were not changed	Scope creep	Stick to the diff
Ignoring commit messages	They contain intent that diffs miss	Read them as primary context
Abstract advice disconnected from the code	Not actionable	Always reference specific files/lines
Negative-only feedback	Demoralizing	Lead with what works, then suggest improvements
More than 3 lessons	Dilutes the insight	One well-grounded lesson beats seven vague ones

需避免的行为	原因	正确做法
罗列所有沾边的原则	过于冗余且空泛	选择1-2个最相关的原则
分析未发生变更的文件	超出分析范围	仅关注差异内容
忽略提交信息	其中包含了差异无法体现的意图	将提交信息作为主要上下文来阅读
给出脱离代码的抽象建议	不具备可操作性	始终引用具体文件/行号
只给出负面反馈	打击积极性	先肯定做得好的地方，再提出改进建议
总结超过3条经验	分散核心观点	一个有扎实依据的经验胜过七个空泛的结论

Conversation Style

沟通风格

Reflective, not prescriptive. Use the user's own code as primary evidence.
Never say "you should have..." -- instead use "the approach here shows..." or "next time you face this, consider..."
If the code is good, say so. Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
If the changes are trivial (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
Be specific. Generic advice is worthless. Every claim must point to a concrete code change.

侧重反思，而非指令。 将用户自己的代码作为主要依据。
永远不要说“你本应该...”——而是用“此处的方法体现了...”或“下次遇到类似情况，可以考虑...”
如果代码写得好，要明确肯定。 并非所有经验都是关于错误的，认可好的模式能强化正确实践。
如果变更非常琐碎（比如单一配置调整、拼写错误修复），要如实告知，而非强行总结经验。可以说：“这些变更很直接——没有深层经验可总结，只是良好的代码维护。”
要具体。 空泛的建议毫无价值，所有结论都必须指向具体的代码变更。