knowledge-extractor

ナレッジ抽出スキル

目的

このスキルは、会話、デバッグセッション、失敗した試行、解決済みの問題から知識を自動的に抽出、統合、保存します。一時的なやり取りを永続的な組織の知識に変換し、今後のパフォーマンスを向上させます。

このスキルを使用する場面

• セッション終了時の分析：セッションのコンテキストが失われる前に学びを抽出します
• 複雑なデバッグの後：根本原因と解決策を、記憶が新しいうちに記録します
• 失敗した試行の後：うまくいかなかったこととその理由を記録します
• 問題を解決した後：解決策を保存し、今後再利用できるようにします
• 新しいパターンの発見時：文書化すべきパターンを特定します
• ワークフローの繰り返し時：新しい専門エージェントを作成すべきタイミングを把握します
• セッションをまたいだ学習：個々のセッションから組織の記憶を構築します

基本理念：知識の保存

セッションのコンテキスト：積極的に保存しなければ失われる、一時的な会話のコンテキストです
永続的な知識：今後のパフォーマンスを向上させる、構造化された学びです
パターン認識：解決策が繰り返され、自動化すべきタイミングを特定することです
組織の成長：個々の学びをシステム全体の改善につなげることです

知識抽出フレームワーク

3 種類の知識抽出

1. 発見 — 新しい知見と根本原因

記録するもの：遭遇した問題、特定した根本原因、実施した解決策

抽出するタイミング：

• 複雑なバグを解決した後
• デバッグで予想外の動作が判明したとき
• 誤った前提に気づいたとき
• 機能の不足を特定した後
• 何かが失敗した理由を学んだとき

DISCOVERIES.md の形式：

## [Brief Title] (YYYY-MM-DD)

### Issue

What problem or challenge was encountered?

### Root Cause

Why did this happen? What was the underlying issue?

### Solution

How was it resolved? Include code examples if relevant.

### Key Learnings

What insights were gained? What should be remembered?

### Prevention

How can this be avoided in the future?

品質基準：

• ✅ 一般論ではなく、具体的な問題である
• ✅ 根本原因が明確に特定されている
• ✅ 実際に機能する解決策が含まれている
• ✅ 再利用できるよう、学びが一般化されている
• ✅ 再発防止策が記録されている

2. パターン — 再利用可能な解決策

記録するもの：繰り返し発生する問題に対する実証済みの解決策、アーキテクチャのアプローチ、設計パターン

抽出するタイミング：

• 既知のパターンと類似した問題を解決した後
• 同じ種類の問題が繰り返されていると気づいたとき
• 実証済みの解決策を実装したとき
• 効果のあるベストプラクティスを発見したとき
• 複数の状況に適用できる解決策を見つけたとき

PATTERNS.md の形式：

## Pattern: [Name]

### Challenge

What problem does this pattern solve?

### Solution

How does the pattern work? Include code/examples.

### Key Points

- Main insight 1
- Main insight 2
- When to use / when not to use

### When to Use

Specific scenarios where this pattern applies.

### Real Impact

Where has this pattern been used successfully?

### Related Patterns

Links to similar or complementary patterns.

品質基準：

• ✅ 複数の状況に適用できる程度に汎用的である
• ✅ 問題が明確に定義されている
• ✅ 解決策に実績がある
• ✅ 実際に機能するコード例がある
• ✅ 使用する場合と使用しない場合の指針が明確である

3. エージェントの作成 — 繰り返されるワークフローの自動化

記録するもの：頻繁に繰り返されるワークフロー、専門知識が必要な分野、複雑な複数ステップのプロセス

抽出するタイミング：

• 同じワークフローを 2～3 回実行した後
• 専門的なスキルが求められる分野を見つけたとき
• ワークフローの入力と出力が明確なとき
• 自動化によって大幅な時間短縮が見込めるとき
• 問題領域が狭く、明確に定義されているとき

エージェント作成のトリガーチェックリスト：

• 同じワークフローを 2 回以上繰り返している
• ワークフローの実行に 30 分以上かかる
• ワークフローの専門分野が明確である
• 現在のツールでワークフローを自動化できる
• 問題領域が狭く、明確に定義されている
• 自動化によって大きな価値が得られる

エージェント作成の例：

## Recommended New Agent: [domain]-[specialty]

### Problem

What repeated workflow would this agent handle?

### Scope

What's in scope | What's explicitly out of scope

### Inputs

What information does the agent need?

### Process

Step-by-step workflow the agent follows

### Outputs

What does the agent produce?

### Value

How much time/effort does this save?

### Integration

Where in the workflow does this fit?

抽出プロセスの手順

手順 1：セッションの分析（5 分）

会話／セッション全体を確認します：

1. What was the original problem/request?
2. What approaches were tried?
3. Which attempts failed and why?
4. What succeeded and why?
5. What was learned in the process?
6. What surprised you?
7. What took longer than expected?
8. What would have helped?

手順 2：パターンの認識（5 分）

作業の中にあるパターンを特定します：

1. Have I seen this problem before? (→ DISCOVERIES)
2. Is this a generalizable solution? (→ PATTERNS)
3. Would this be worth automating? (→ AGENT)
4. What was the root cause? (Why, not just what)
5. What should others know about this?
6. What should be remembered to avoid repetition?

ステップ 3：知識の抽出（10 分）

知識を抽出し、整理します。

DISCOVERIES.md の場合：

• 発生した具体的な問題
• 根本原因の分析
• 実施した解決策
• 一般化した重要な学び
• 再発防止策

PATTERNS.md の場合：

• パターンが解決する問題
• パターンの仕組み
• 使用する状況／使用しない状況
• 動作するコード例
• 関連するパターン

新しいエージェントの場合：

• 特定された反復ワークフロー
• 明確な適用範囲と境界
• 入力／出力の要件
• ステップごとのプロセス
• 期待される効果／時間の節約

ステップ 4：統合（3 分）

知識を適切な場所に配置します。

Memory → Store discovery using store_discovery() from amplihack.memory.discoveries
PATTERNS.md → New pattern in appropriate section
Agent → Create in .claude/agents/amplihack/specialized/

ステップ 5：検証（2 分）

品質を確認します。

[ ] Entry is specific, not generic
[ ] Entry follows template format
[ ] Examples/code provided
[ ] Quality sufficient for reuse
[ ] Grammar and clarity checked
[ ] Related items cross-referenced

使用例

例 1：バグ修正後に発見を抽出する

シナリオ：pre-commit フックが機能しない理由のデバッグに 45 分かかったところです。

User: Extract what we learned from debugging the pre-commit issue.

Claude:
1. Analyzes conversation showing:
   - Initial problem: hooks appeared to run but didn't modify files
   - False leads: blamed merge conflicts, tool versions
   - Root cause found: Hooks couldn't write to files due to cloud sync lock
   - Solution: Added exponential backoff retry logic
   - Time to discover: 45 minutes

2. Creates DISCOVERIES.md entry:
   - Issue: Pre-commit hooks silently failing
   - Root Cause: Cloud sync (OneDrive) file locks
   - Solution: Exponential backoff retry (0.1s, 0.2s, 0.4s...)
   - Key Learning: Cloud sync issues silent - need defensive coding
   - Prevention: Add retry logic for file I/O, test with cloud storage

3. Offers to also:
   - Add pattern for "Resilient File I/O" to PATTERNS.md
   - Suggest new agent for cloud-sync issue detection

例 2：実装に成功した後でパターンを抽出する

シナリオ：モジュール再生成戦略の実装が完了したところです。

User: Extract the pattern we discovered for building regeneratable modules.

Claude:
1. Analyzes implementation showing:
   - Clear __all__ exports defining public interface
   - Self-contained module structure
   - Type-hinted functions with docstrings
   - Comprehensive test coverage
   - Working examples

2. Creates PATTERNS.md entry:
   - Pattern: Module Regeneration Structure
   - Challenge: Modules become tightly coupled, hard to regenerate
   - Solution: Brick & studs design with __all__ public API
   - Key Points: Clear contracts, single responsibility, testable behavior
   - When to Use: Any utility module, anything that might be regenerated
   - Real Impact: Enables AI to rebuild modules without breaking system

3. Cross-references:
   - Relates to "Bricks & Studs Module Design"
   - Enables "Builder Agent Workflow"

例 3：新しいエージェントを作成する機会を特定する

シナリオ：5 ステップの診断プロセスを使って CI の失敗を 3 回目にデバッグしました。

User: We keep using the same CI debugging process. Should we automate it?

Claude:
1. Analyzes past sessions:
   - Session 1: 45 minutes CI debugging (version mismatch issue)
   - Session 2: 30 minutes CI debugging (pre-commit hook issue)
   - Session 3: 25 minutes CI debugging (merge conflict issue)
   - Pattern: Same 5-step process each time

2. Recommends new agent:
   - Name: ci-diagnostic-workflow
   - Problem: Each CI failure requires manual diagnosis, takes 30-45 min
   - Scope: Diagnoses CI failures, suggests fixes (doesn't auto-fix)
   - Process:
     1. Check environment (Python version, tool versions)
     2. Analyze CI logs for error patterns
     3. Detect common issues (conflicts, missing deps)
     4. Suggest solutions
     5. Coordinate parallel diagnostic agents
   - Value: Reduce diagnosis time from 45 min → 15 min

3. Proposes creating:
   - .claude/agents/amplihack/ci-diagnostic-workflow.md
   - Can delegate to: fix-agent for implementation

例 4：複数レベルの抽出

シナリオ：複数の学びを含む、複雑なアーキテクチャ上の決定です。

User: Extract everything we learned from deciding on the memory architecture.

Claude:
1. Session involved:
   - 2 failed approaches (too complex, wrong threat model)
   - 1 successful approach (simple, fits threat model)
   - Discovery of meta-pattern for architecture decisions

2. Creates THREE extractions:

   DISCOVERIES.md:
   - Issue: Pattern Applicability Analysis
   - Root Cause: Importing patterns without validating threat match
   - Solution: Five-phase applicability analysis framework
   - Learning: Threat model match is critical first check

   PATTERNS.md:
   - New Pattern: Threat Model Precision Principle
   - Challenge: Fault tolerance mechanisms mismatch problem space
   - Solution: Validate threat model before adopting patterns
   - When: Before adopting any "best practice" from different domain

   Recommended Agent:
   - Name: pattern-applicability-analyzer
   - Automate: Quick assessment of pattern applicability
   - Value: Prevent adopting wrong patterns early

知識の品質チェックリスト

抽出を確定する前に、次の項目を確認してください。

DISCOVERIES.md の場合

• 問題が具体的である（「ツールが壊れている」ではなく「pre-commit フックが失敗する」）
• 根本原因が特定されている（何が起きたかだけでなく、なぜ起きたか）
• 解決策が機能し、実証されている
• 学びが一般化されている（この具体的なケース以外にも適用できる）
• 再発防止策が実行可能である
• 推測や将来への過剰な備えがない
• 該当する場合、コード例が示されている

PATTERNS.md の場合

• 問題が明確で、認識しやすい
• 解決策の実績がある（2 回以上、問題なく使用されている）
• 使用する場合／しない場合の指針が明確である
• パターンが再利用できる程度に汎用的である
• コード例が動作し、分かりやすい
• 関連するパターンが相互参照されている
• 実際の効果または使用状況が記録されている

新しいエージェントの場合

• ワークフローが 2 回以上繰り返されている
• 実行のたびに 30 分以上の時間を節約できる
• 問題領域が限定され、明確に定義されている
• 入力と出力が明確である
• ステップごとのプロセスが文書化されている
• 自動化にかける労力に見合う高い価値がある
• ワークフローのどこに組み込むかが明確である

システムとの統合

発見のメモリのライフサイクル

1. 抽出：セッション中に store_discovery() を使ってメモリに保存します
2. 可視化：セッション開始時に get_recent_discoveries() で取得します
3. 活用：エージェントは、類似の問題を解決する際にメモリを参照できます
4. 再発防止：セッションをまたいだ同じミスの繰り返しを防ぎます
5. 進化：より良い解決策が見つかったときに更新します

PATTERNS.md のライフサイクル

1. 抽出：パターンが実証されたら PATTERNS.md に追加します
2. カタログ化：利用可能なパターンのライブラリに加わります
3. 活用：関連するエージェントの指示で参照します
4. 共有：ドキュメントやオンボーディングで使用します
5. 改善：利用データが増えるにつれて改良します

エージェント作成のライフサイクル

1. 推奨：価値のある自動化候補として特定します
2. 提案：期待される効果とともにシステムに提示します
3. 作成：明確な適用範囲と境界を持つ新しいエージェントを作成します
4. 統合：CLAUDE.md の委任トリガーに追加します
5. 活用：ワークフロー全体でのオーケストレーションに使用できます

実際の効果の例

効果 1：無駄なデバッグ時間を防ぐ

知識を抽出しない場合：同じ 45 分のデバッグ作業を繰り返します
抽出した場合：メモリから取得し、10 分で修正します

効果 2：解決策をより早く見つける

抽出しない場合：解決策を一から探し直します
抽出した場合：PATTERNS.md を参照し、既知の解決策を適用します

効果 3：ワークフローを自動化する

抽出しない場合：毎回 CI を手動でデバッグします（30～45 分）
新しいエージェントを使う場合：5～10 分で自動診断します

避けるべき一般的な抽出ミス

ミス 1：汎用的すぎる

BAD: "Learned that good error handling is important"
GOOD: "Discovered cloud sync issues cause silent file I/O failures - need exponential backoff retry"

ミス 2：根本原因の欠落

BAD: "CI failed, fixed it"
GOOD: "CI failed because version mismatch (local 3.12 vs CI 3.11) - fixed by updating pyproject.toml version constraint"

ミス 3：実行可能な学びがない

BAD: "This was complicated"
GOOD: "Multi-layer sanitization at every data transformation prevents credential leakage"

ミス 4：パターンの過度な一般化

BAD: "Always use caching everywhere"
GOOD: "Use smart caching with lifecycle management for expensive operations where results may become stale"

ミス 5：費用対効果を考慮しないエージェント作成

BAD: "Create agent for task that happens once per quarter"
GOOD: "Create agent for CI debugging workflow that happens 2-3x per week and takes 30-45 minutes"

抽出プロンプト

以下のプロンプトを使って、知識の抽出を促します。

発見事項を抽出する

Extract what we discovered/learned from this session.
Focus on: root causes, unexpected behaviors, solutions that worked.
Update DISCOVERIES.md appropriately.

パターンを抽出する

What patterns should we capture for future reuse?
These should be proven solutions that apply to multiple situations.
Update PATTERNS.md appropriately.

エージェント化の機会を特定する

Should we create a new agent to automate any repeated workflows?
Check if any workflow has been done 2+ times and takes 30+ minutes.
Recommend creation with scope and value calculation.

完全な抽出

Perform complete knowledge extraction on this session.
Extract: discoveries, patterns, and agent creation recommendations.
Verify quality and update all three knowledge bases.

統合ポイント

ドキュメント主導型開発との連携

• 知識の抽出を使って、仕様とドキュメントを更新します
• パターンを抽出して、次の実装の指針にします

エージェントへの委任との連携

• 委任によって新たに必要な専門分野が明らかになったら、抽出します
• 委任パターンが繰り返される場合は、エージェントを作成します

コミット前分析との連携

• CI/CD とテストのパターンに関する発見事項を抽出します
• 新たに見つかったアプローチで PATTERNS.md を更新します

セッションの振り返りとの連携

• セッション終了時に知識を自動的に抽出します
• コンテキストの圧縮前に学びを保持します

成功指標

知識抽出の有効性を追跡します。

• 再利用された発見事項：DISCOVERIES.md によってミスが防がれた頻度（目標：80% 以上）
• 適用されたパターン：PATTERNS.md によって解決が速くなった頻度（目標：70% 以上）
• エージェントの使用率：手動での対応と比べて、抽出されたエージェントが使用された頻度（目標：60% 以上）
• 節約された時間：知識の再利用によって累積的に節約された時間（目標：週あたり数時間）
• 繰り返されたミス：同じミスを二度繰り返すことの減少率（目標：95% 以上）

今後の発展

このスキルは、以下に基づいて成長していきます。

• 抽出する価値が最も高い知識の種類は何ですか？
• 適切な抽出を妨げる要因は何ですか？
• 抽出した内容をより実用的にするにはどうすればよいですか？
• 十分に活用されていない知識源は何ですか？
• 関連する知識をより効果的に提示するにはどうすればよいですか？

学びを ~/.amplihack/.claude/context/DISCOVERIES.md に記録します。