code-distill

Code-Distill — GitHub コードベースのパターン抽出手法

特定の GitHub コードベースを対象に、焦点を絞ったクエリに応じてエージェントがコードパターンをオンデマンドで抽出するときに行う一般的な処理を、手法としてまとめたものです。ライブラリごとのスキルではありません。スキルは 1 つだけ用意し、共有ナレッジグラフにライブラリごとの簡単な記録を追加します（/knowledge/libraries/）。どのリポジトリでも作業の 90% は同じだからです。

これは、静的なコードアトラスの抽出物に対する動的で軽量な兄弟スキルです。opencode-ts、openai-codex-rust-patterns、nextjs-ppr-patterns が該当します。これらのスキルは、事前に単一のリポジトリからパターンを抽出した、丹念にまとめられた重厚な成果物です。このスキルは、そのオンデマンド版です。対象ライブラリに静的スキルがまだない場合は、リポジトリを指定して、この手法を実行します。

適用する場合

次のような場合に、このスキルを使用します。

• ユーザーが「<library> は <feature> をどのように実装していますか？」と尋ね、実際の GitHub リポジトリを指定する（または名前を挙げる）
• クエリが単一のサブシステム（デザインシステム、コンポジション、状態、エラー処理、エフェクト、ビルド、ルーティング）に焦点を絞っている。「このコードベース全体は何ですか？」のような質問ではない
• 対象ライブラリに静的なコードアトラスのスキルがまだない（または既存のスキルが古くなっている）
• アドホックな呼び出しが /distill <library> <query> のような形式、または自然言語での「リポジトリ Y で X を見せて」のような形式である
• ライブラリの対象範囲が狭すぎる、または存続期間が短すぎるため、完全な静的コードアトラスの抽出物を作成する価値がない

このスキルは、次の用途には使用しません。

• 静的なコードアトラスのスキルがあるライブラリ — まず opencode-ts、openai-codex-rust-patterns、nextjs-ppr-patterns、または提供されているその他のライブラリごとのスキルを使用してください。これらは（すでに精選されているため）より迅速に使え、このスキルではオンデマンドで再発見できない失敗ギャップの教訓も取り入れています。
• コードベース全体のアーキテクチャマッピング — 「このコードベース全体は、ドメイン別に見ると何をしていますか？」という質問には、codebase-comprehension-algorithms を使用してください。こちらは Leiden、MoJoFM、SBM を含む、アルゴリズムを駆使する重厚なツールキットです。このスキルは、焦点を絞ったクエリからの抽出を目的としています。
• 完全な静的コードアトラスのスキルの作成 — その作成作業のための手法プレイブックは、別の（まだ作成されていない）スキルです。これは library-reference-distillation に対応するコードソース版です。同じライブラリに対して code-distill を 3 回以上実行するようになったら、完全な静的スキルに発展させるべきサインです。
• ドキュメントの検索 — 「<library> のドキュメントで X はどこにありますか？」という質問には、docs-search を使用してください。このスキルの対象はソースコードであり、ドキュメントではありません。

使い方

4 つのカテゴリーは、それぞれ独立した操作です。症状に合った操作を選んでください。

症状	選ぶ操作	最初に読むルール
やみくもに grep しようとしている、クエリが曖昧	Find	find-classify-query
パターンを特定する前に、ファイル全体を読もうとしている	Find（grep）	find-grep-before-read
候補のファイルは見つかったが、慣用的な書き方かどうかわからない	Find（テスト）	find-tests-show-intent
名前がわかっているエントリーを読む前に、knowledge/libraries/ を一通り確認しようとしている	Find（範囲を絞った読み取り）	find-bounded-knowledge-read
実装は見つかったが、公開インターフェースを把握する必要がある	Trace（外向き）	trace-imports-outward
公開インターフェースはわかったが、バリエーションや変遷を確認する必要がある	Trace（内向き）	trace-usages-inward
ボイラープレート、レガシーなパス、テスト用の足場に埋もれている	Filter	filter-load-bearing
完了 — セッションを終了しようとしている	Capture	capture-registry-record

カテゴリーの概要と順序の理由については、references/_sections.md を参照してください。

ルールカテゴリー

#	カテゴリー	プレフィックス	操作	ルール数
1	Find	find	クエリに合うコードを特定し、knowledge を範囲を絞って読む	4
2	Trace	trace	インポートと使用箇所をたどり、パターンを把握する	2
3	Filter	filter	ノイズを除いて、重要なパターンを浮かび上がらせる	1
4	Capture	capture	コードの全体像を registry/ に記録し、再利用できるようにする	1

クイックリファレンス

1. Find

• find-classify-query — grep する前にクエリを分類します（コンポーネント／コンポジション／状態／エフェクト／エラー／ビルド／ルーティング）。分類によって grep の対象とフォルダーの手がかりが決まります
• find-grep-before-read — まず狭い範囲で grep してファイルを特定します。ファイル全体を読むところから始めてはいけません
• find-tests-show-intent — テスト、examples/、e2e/ ディレクトリは、作者が意図を示すための標準的な例です。文章から仮説を立てる前に確認してください
• find-bounded-knowledge-read — ファイル名がインデックスです。knowledge/libraries/<slug>.md だけを読み、ディレクトリ全体を確認してはいけません。knowledge ストアのサイズにかかわらず、呼び出しごとのトークンコストを一定範囲に抑えます

2. Trace

• trace-imports-outward — 実装ファイルからインポートを外向きにたどり、パターンの公開インターフェースと依存関係を見つけます
• trace-usages-inward — 公開インターフェースから同じリポジトリ内の呼び出し箇所を見つけ、バリエーション、エッジケース、パターンの変遷を確認します

3. Filter

• filter-load-bearing — ボイラープレート（再エクスポート、ビルダー、ヘルパー）、レガシーなパス（非推奨のディレクトリ、_old/、legacy/）、テスト用の足場を回答から除きます。回答には重要なパターンだけを残します

4. Capture

• capture-registry-record — セッションが正常に終わったら、knowledge/libraries/<library>.md の code: セクション（リポジトリ URL、ブランチ、SHA、フォルダーマップ、命名規則、AGENTS.md フラグ、サンプルディレクトリの場所）を記録し、次回の検索で探索を省けるようにします

ナレッジストア

ライブラリごとのコード構造記録は、リポジトリルートの共有ナレッジグラフ /knowledge/libraries/ に保存されています。同じファイルは docs-search からも書き込まれます。それぞれのスキルが担当するセクション（このスキルは code:、docs-search は docs:）だけを扱い、もう一方を上書きすることはありません。統合スキーマ、Wikiリンクの規約、マージのルールについては knowledge/README.md を参照してください。

ナレッジストアは v0.1.0 では意図的に空 です。このスキルを生み出した「徹底的な簡素化」の提言では、先回りして準備せず、実際の検索から最初のエントリを追加するよう述べています。実際に調べていないリポジトリの記録を追加しようとしていることに気づいたら、そこで止めてください。実際に必要になるまで待ちます。

読み取りのルール：ユーザーがライブラリ名を指定したら、read knowledge/libraries/<slug>.md だけを実行してください。「利用可能なもの」を確認するために knowledge/libraries/ を走査してはいけません。ファイル名がインデックスであり、必要なときにだけアクセスすることで、ナレッジストアのサイズにかかわらず、呼び出しごとのトークンコストを抑えられます。

関連スキル

• docs-search — ソースコードではなくドキュメントを対象とする対称的な兄弟スキルです。同じ構成（手法＋共有ナレッジグラフ）で、このスキルが code: セクションを書き込む knowledge/libraries/<lib>.md ファイルの docs: セクションを書き込みます
• library-reference-distillation — 上流ドキュメントから完全なライブラリリファレンスのルールパックを作成するための執筆ガイドです。ドキュメントソースを扱う、より大規模な兄弟スキルです
• （将来）code-atlas-distillation — まだ作成されていません。opencode-ts のような、完全な静的コードアトラススキルを作成するための執筆ガイドです。4つ目か5つ目の静的コードアトラススキルをリリースし、経験的なパターンが確認できた時点で抽出してください。
• opencode-ts、openai-codex-rust-patterns、nextjs-ppr-patterns — 特定のライブラリ向けに厳選された大規模な成果物です。存在する場合は、このスキルより優先して使用してください
• codebase-comprehension-algorithms — コードベース全体のドメインマッピングに使う、Leiden、MoJoFM、SBM などの大規模なアルゴリズムツールキットです。特定のクエリに対する抽出とは別の用途です
• radical-simplification — このスキルの上位にある思考レイヤーです。このスキル自体が、繰り返し発生する「XごとにN個のスキル」問題に対して、「制約する → 不変条件に名前を付ける」というアプローチを3回目に適用したものです

執筆上の注意

これらのルールは飾りではなく、実用上不可欠です。それぞれが、未知のソースコードを調べる際にエージェントが陥りがちな誤った初期設定を示しています。たとえば、grep する前にファイル全体を読むこと、テストを正規の意図として扱わないこと、定型コードと重要なパターンを混同すること、検索を毎回単発で終わらせることです。高性能なモデルがすでに正しく実行できることを言い換えているだけのルールは削除してください。網羅性は、ルールの数ではなく、実際の「X はどのように Y を実装するか」というプロンプトを使った /dev-skill:eval で検証します。レジストリは実際の検索ニーズに応じて自然に拡大します。あるライブラリが約3回を超えて検索されたら、完全な静的コードアトラススキルへ昇格させる合図です。