lesson-learned

lesson-learned skill の概要

lesson-learned skill は、直近の Git アクティビティを具体的なソフトウェアエンジニアリング上の学びに変換するための skill です。抽象的な助言を返すのではなく、実際の diff、コミット履歴、変更ファイルを確認し、その変更が SRP、DRY、KISS、YAGNI といった原則や関連するアンチパターンのどれに当てはまるのかを整理します。
そのため lesson-learned skill が最も力を発揮するのは、すでにコードを変更した開発者が「今回の作業から何を学べたのか」「どんなトレードオフを取ったのか」「次回も繰り返すべきこと、避けるべきことは何か」を振り返りたい場面です。

lesson-learned skill が向いている人

特に相性が良いのは、次のような人です。

• 機能追加、リファクタリング、バグ修正、コード整理を終えた開発者
• PR 後に学び重視のサマリーを作りたいレビュアー
• 軽量なエンジニアリング振り返りの習慣をチームに根づかせたいチームリード
• 直近のコード変更の背景にある原則を説明する必要があるエージェント

実際のリポジトリ履歴に根ざした設計上の振り返りをしたいなら、単なる “review this code” の汎用プロンプトよりも lesson-learned skill の方が適しています。

lesson-learned skill が実際に担う役割

この skill の中核は、一般的な意味での合否判定型コードレビューではありません。lesson-learned は、完了済みまたは進行中の作業を振り返り、diff に裏付けられた 1〜3 個の学びを抽出します。良い出力には通常、次の要素が入ります。

• 原則の名前
• その変更がどう原則を体現しているか
• それがなぜ重要か
• 次に取るべきアクション

この枠組みにより、振り返り、メンタリング、PR 用の学習メモに特に使いやすくなっています。

lesson-learned と汎用プロンプトの違い

重要なのは主に 2 点です。

1. Git 履歴を起点にするため、仮のコード断片ではなく実際の変更を分析すること
2. 原則カタログ、とくに references/se-principles.md を前提にしており、パターンを一貫した語彙で名付けられること

この組み合わせによって、ソフトウェア工学の教科書から貼り付けたような一般論ではなく、コードの変更から自然に導かれた学びとして出力しやすくなります。

lesson-learned を選ばないほうがよいケース

実際にやりたいことが次のいずれかなら、lesson-learned は見送ったほうがよいです。

• マージ前の行単位のバグ検出
• セキュリティ監査
• スタイルだけに関する lint フィードバック
• まだコード変更がない段階でのアーキテクチャ設計
• スコープが定まっていない巨大コードベースのレビュー

こうしたケースでは、まずコードレビュー系、セキュリティ系、設計系の skill を使う方が適切です。

lesson-learned skill の使い方

lesson-learned のインストール前提

リポジトリの skills/lesson-learned/SKILL.md には専用のインストールコマンドは記載されていません。そのため、インストール方法は softaworks/agent-toolkit から skill をどう読み込む環境かに依存します。環境がそのリポジトリから skill を追加できるなら、一般的なパターンは次のとおりです。

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

エージェントがリポジトリから直接 skill を読み込む場合は、次の 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 のような比較対象ブランチ
• コミット範囲、コミット SHA、ブランチ間 diff、または working tree diff
• 変更量の大きいファイルを確認できるだけの十分なファイル文脈

Git の文脈がないと、出力はすぐに一般論へ寄ってしまいます。

まず分析スコープを正しく決める

この skill の品質は、どの範囲を渡すかでほぼ決まります。リポジトリ側でも実用的なデフォルトが定義されています。

• feature branch: ブランチの作業内容を main と比較
• main branch: 直近 5 コミットを分析
• specific commit: 単一の SHA を確認
• working changes: unstaged と staged の diff を確認

良い lesson-learned guide は、この選択を早い段階で必ず確定させます。スコープが曖昧なままだと、無関係な学びが混ざりやすくなります。

lesson-learned usage に役立つ 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 に説明させたい変更のストーリーに合うものを選べば十分です。

曖昧な依頼を強いプロンプトに変える

弱いプロンプト:

“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 は、通常のレビューの代替ではなく、その後段に置く振り返りレイヤーとして使うのが最適です。実用的なプロンプトは次のようになります。

“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.”

これは、単に差し戻すだけでなく、学びのあるレビューコメントを作りたいときに有効です。

依頼しておくとよい出力フォーマット

次のような簡潔な構造を指定すると使いやすくなります。

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

この形はリポジトリの意図にも合っており、ありがちな冗長な一般論も減らせます。

大きな diff を扱うときのコツ

大規模な PR では、skill に「全部を分析して」と頼まないでください。代わりに次のように進めます。

• 変更量の大きいファイルを特定する
• 変更をテーマごとにまとめる
• 明らかな機械的修正は無視する
• 学びは 1〜3 個に絞る

この skill は、すべてのファイル変更を網羅的に列挙するより、パターンを抜き出す方が得意です。

時間を節約できる定番ワークフロー

安定して使いやすい流れは次のとおりです。

1. se-principles.md を読み込む
2. スコープを決める
3. Git log と diff を確認する
4. 変更量の大きいファイルを読む
5. 必要なら anti-patterns.md も読み込む
6. 根拠付きで 1〜3 個の学びを生成する
7. 結果が広すぎる、または説教くさすぎる場合は絞り込む

この順序が重要なのは、原則カタログを先に入れることで、分析に使う語彙が強化されるためです。

lesson-learned skill の FAQ

lesson-learned は初心者にも向いていますか？

はい。初心者でも、分析対象となる実際の変更があれば有効です。自分が今まさに行った作業を通して原則を説明してくれるため、先に理論だけを読むより理解しやすいことが多いです。反対に、リポジトリへアクセスできない場合や直近の diff がない場合は有用性が下がります。

lesson-learned はコードレビューと同じですか？

いいえ。lesson-learned は振り返り志向で、原則ベースです。一方、コードレビューは通常、正しさ、リスク、保守性に重点が置かれます。重なる部分はありますが、目指す出力は異なります。

lesson-learned skill には Git アクセスが必要ですか？

強い結果を求めるなら必要です。このリポジトリは Git 履歴と diff を前提に設計されています。コード断片だけを貼り付けても原則に関するコメントはできますが、それはもはやこの skill の最も強い使い方ではありません。

lesson-learned が普通のプロンプトより優れている点は何ですか？

強みは構造にあります。明示的なスコープ選定、必須の原則リファレンス、そして学びを具体的なコード上のシグナルに結びつけるワークフローです。普通のプロンプトは、すぐに一般的な “best practices” へ飛びがちです。

コミット前の変更にも lesson-learned は使えますか？

はい。git diff と git diff --cached によって、未コミットの変更にも対応できます。これは、コミット前に「これから出荷する変更の学びやトレードオフは何か」を整理したいときに役立ちます。

lesson-learned が向かないのはどんなときですか？

次のような場合は適合しません。

• 意味のある直近の変更が存在しない
• diff の大半が生成物やフォーマット修正ノイズである
• 振り返りよりも不具合の切り分けが必要
• 1 つのブランチに無関係な作業が多数混在している

その場合は、まずスコープを狭めるか、別の skill を先に使うのが現実的です。

lesson-learned skill を改善するには

lesson-learned にはもっと狭いストーリーを渡す

品質を最も左右するのはスコープです。“My last month of work” では広すぎます。“This refactor that split API calls from UI rendering” のように絞った方がよいです。範囲が狭いほど、原則は鋭くなり、根拠も強くなります。

毎回 principles リファレンスを読み込む

この点について、リポジトリはかなり明確です。分析前に references/se-principles.md を読み込むべきです。省略しても何らかの所見は出ますが、パターンのラベル付けの一貫性や、広く認知された原則との接続は弱くなりがちです。

anti-patterns はネガティブ目的ではなくバランス取りに使う

references/anti-patterns.md が特に役立つのは、diff に散発的な編集、過剰な抽象化、肥大化する “god” module などのリスクシグナルがあるときです。結果が懲罰的に聞こえないよう、やわらかい表現で返すよう依頼すると実用性が上がります。

変更ファイルにひもづく証拠を求める

よくある失敗は、根拠のない高レベルな助言です。lesson-learned の出力を改善したいなら、次を明示的に求めてください。

• 関係する変更ファイル
• どんな構造的変更が起きたか
• そこから読み取れるトレードオフ
• なぜそれが特定の原則に対応するのか

本当の学びと一般論の違いは、証拠があるかどうかです。

学びの数を絞る

学びを増やすほど、1 つ 1 つは弱くなりやすいです。求めるのは 1〜3 個に限定してください。そうすることで優先順位が付き、PR メモ、レトロスペクティブ、コーチングでも使いやすく、内容の納得感も高まります。

どの種類の学びが欲しいかを伝える

視点を追加すると、分析を狙いどおりに寄せられます。

• maintainability lesson
• refactoring lesson
• bug-fix lesson
• design trade-off lesson
• コード変更にひもづく team process lesson

これは skill の意図したワークフローを壊さずに、関連性を高める有効な方法です。

一般的すぎる初稿は 2 回目で補正する

最初の結果が曖昧でも、すぐに最初からやり直す必要はありません。代わりに次のように依頼します。

• “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.”

広く投げ直すより、こうした 2 回目の指示の方が短時間で改善しやすいことが多いです。

lesson-learned の典型的な失敗パターンに注意する

弱い出力には、次のような傾向があります。

• コード上の証拠なしに原則名だけが挙がる
• 1 つの diff から学びを出しすぎる
• コードレビューの欠陥指摘と学びの要約を混同する
• 実務的なトレードオフではなく説教調になる
• 無関係な変更を 1 つの学びとしてまとめようとする

これらを早めに見抜けると、反復調整はかなり楽になります。

チームで継続利用するなら最も効果的な改善策

チームで lesson-learned を継続的に使うなら、次の要素を含むプロンプトテンプレートを標準化するのが有効です。

• スコープの決め方
• 比較対象
• 学びの最大数
• 必須の証拠フォーマット
• 任意のアンチパターン確認

これによりブレが減り、PR やレトロスペクティブ全体で lesson-learned skill の再現性が大きく高まります。