insight-extraction

インサイト抽出スキル

概要

完了したコーディングセッションを分析し、メモリーシステム向けに構造化された学びを抽出します。インサイトは、今後のセッションでミスを避け、確立されたパターンに従い、コードベースをより早く理解するのに役立ちます。

基本原則： ログではなく、実行可能な知識を抽出します。すべてのインサイトは、今後のセッションで何かをより良く行う助けになるものでなければなりません。

使用するタイミング

必ず使用：

• コーディングタスクの完了後
• バグの修正後
• 新しいパターンの発見後
• 試行が失敗した後（特に重要です）

例外：

• 学びのない些細な変更
• ドキュメントのみの変更

鉄則

NO SESSION END WITHOUT INSIGHT EXTRACTION FOR NON-TRIVIAL WORK

重要なセッションでは、コンテキストが失われる前に学びを記録してください。

必要な入力

インサイトを抽出するには、次の情報が必要です。

1. Git diff - 変更されたファイルと変更内容
2. タスクの説明 - 実装しようとしていた内容
3. 試行履歴 - 以前の試行（あれば）と、使用したアプローチ
4. セッションの結果 - 成功または失敗

ワークフロー

フェーズ 1：セッションデータの収集

# Get the diff of changes
git diff HEAD~1 --stat
git diff HEAD~1

# Get commit message
git log -1 --pretty=format:"%s%n%n%b"

# Get list of modified files
git diff HEAD~1 --name-only

フェーズ 2：ファイルごとのインサイト分析

変更したファイルごとに、次の内容を抽出します。

• 目的：このファイルはどのような役割を担っていますか？
• 変更内容：どのような変更を行いましたか？「何を」だけでなく、「なぜ」を重視してください
• 使用したパターン：どのようなコーディングパターンを適用しましたか？
• 注意点：このファイル固有の落とし穴はありますか？

良い例：

{
  "path": "src/stores/terminal-store.ts",
  "purpose": "Zustand store managing terminal session state with immer middleware",
  "changes_made": "Added setAssociatedTask action to link terminals with tasks",
  "patterns_used": ["Zustand action pattern", "immer state mutation"],
  "gotchas": ["State changes must go through actions, not direct mutation"]
}

悪い例（曖昧すぎます）：

{
  "path": "src/stores/terminal-store.ts",
  "purpose": "A store file",
  "changes_made": "Added some code",
  "patterns_used": [],
  "gotchas": []
}

フェーズ 3：パターンの抽出

再利用可能なパターンのみを抽出します。

• このケース以外にも適用できること
• そのパターンを適用する場所やタイミングを含めること
• コードベース内の具体例を参照すること

良い例：

{
  "pattern": "Use e.stopPropagation() on interactive elements inside containers with onClick handlers",
  "applies_to": "Any clickable element nested inside a parent with click handling",
  "example": "Terminal.tsx header - dropdown needs stopPropagation to prevent focus stealing"
}

フェーズ 4：注意点の記録

具体的で、実行可能な内容にしてください。

• 問題を引き起こす条件を含めること
• 解決または予防する方法を含めること
• 一般的な助言（「Xに注意する」など）は避けること

良い例：

{
  "gotcha": "Terminal header onClick steals focus from child interactive elements",
  "trigger": "Adding buttons/dropdowns to Terminal header without stopPropagation",
  "solution": "Call e.stopPropagation() in onClick handlers of child elements"
}

フェーズ 5：アプローチの結果を記録

成功または失敗から得た学びを記録します。

• 成功した場合：このアプローチがうまくいった理由は何ですか？重要なポイントは何でしたか？
• 失敗した場合：失敗の理由は何ですか？代わりに何がうまくいったでしょうか？
• 試した代替案：ほかにどのようなアプローチを試しましたか？

これにより、今後のセッションで過去の試行から学べるようになります。

フェーズ 6：推奨事項の作成

今後の作業に向けた、具体的で実行可能なアドバイスを作成します。

• 今後のセッションで実装できる内容にすること
• 一般的な内容ではなく、このコードベースに特化させること
• 次に行うことや、注意すべきことに焦点を当てること

良い例：「Terminal ヘッダーにコントロールを追加する場合は、このセッションのドロップダウンパターンに従い、stopPropagation を使って、ヘッダーを基準に位置を設定してください」

悪い例：「良いコードを書く」または「十分にテストする」

フェーズ 7：構造化されたインサイトの出力

構造化されたインサイトの出力を作成します。

# Session Insights: [Task Name]

## Date

[timestamp]

## Task

[Description of what was being implemented]

## Outcome

[SUCCESS/FAILURE]

## File Insights

### [file-path]

- **Purpose**: [what this file does]
- **Changes**: [what was changed and why]
- **Patterns**: [patterns used]
- **Gotchas**: [things to watch out for]

## Patterns Discovered

### [Pattern Name]

- **Pattern**: [description]
- **Applies to**: [when to use]
- **Example**: [file or code reference]

## Gotchas Discovered

### [Gotcha Name]

- **Issue**: [what to avoid]
- **Trigger**: [what causes it]
- **Solution**: [how to handle]

## Approach Analysis

### What Worked

[Description of successful approach]

### What Failed (if applicable)

[Description of failed approaches and why]

### Alternatives Tried

[List of other approaches attempted]

## Recommendations for Future Sessions

1. [Specific recommendation 1]
2. [Specific recommendation 2]

.claude/context/memory/learnings.md に追記して保存します。

例外的なケースへの対応

差分がない、または最小限の場合

diff が非常に小さいか空の場合：

• 推測できる場合は、ファイルの目的も抽出します
• セッションでの変更が最小限だったことを記録します
• 次のステップに関する推奨事項に焦点を当てます

セッションが失敗した場合

セッションが失敗した場合：

• 失敗の理由に焦点を当てます。これが最も価値のあるインサイトです
• 失敗から学んだことを抽出します
• 推奨事項では、次回成功する方法を示します

複数のファイルを変更した場合

• 最も重要なファイルを3～5個優先します
• 定型的な変更（package-lock.json など）は省略します
• 機能の中心となるファイルに焦点を当てます

検証チェックリスト

インサイトの抽出を完了する前に、次を確認します。

• Git diff を分析した
• 主要なファイルのインサイトを抽出した
• 再利用可能なパターンを記録した
• 発生条件と解決策を含めて注意点を記録した
• アプローチの結果を記録した
• 推奨事項が具体的で実行可能である
• インサイトをメモリーファイルに保存した

よくある間違い

曖昧すぎる

問題点：「バグを修正した」では、誰の役にも立ちません。

代わりにこうします：「クリーンアップ関数を追加して useEffect 内の競合状態を修正した。パターン：非同期エフェクトでは、必ずクリーンアップ関数を返す」

一般的なアドバイス

なぜよくないのか：「コードをテストする」だけでは、実行すべきことが明確ではありません。

代わりにこうしてください：「ストアのロジックを変更した後に npm test src/stores を実行します。テストで状態管理のバグを検出できます。」

コンテキストの不足

**なぜよくないのか：**後続のセッションで、その理由がわからなくなります。

**代わりにこうしてください：**ファイルパス、関数名、具体的なシナリオを記載します。

他のスキルとの連携

このスキルは、次のスキルと相性がよいです。

• session-handoff：引き継ぎドキュメントで知見を活用します
• summarize-changes：変更の要約に知見を加えます
• debugging：デバッグセッションから知見を抽出します

絶対に守るべきルール

1. 必ずタスク完了後すぐに知見を抽出します。抽出が遅れるとコンテキストが失われます。「何をしたか」は再構成できますが、「なぜそうしたか」はセッション中に消えてしまいます。
2. 決して実施した作業を記録しません。記録するのは学んだことだけです。作業ログはタスクのメタデータに記録し、学習システムには記録しません。
3. 必ず書き込む前に、重複する知見がないか確認します。ほぼ同じ知見を追記するとメモリーインデックスが汚染され、今後の検索精度が低下します。
4. 具体的なコンテキスト、ファイルパス、例を示さずに「X はよい」のような曖昧な知見を決して書きません。曖昧な知見は見つけにくく、後続のセッションで役に立ちません。
5. 必ず知見にドメインカテゴリ（[CODE]、[WORKFLOW]、[SECURITY] など）のタグを付けます。タグのない知見は、ドメイン別に検索するエージェントから実質的に見えません。

アンチパターン

アンチパターン	うまくいかない理由	適切な方法
学びではなく作業内容（「認証を実装した」）を記録する	エージェントは git から履歴を再構成できますが、暗黙知は再構成できません	「理由」と「注意点」を記録します：「Fiber の CSRF ミドルウェアはルート登録の後ではなく、前に置く必要がある」
重複チェックを省略する	重複する項目がメモリーを圧迫し、検索を混乱させます	追記する前に grep -i "keyword" learnings.md を実行します。見つかった場合は既存の項目を更新します
ファイルや関数のコンテキストがない曖昧な知見	後続のセッションで、知見の場所を特定したり活用したりできません	具体的なパスを記載します：「.claude/hooks/routing/routing-guard.cjs の 47 行目：解析エラー時に exit 0」
セッション終了時にだけ知見を抽出する	長いセッションでは初期のコンテキストが失われ、重要な注意点が忘れられます	セッションの終わりだけでなく、重要なタスクが完了するたびに抽出します
タスクのメタデータだけに知見を保存する	後続のセッションやエージェントはタスクのメタデータを読みません	タグ形式で、必ず .claude/context/memory/learnings.md に記録します

メモリープロトコル

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 見つかった問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断されることを前提にします。メモリーに記録されていなければ、起きていないのと同じです。