lesson-learned

lesson-learned 技能概覽

lesson-learned skill 會把近期的 Git 活動轉成具體、可落地的軟體工程心得。它不是給你抽象建議，而是實際檢視 diff、commit 歷史與變更檔案，再把這些變化對應到像 SRP、DRY、KISS、YAGNI 這類已命名的原則，以及相關 anti-patterns。也因此，lesson-learned 特別適合已經動手改過程式的開發者，用來回答這些問題：這次改動讓我們學到什麼？做了哪些取捨？下次哪些做法值得延續、哪些該避免？

lesson-learned skill 適合哪些人

最適合的讀者包括：

• 剛完成功能、重構、除錯或清理工作的開發者
• 想在 PR 後補上一份偏學習導向摘要的 reviewer
• 想培養輕量工程反思習慣的 team lead
• 需要解釋近期程式碼變更背後原則的 agents

如果你要的是建立在真實 repository 歷史上的設計反思，lesson-learned skill 會比泛泛的「review 這段程式碼」prompt 更有力。

這個技能實際上在做什麼

它的核心工作，不是一般意義上那種 pass/fail 式 code review。lesson-learned 是回頭檢視已完成或進行中的工作，從 diff 中萃取出 1–3 個有根據的教訓或收穫。好的輸出通常會包含：

• 原則名稱
• 這次變更如何體現該原則
• 為什麼這件事重要
• 下一步建議

這種框架特別適合用在 retrospective、mentoring，以及 PR 學習筆記。

lesson-learned 與一般 prompt 的差異在哪裡

最關鍵的是兩點：

1. 它是以 Git 歷史為驅動，所以分析的是實際發生過的變更，不是假設性的程式片段。
2. 它依賴一份原則目錄，尤其是 references/se-principles.md，讓模型能用一致的詞彙來命名模式與原則。

這個組合能讓 skill 產出的 lesson 更像是從程式碼裡「長出來」的，而不是從軟體工程教科書硬貼上去的結論。

什麼情況不適合選 lesson-learned

如果你的真正目標是以下其中一種，就不建議用 lesson-learned：

• merge 前逐行找 bug
• security audit
• 只看 style 的 lint 回饋
• 還沒有任何程式碼變更時就先做架構規劃
• 在沒有明確範圍的情況下審視一整個大型 codebase

這些情境下，通常先用 code review、security 或 design 類 skill 會更合適。

如何使用 lesson-learned skill

lesson-learned 的安裝情境

repository 並沒有在 skills/lesson-learned/SKILL.md 裡提供專屬安裝指令，所以實際安裝方式會取決於你的環境如何從 softaworks/agent-toolkit 載入 skills。如果你的環境支援從該 repository 加入 skill，常見寫法是：

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

如果你的 agent 是直接從 repo 載入 skills，則使用這個 skill path：

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 歷史的 repository
• 當前 branch 名稱，或像 main 這樣明確的比較目標
• commit 範圍、commit SHA、branch diff，或 working tree diff
• 足夠的檔案脈絡，能檢查變更最多的那些檔案

少了 Git 脈絡，輸出很快就會變得空泛。

先選對分析範圍

這個 skill 的品質，高度取決於你給它的範圍。repository 其實已經定義了實用預設值：

• feature branch：拿 branch 的工作與 main 比較
• main branch：分析最近 5 個 commits
• specific commit：檢查單一 SHA
• working changes：檢查 unstaged 與 staged diffs

一份好的 lesson-learned guide，第一步通常就是先逼自己把範圍定清楚。如果範圍模糊，結果往往會把彼此無關的 lesson 混在一起。

能提升 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

你不需要每次都用到全部指令。挑出最符合你想讓 skill 說明的那段「變更故事」即可。

把模糊請求改寫成有效 prompt

弱的 prompt：

“Reflect on my recent work.”

更強的 prompt：

“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 依賴的 reference file
• 它限制了分析面積
• 它指定了輸出格式

用於 Code Review 的 lesson-learned prompt 模式

lesson-learned for Code Review 最適合當作一般 review 之後的反思層，而不是拿來取代 review。本質上可用這樣的 prompt：

“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

這樣的格式和 repository 原本的設計意圖一致，也比較能避免一堆空泛填充文字。

面對大型 diff 時怎麼處理

如果 PR 很大，不要直接叫這個 skill「分析全部」。更好的做法是：

• 找出變更最多的檔案
• 依主題把改動分群
• 忽略明顯機械式的修改
• 只要求 1–3 個 lessons

這個 skill 最擅長的是抽出模式，不是鉅細靡遺列舉每個檔案的所有變更。

一套省時的常見工作流程

比較穩定可靠的流程如下：

1. 載入 se-principles.md
2. 選定範圍
3. 檢查 Git log 與 diff
4. 閱讀變更最多的檔案
5. 視需要再載入 anti-patterns.md
6. 產出 1–3 個附帶證據的 lessons
7. 如果結果太散或太說教，再做收斂

這個順序很重要，因為原則目錄會讓分析用語更準、更穩。

lesson-learned skill 常見問題

lesson-learned 適合新手嗎？

適合，但前提是新手手上真的有實際變更可分析。這個 skill 會透過他剛做完的工作來解釋原則，通常比先讀理論更容易吸收。反過來說，如果沒有 repo 存取權，或沒有近期 diff，它的幫助就會小很多。

lesson-learned 和 code review 是同一件事嗎？

不是。lesson-learned 是回顧式、偏原則導向的分析；code review 則通常更偏向正確性、風險與可維護性。兩者確實有交集，但最終輸出目標不同。

lesson-learned skill 一定需要 Git 存取嗎？

如果你要的是夠強、夠有根據的結果，答案是要。這個 repository 的設計本來就是圍繞 Git 歷史與 diff。若你只是貼一小段程式碼，模型仍然可以評論原則，但那已經不是這個 skill 最強的使用模式。

lesson-learned 比一般 prompt 好在哪裡？

優勢在於結構完整：它要求明確選範圍、指定必讀的原則參考檔，並透過工作流程把 lessons 綁回具體的程式碼訊號。一般 prompt 很容易直接跳到空泛的「best practices」。

可以把 lesson-learned 用在尚未 commit 的變更上嗎？

可以。這個 skill 支援透過 git diff 和 git diff --cached 分析 working changes。如果你想在 commit 前先弄清楚自己即將交付的內容反映了什麼 lesson 或取捨，這就很有用。

什麼時候 lesson-learned 不是好選擇？

以下情況建議避免：

• 沒有任何有意義的近期變更
• diff 幾乎都是自動產生內容或格式噪音
• 你真正需要的是 defect triage，而不是反思
• 同一個 branch 混了很多彼此無關的工作

這些情況下，先縮小範圍，或先換用其他 skill，通常會比較有效。

如何改善 lesson-learned skill 的使用效果

給 lesson-learned 一個更聚焦的故事

影響品質最大的槓桿就是 scope。「我過去一個月做了什麼」太大了；「這次把 API 呼叫從 UI rendering 拆開的重構」就好很多。範圍越窄，產出的 lesson 原則會越銳利，證據也會更扎實。

每次都先載入 principles reference

這個 repository 在這點上寫得非常明白：分析前應先載入 references/se-principles.md。如果跳過它，模型或許還是會產出一些觀察，但更容易出現原則命名不一致，或無法穩定連回既有工程原則的情況。

用 anti-patterns 保持平衡，不是拿來放大負面

references/anti-patterns.md 最有幫助的時機，是 diff 裡已經出現風險訊號，例如修改過於分散、過度抽象化，或某些「god」模組持續膨脹。可以要求模型用較溫和的措辭，這樣結果才會維持實用，而不是變成責備。

要求證據一定要綁定變更檔案

這個 skill 常見的失敗模式之一，就是講很多高層次建議，卻沒有證據。要改善 lesson-learned 輸出，可以明確要求：

• 涉及哪些變更檔案
• 發生了什麼結構性改動
• 這代表了什麼取捨
• 為什麼它對應到某個特定原則

證據，才是「真實 lesson」和「泛泛評論」的分水嶺。

控制 lesson 的數量

lesson 越多，通常每一則就越弱。建議只要 1–3 個 takeaways。這會迫使模型做優先排序，也讓輸出更可信，更容易直接拿去寫 PR notes、retros 或 coaching 內容。

告訴 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.”

這種二次修正，通常比整段重新 broad re-prompt 更快把品質拉上來。

留意這些常見的 lesson-learned 失敗模式

常見的弱輸出包括：

• 只點原則名稱，卻沒有程式碼證據
• 從同一個 diff 硬拆出太多 lessons
• 把 code review 缺陷和學習型 takeaway 混在一起
• 用說教口吻，取代實際的取捨分析
• 試圖把彼此無關的變更硬總結成同一個 lesson

越早辨認出這些問題，後續迭代就越直接。

團隊重複使用時，最佳改善路徑

如果團隊打算固定使用 lesson-learned，最好的做法是把 prompt template 標準化，至少固定以下欄位：

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

這樣可以降低前後不一致的情況，也能讓 lesson-learned skill 在不同 PR 與 retrospective 裡更穩定可靠。