lessons-learned

学んだ教訓

このスキルを使って、軽量なプロジェクトメモリのループを維持します。

このファイルを、教訓メモリの動作に関する唯一の信頼できる情報源として扱います。 対象となるのは、トリガーのルール、想起フロー、記録フロー、制限、検証です。 README.md、references/、フェーズ開始コマンドで、これらのルールを上書きしてはいけません。

トリガーの契約

次のタイミングでこのスキルを呼び出します。

• タスク開始時：実装の前に想起を実行します。
• タスク中：ユーザーがアプローチを修正したときに記録を実行します。
• タスク終了時：記録の基準を評価し、該当する教訓を自動記録します。

次の場合はトリガーしません。

• 再利用可能なプロセスを伴わない、一度限りの事実確認のQ&A。
• 実行可能なガイダンスを含まない、純粋な概念の説明。
• 技術的な教訓を伴わない、書式のみの編集や事務的な編集。
• 安定した予防ルールを定められない、再現不可能な状況。

最小限の実行ガードレール

このスキルがセッションの主要なプロセススキルである場合：

• 重要な作業（3ステップ以上）では、実装の前にタスクトラッカーを作成します。
• 完了を報告する前に、関連する検証コマンドを実行し、証拠を報告します。
• 仮定や部分的な確認で検証を代替してはいけません。

保存先

すべての教訓アーティファクトを、プロジェクトルートの docs/lessons/ に保存します。

docs/lessons/
├── _index.md
├── api-timeout-retry-pattern.md
├── db-migration-run-order.md
└── null-check-before-save.md

各教訓カードは、Zettelkasten形式の独立したノート1件とします。カード1件につき、再利用可能な教訓を1つだけ記載します。

正規の制限

スキルパッケージ全体で、次の制限を適用します。

• 想起時に読み込む主要カードは 1～3 件です。
• 関連カードは最大 2 件まで読み込みます。
• 読み込むカードの合計は最大 5 件です。
• カード1件あたりの related リンクは 0～2 件です。
• カード1件あたりのタグは 3～6 個です。
• confidence は 0.0-0.9 の両端を含む範囲にします。

他のファイルがこれらの制限と矛盾する場合は、このファイルを優先します。

想起フェーズ

コードを書く前に、このフェーズを実行します。

1. タスクのキーワード（技術、障害モード、ドメイン用語）を抽出します。
2. 教訓の保存先が存在するか確認します。
   • docs/lessons/ が存在しない場合は、初回実行の状態として扱い、想起をスキップします。
   • docs/lessons/ は存在するものの _index.md がない場合は、この想起では既存カードのフロントマターを直接読み取り、次回の記録／更新メンテナンス時に _index.md を再構築する必要があることを警告します。
3. タスクのコンテキストから作業範囲を判断します。
   • 横断的な懸念事項やリポジトリ全体に関する懸念事項には project
   • パッケージ／ディレクトリレベルの懸念事項には module
   • 特定のフローやコンポーネントには feature
4. docs/lessons/_index.md を読み込みます。
5. docs/lessons/ 内のカードから、通常の想起候補を作成します。
   • confidence: 0.0 を明示的に設定しているカードのみを除外します。
   • confidence がないカードは引き続き候補とし、レガシーのフォールバックを適用します。
   • confidence: 0.0 のカードも、明示的に過去の記録を参照するために docs/lessons/ に残します。
   • 通常の想起から除外されたカードを読み込むのは、ユーザーがそのカードの確認を明示的に求めた場合のみです。
6. 次の順序で候補をランク付けします。 タグの一致 -> スコープの一致 -> confidence（降順） -> 日付（降順）
   • レガシーのフォールバックは、confidence がない場合にのみ適用します。source に基づいて値を導出します（user-correction=0.7、bug-fix=0.5、retrospective=0.3）。両方ともない場合は 0.3 を使用します。
7. 主要カードを 1～3 件読み込みます。
8. 主要カードの related リンクをたどり、追加のカードを最大 2 件読み込みます。
9. 厳格な上限を適用します。主要カードと関連カードの合計は 5 件を超えてはいけません。
10. 読み込んだ教訓を現在の作業の制約として適用し、読み込んだカードIDを簡潔に示します。
11. 想起では confidence を読み取り専用として扱います。
    • 教訓を読み込んだことを理由に confidence を変更してはいけません。
    • 教訓を読み込まなかったことを理由に confidence を変更してはいけません。
    • 最近使用していないことを理由に confidence を変更してはいけません。

該当するカードがない場合は、教訓による制約を設けずに作業を続けます。

リコールに関する警告

これらは処理を妨げるものではないため、そのまま続行してください。

• 初回実行時には docs/lessons/ がありません。
• _index.md がないため、このリコール処理ではカードのメタデータを直接使用しました。
• 読み込んだカードに confidence がないため、レガシー形式にフォールバックする必要があります。
• related の参照先がありません。

キャプチャフェーズ

次のいずれかに該当する場合は、このフェーズを実行してください。

• ユーザーがあなたの対応を修正した
• ユーザーがキャプチャを依頼した
• バグ修正によって再利用可能なパターンが明らかになった
• タスクの完了によって、明白ではない再利用可能な知見が得られた

次の2種類のメモリメンテナンスの両方に、このフェーズを使用してください。

• 現在の作業で再利用可能な新しい教訓が得られた場合に、新しいレッスンカードを作成する
• 現在の作業から、想起されたカードまたは関連カードが以前ほど適用できなくなった、一部古くなった、あるいは有効でなくなったことがわかった場合に、既存のレッスンカードを更新する

ステップ 1 — キャプチャするかどうかを判断する

次の問いを検討してください。「この教訓は、次に同様のタスクが発生したときに時間を節約できるか？」

次の2つの判断について、それぞれこのステップを適用してください。

• 新しいレッスンカードを作成するかどうか
• 既存のレッスンカードを更新するかどうか

新しいカードの作成を見送っても、既存カードの修正更新を見送ることにはなりません。 現在の作業から、想起されたカードまたは関連カードに修正が必要だとわかった場合は、新しいレッスンをキャプチャしない場合でも、既存カードについてステップ 2 に進んでください。

明白ではない知見だけをキャプチャしてください。次のような教訓を優先してください。

• ファイル／モジュール間に隠れている関係。
• コード構造から想定されるものとは異なる実行経路。
• 見落としやすい設定、環境変数、フラグ、順序の制約。
• エラーメッセージが誤解を招いたことで得られた突破口。
• ツール／API の癖と、必要な回避策。
• 近くに記載されていないビルド／テストコマンドや運用上の前提条件。
• 正しく動作させるために一緒に変更する必要があるファイル。

次の場合はキャプチャしてください。

• ✅ 再利用可能なパターンまたは判断基準
• ✅ 明確な予防策のある、コストのかかるミス
• ✅ 忘れやすい重要なパラメーター、設定、前提条件
• ✅ 複数回の試行を経た解決策（失敗の理由と成功条件を含める）

次の場合は既存カードを更新してください。

• ✅ 現在の作業から、想起されたカードまたは関連カードが以前ほど適用できなくなったことがわかった
• ✅ 現在の作業から、想起されたカードまたは関連カードが一部古くなったことがわかった
• ✅ 現在の作業から、想起されたカードまたは関連カードを通常の想起対象から外すべきだとわかった

次の場合はスキップしてください。

• ❌ 再利用可能なプロセスのない、一度限りの質疑応答
• ❌ 実行可能な指針を伴わない、単なる概念の説明
• ❌ 再現できない、特定の状況に限られた結論
• ❌ 隠れた制約のない、明白なフレームワーク／言語の動作
• ❌ 繰り返される可能性が低い、セッション固有のメモ

これらのスキップ規則は、新しいカードの作成に適用されます。現在の証拠から既存カードを書き換えるべき、またはその confidence を変更すべきだとわかった場合、その修正更新を妨げるものではありません。

ステップ 2 — Zettel カードを作成する

新しいカードを作成するときは、レッスンの内容を示す意味的なケバブケースの ID を生成します（例：api-timeout-retry-pattern）。

カードを書き込む前、または更新する前に、意味的に類似する既存のカードがないか確認し、 判断を明示します。

• 類似するカードがなく、新しいレッスンを記録する場合は decision=create とします。
• 類似するカードが同じレッスンをすでに扱っている場合、または現在の作業で既存のカードを修正する場合は decision=update とします。

1 回の記録処理で影響を受けるカードすべての結果の種類が同じ場合に限り、 decision=create または decision=update を使用します。1 回の記録処理でカードの作成と更新の両方を行う場合は、 created=<n> と updated=<n> の件数のみを報告します。

1 回の記録処理で複数のカードに影響する場合は、created=<n> と updated=<n> の件数を報告します。1 回の記録処理でカードの作成と更新の両方を行う場合は、 decision= を含めないでください。

カードを書く前に scope を割り当てます。

• リポジトリ全体に適用される制約には project
• パッケージ／ディレクトリ単位の制約には module
• 1 つのフロー／コンポーネントには feature

source に基づいて初期 confidence を割り当てます。

• user-correction：0.7
• bug-fix：0.5
• retrospective：0.3

confidence は記録／更新時にのみ変更し、想起時には変更しません。

ユーザーがレッスンが今も有用だと明示的に確認した場合は、confidence を +0.1 増やします（上限は 0.9）。

後から得られた証拠によりレッスンの適用可能性が低いと分かった場合は、 confidence を -0.1 減らします。

レッスンの一部が古くなっている場合は、まずカードの内容を更新し、 必要な場合にのみ confidence を減らします。

通常の想起にカードを含める必要がなくなった場合に限り、confidence を直接 0.0 に設定します。

最近そのレッスンが使われていないという理由だけで、confidence を減らさないでください。

テンプレート references/card-template.md を使用して、 カードを docs/lessons/<id>.md に書き込みます。

新しいカードを作成する前に、意味的な重複がないか確認します。

• 既存のカードが意味的に類似している場合は、重複カードを作成するのではなく、そのカードを更新します。
• 更新時は既存のカード ID を保持します。

現在の作業によって想起済みまたは関連するカードの妥当性が弱まる場合：

• 新しいレッスンカードを作成しない場合でも、既存のカードを更新します
• レッスンが一部だけ古くなっている場合は、まずカードの内容を更新します
• その後、レッスンの標準的な適用可能性が以前より弱くなった場合に限り、confidence を下げます
• 通常の想起にカードを含める必要がなくなった場合に限り、confidence を 0.0 に設定します

最小限の修正記録の例：

Lessons capture report: decision=update, updated=1 (db-migration-run-order), confidence=0.7->0.6 (現在の設定では適用可能性が低下), skipped=0

カードのフィールド：

フィールド	目的
id	意味を表すケバブケースのスラッグ。ファイル名にも使用します
date	レッスンを記録した ISO 形式の日付
scope	適用範囲：project / module / feature
tags	想起時の照合に使う 3～6 個の小文字タグ
source	user-correction / bug-fix / retrospective
confidence	想起時の順位付けに使う数値の確信度スコア
related	[[card-id]] 形式で参照する、関連性の高いレッスン 0～2 件
タイトル	レッスンの 1 行要約
コンテキスト	間違いが起きたときの状況
間違い	何がうまくいかなかったか
レッスン	抽出したルールまたはベストプラクティス
適用する場面	このレッスンが役立つ今後の状況

タスク終了時の動作：

• 記録条件を満たしている場合は、事前に許可を求めず自動的に記録します。
• 記録後、作成または更新した内容を報告します。
• 通常のユーザー向け出力では、短い記録の概要を優先します。
• ユーザーから確認を求められない限り、カードの本文全体を再掲しないでください。

ステップ 3 — インデックスを更新する

カード ID ごとに 1 行を docs/lessons/_index.md に追加または更新します。

_index.md が存在しない場合は、次の構成で作成します。

# Lessons Index

> Auto-generated by lessons-learned skill. Do not edit manually.

| Card | Scope | Tags | Date |
|---|---|---|---|

その後、行を Date の降順（新しいものが先）に並べます。

ステップ 4 — ユーザーに確認する

次のような簡潔なレポートで、記録した内容をユーザーに伝えます。

Lessons capture report: created=1 (api-timeout-retry-pattern), updated=1 (db-migration-run-order), skipped=1 (明らかな動作)

影響を受けたカードがすべて同じ結果の場合は、レポートに decision=create または decision=update を含めます。1 回の記録処理でカードの作成と更新の両方が行われた場合は、 created=<n> と updated=<n> の件数のみを報告します。

記録または更新によって信頼度が変化した場合は、影響を受けた各カードの信頼度の遷移 old->new と簡潔な理由を含めます。

新規カードの場合は、none-><value> を使用します。

遷移後に 0.0 となる場合は、そのカードが通常の想起対象から除外されることを明示します。

例：

• Lessons capture report: decision=create, created=1 (\api-timeout-retry-pattern`), confidence=none->0.5 (再利用可能な新しいパターン)`
• Lessons capture report: decision=update, updated=1 (\db-migration-run-order`), confidence=0.7->0.6 (現在の設定では適用可能性が低下)`
• Lessons capture report: decision=update, updated=1 (\legacy-bootstrap-flow`), confidence=0.1->0.0 (通常の想起対象から除外)`

確認は簡潔にします。decision、影響を受けたカード ID、1 行のルール概要を優先します。 通常の出力では、Markdown カード全体やインデックスの内容をそのまま大量に出力しないでください。

リンクのルール

価値の高いカードにのみ related リンクを使用します。

次の 4 条件のうち少なくとも 2 つに当てはまる場合に、related リンクを作成します。

1. 異なるタスクで再利用できます。
2. コストの高い失敗を表します（複数回の試行、または大幅な時間の損失）。
3. 重要なパラメーター、設定、判断の詳細に依存します。
4. 既存の少なくとも 2 つのレッスンカードと自然につながります。

リンクの制約：

• カードごとに related リンクを 0～2 個追加します。関連性が強い場合に限ります。
• references/linking-heuristics.md に従い、決定的な順位付けを使用します。
• 関連性が弱いリンクや推測に基づくリンクは追加しないでください。

リンク切れの related ターゲットは処理を妨げません。

• related ターゲットが見つからない場合は無視し、警告します。
• 想起／記録の処理を続行します。

アンチパターン

• 隠れた制約のない、明らかな言語／フレームワークの動作を記録する。
• セッション限定のメモ（一時的なログ、その場限りのローカルパス、単発の環境ノイズ）を記録する。
• 実行可能な予防ルールのない、冗長な説明カードを書く。
• 既存カードの更新で十分な場合に、ほぼ重複するカードを作成する。
• When to Apply に具体的なきっかけを示さず、一般的な助言を記録する。

検証

記録または更新の際は、次のチェックを適用します。別の箇所で警告として明示されている場合を除き、これらのチェックへの不適合は処理を妨げるエラーです。

• カードのファイル名が id のスラッグと一致している。
• date の形式が ISO YYYY-MM-DD である。
• scope が project、module、feature のいずれかである。
• tags の数が 3～6 個である。
• source が有効な列挙値である。
• confidence が数値で、範囲が 0.0-0.9 である。
• related の数が 0～2 個で、すべてのターゲットが既存のカードに解決される。
• インデックスに行が存在し、scope を含むカードのメタデータと一致している。
• _index.md の行が Date の降順（新しいものが先）に並んでいる。

統合ガイド

同じセッションで他のスキルと併用する場合は、唯一の信頼できる情報源としてトリガー契約に従います。

• タスク開始 -> 想起
• 作業中のユーザーによる修正 -> 記録
• タスク終了 -> 記録の評価

これは置き換え不可のステップです。レッスンの記録を、todo トラッカー、進捗ファイル、その他のスキルの成果物で代替することはできません。