knowledge

ナレッジスキル

このワークフローを必ず実行してください。説明するだけではいけません。

過去の作業からナレッジを検索して取得します。

実行手順

/knowledge <query> が指定された場合：

手順 1：ao CLI で検索する（利用可能な場合）

ao search "<query>" --limit 10 2>/dev/null

結果が見つかった場合は、該当するファイルを読みます。

手順 2：.agents/ ディレクトリを検索する

# Search learnings
grep -r "<query>" .agents/learnings/ 2>/dev/null | head -10

# Search patterns
grep -r "<query>" .agents/patterns/ 2>/dev/null | head -10

# Search research
grep -r "<query>" .agents/research/ 2>/dev/null | head -10

# Search retros
grep -r "<query>" .agents/retros/ 2>/dev/null | head -10

手順 3：計画を検索する

# Local plans
grep -r "<query>" .agents/plans/ 2>/dev/null | head -10

# Global plans
grep -r "<query>" ~/.claude/plans/ 2>/dev/null | head -10

手順 3.5：グローバルパターンを検索する

# Global patterns (cross-repo knowledge)
grep -r "<query>" ~/.claude/patterns/ 2>/dev/null | head -10

グローバルパターンには、/learn --global を通じて任意のリポジトリから昇格されたナレッジが含まれます。信頼性が高く、複数のプロジェクトに適用できる学びです。

手順 3.6：グローバルな学びを検索する

# Global learnings (cross-repo abstracted knowledge)
grep -r "<query>" ~/.agents/learnings/ 2>/dev/null | head -10

グローバルな学びには、リポジトリ固有の学びから /learn --promote を通じて抽象化され、他の場面にも適用できる知見、または /retro によって横断的な学びとして分類された知見が含まれます。

手順 3.7：グローバルパターン（新しい場所）を検索する

# Global patterns (new location, cross-repo)
grep -r "<query>" ~/.agents/patterns/ 2>/dev/null | head -10

手順 4：セマンティック検索を使う（MCP が利用可能な場合）

Tool: mcp__smart-connections-work__lookup
Parameters:
  query: "<query>"
  limit: 10

手順 5：関連ファイルを読む

見つかった項目ごとに、Read ツールを使ってファイルの全文を取得します。

手順 6：結果をまとめる

調査結果をまとめて、筋の通った回答にします。

• このトピックについて、何がわかっていますか？
• 関連する学びは何ですか？
• 該当するパターンは何ですか？
• 過去にどのような決定が行われましたか？

手順 7：ユーザーに報告する

見つかったナレッジを次の内容とともに提示します。

1. 調査結果の概要
2. 主な学び（ID 付き）
3. 関連するパターン
4. ソースファイルへのリンク
5. 確信度（どの程度わかっているか）

ナレッジの保存場所

種類	場所	形式
学び	.agents/learnings/	Markdown
パターン	.agents/patterns/	Markdown
調査	.agents/research/	Markdown
振り返り	.agents/retros/	Markdown
計画	.agents/plans/	Markdown
グローバル計画	~/.claude/plans/	Markdown
グローバルな学び	~/.agents/learnings/	リポジトリ横断で抽象化された学び
グローバルパターン	~/.agents/patterns/	リポジトリ横断で再利用可能なパターン
レガシーパターン	~/.claude/patterns/	読み取り専用のフォールバック（書き込みには非推奨）

主なルール

• 複数の場所を検索する — ナレッジが分散している可能性があります
• まず ao CLI を使う — セマンティック検索のほうが優れています
• grep にフォールバックする — ao が利用できない場合
• ファイルを全文読む — 検索結果だけを報告してはいけません
• 結果をまとめる — 調査結果を組み合わせて役立つ回答にします

クエリの例

/knowledge authentication    # Find auth-related learnings
/knowledge "rate limiting"   # Find rate limit patterns
/knowledge kubernetes        # Find K8s knowledge
/knowledge "what do we know about caching"

例

過去の学びを見つける

ユーザーの入力： /knowledge "error handling patterns"

実行内容：

1. エージェントが ao search "error handling patterns" を試し、3 件の該当項目を見つける
2. エージェントが grep で .agents/learnings/ を検索し、さらに 5 件の該当項目を見つける
3. エージェントが .agents/patterns/ から関連するパターンを検索し、2 件の該当項目を見つける
4. エージェントが Read ツールを使って、該当するファイルをすべて読む
5. エージェントが調査結果をまとめ、筋の通った回答を作成する
6. エージェントが次のように報告する：「エラー処理に関する学びが 5 件あります。L1（エラーを必ずラップする）、L3（型付きエラーを使う）、L12（返す前にログを記録する）、L15（コンテキストを伝播する）、L22（バックオフを伴う再試行を行う）」
7. エージェントがソースファイルへのリンクと確信度を提示する。確信度は高（複数の情報源で裏付けられている）

結果： 5 件の具体的な学びと 2 件の関連パターンを、すべて出典付きでまとめた完全なナレッジ統合が得られます。

ao CLI を使わずに検索する

ユーザーの入力： /knowledge "database migrations"

実行内容：

1. エージェントが ao search を試すが、コマンドが見つからない
2. エージェントが .agents/ ディレクトリ全体を grep で検索する
3. エージェントが学びの中から 2 件、調査資料の中から 1 件、パターンの中から 0 件の該当項目を見つける
4. エージェントが該当するファイルを読む
5. エージェントが次のようにまとめる：「見つかったナレッジは限られています。L8 ではトランザクションでラップしたマイグレーションの使用を推奨しています。2026-01-20 の調査資料では、マイグレーションツールを分析しています。」
6. エージェントが確信度を中と報告する（情報源が 2 件のみのため）

結果： ao CLI がなくてもナレッジを見つけられ、情報源の数に応じた適切な確信度が示されます。

トラブルシューティング

問題	原因	解決策
結果が見つからない	クエリが具体的すぎる、またはナレッジがまだ記録されていない	検索語句を広げてください。同義語も試してください。最近の作業でこのトピックが扱われているものの、振り返りがまだ実行されていないか確認してください。最近の学びを抽出するために /retro の実行を提案してください。
結果が多すぎて把握しきれない	検索語句の範囲が広すぎる	より具体的な語句を使ってクエリを絞り込んでください。日付で絞り込み、最近の学びだけを検索してください。利用可能な場合は、より適切に順位付けできるセマンティック検索（ao CLI）を使用してください。
結果に文脈がない	Grep で一致が見つかったものの、ファイルがクエリに答えていない	一致した行だけでなく、ファイル全体を読んでください。周辺の文脈から情報をまとめてください。元の調査までさかのぼるために /trace が必要になる場合があります。
確信度が不明確	情報源が混在している、または矛盾している	矛盾する情報を明示して報告してください。どの情報源が一致し、どれが一致しないかを記してください。重要な場合は、さらに調査するために /research の実行を提案してください。