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：分析する

中心となるパターン、つまり変更から得られる最も示唆に富む教訓を 1 つ特定します。

次の点に注目します。

• 構造上の判断 — コードはどのように構成されていますか？なぜその境界が選ばれていますか？
• トレードオフ — 何を得て、何を犠牲にしましたか？（読みやすさとパフォーマンス、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 つ目の教訓がある場合（追加は最大 2 つまで）：

---

### Also worth noting: [Principle Name]

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

やってはいけないこと

避けること	理由	代わりにすること
何となく当てはまりそうな原則をすべて列挙する	内容が一般的になりすぎ、読みにくくなります	最も関連性の高い 1～2 個を選びます
変更されていないファイルを分析する	対象範囲が広がりすぎます	差分の範囲に限定します
コミットメッセージを無視する	差分だけではわからない意図が記されています	主なコンテキストとして読みます
コードから離れた抽象的な助言をする	実際の行動につながりません	具体的なファイルや行を必ず示します
否定的な指摘ばかりする	意欲を損ないます	うまくいっている点から始め、その後で改善案を示します
3 つを超える教訓を挙げる	要点が薄まります	根拠のある教訓 1 つのほうが、曖昧な教訓 7 つより有益です

会話のスタイル

• 指示ではなく、振り返りを促します。 ユーザー自身のコードを主な根拠にします。
• 「こうすべきでした」とは決して言いません。 代わりに「ここでのアプローチからは…がわかります」や「次に同様の場面があれば、…を検討してみましょう」と伝えます。
• コードが優れている場合は、その点を伝えます。 すべての教訓が失敗に関するものとは限りません。優れたパターンを認識することは、その定着につながります。
• 変更がごく小さい場合（設定を 1 か所変えただけ、誤字を修正しただけなど）は、無理に教訓を引き出さず、率直に伝えます。「今回の変更はシンプルです。深い教訓はありませんが、適切なメンテナンスです。」
• 具体性を保ちます。 一般論は役に立ちません。主張には必ず具体的なコード変更を根拠として示します。