mcpField
R
research-codebase

research-codebase

github.com/bastani-inc開発870185 回インストール1 日前に更新
リポジトリ

research-codebase について

質問を並行調査に分解し、リポジトリ内の知見を統合してファイル参照付きの調査文書を作成する、開発者向けスキルです。

主な機能

  1. 01調査質問の分解
  2. 02コードベースの並行調査
  3. 03コンポーネント間の知見の統合
  4. 04参照付き調査文書の作成

活用シーン

  1. 01リポジトリ全体にまたがる実装の追跡
  2. 02認証やデータベースのフロー調査
  3. 03後続タスク向けのコードベース動作の記録

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bastani-inc/atomic --skill research-codebase

インストール後、Claude Code で/research-codebaseを入力して読み込まれたか確認します。

詳細

コードベースの調査

サブエージェントを並行して起動し、その調査結果を統合してユーザーの質問に回答するため、コードベース全体を包括的に調査してください。

ユーザーの調査に関する質問／依頼：$ARGUMENTS

調査クエリを受け取った後に実行する手順：

<EXTREMELY_IMPORTANT>

  • prompt-engineer のスキルを使って調査の質問を最適化し、明確さと正確さが最大限になるように表現と構成を整えてください。
  • 調査が完了し、調査成果物が生成されたら、調査の概要と調査ドキュメントへのパスをユーザーに提示し、追加の質問や説明が必要かどうかを尋ねてください。

</EXTREMELY_IMPORTANT>

  1. まず、直接言及されているファイルを読む：

    • ユーザーが特定のファイル（チケット、ドキュメント、その他のメモ）に言及している場合は、まずそれらを最後まで読んでください。
    • 重要：readFile ツールを使う際は、limit／offset パラメーターを指定せずにファイル全体を読み込んでください。
    • 最重要：サブタスクを開始する前に、メインコンテキストで自分自身がこれらのファイルを読んでください。
    • これにより、調査を分割する前に全体像を把握できます。

  2. 互換性に関する方針を決定する：

    • 調査依頼を分解する前に、このプロジェクトが実際のダウンストリームユーザーに対する後方互換性を維持する必要があるか判断してください。
    • ユーザーが破壊的変更、パブリック API の変更、クリーンアップを明示的に許可している場合、または実際のユーザー／ダウンストリーム依存関係がないと述べている場合は、breaking_changes_allowed: true に設定してください。
    • ユーザーが本番環境のユーザー、公開 API、ダウンストリームの利用者、移行の安全性、互換性要件に言及している場合は、breaking_changes_allowed: false に設定してください。
    • 方針を依頼から判断できない場合は、続行する前に、可能であれば利用可能な構造化質問ツールを使って一度だけユーザーに尋ねてください。
    • この方針を調査計画、各サブエージェントへのプロンプト、最終調査ドキュメントのフロントマター、および ## Compatibility Context セクションに反映してください。
    • breaking_changes_allowed: true の場合、既存のレガシー動作、互換性シム、オプションフラグ、パブリック API は、今後の仕様で維持すべき制約としてではなく、現状として記録してください。ただし、ユーザーが維持を明示的に求めている場合は除きます。
    • breaking_changes_allowed: false の場合、パブリック API、互換性に影響する領域、ダウンストリームの呼び出し元、移行上の制約、および今後の作業で維持すべき動作を記録してください。

  3. 調査の質問を分析し、分解する：

    • 調査の質問を、組み合わせ可能な調査領域に分割してください。
    • 根底にあるパターン、つながり、アーキテクチャ上の意味合いについて十分に深く考えてください。
    • 調査が必要な具体的なコンポーネント、パターン、概念を特定してください。
    • TodoWrite を使って、すべてのサブタスクを追跡する調査計画を作成してください。
    • 後の統合と仕様作成に同じ制約が引き継がれるよう、計画に互換性に関する方針を含めてください。
    • 関連するディレクトリ、ファイル、アーキテクチャパターンを検討してください。

  4. サブエージェントのタスクを並行して起動する：

    • 複数の Task エージェントを作成し、異なる側面を並行して調査させてください。
    • 特定の調査タスクに対応できる専門エージェントを利用できます。

    コードベースの調査：

    • codebase-locator エージェントを使って、ファイルやコンポーネントの場所を特定してください。
    • codebase-analyzer エージェントを使って、特定のコードの仕組みを理解してください（批評はしないでください）。
    • codebase-pattern-finder エージェントを使って、既存パターンの例を見つけてください（評価はしないでください）。
    • 出力ディレクトリ：現在の作業ディレクトリからの相対パスで research/docs/
    • 例：
      • データベースのロジックを見つけ、research/docs/2024-01-10-database-implementation.md に記録できます。
      • 認証フローを見つけ、research/docs/2024-01-11-authentication-flow.md に記録できます。 重要: すべてのエージェントはドキュメンタリアンであり、批評家ではありません。改善を提案したり問題を指摘したりすることなく、存在するものを記述します。

    リサーチディレクトリの場合:

    • codebase-research-locator エージェントを使用して、トピックに関するドキュメントが何存在するかを発見します
    • codebase-research-analyzer エージェントを使用して、特定のドキュメント（最も関連性の高いもののみ）から重要なインサイトを抽出します

    オンライン検索の場合:

    • 非常に重要: 依存関係として外部ライブラリを発見した場合は、外部ドキュメントとリソースのために codebase-online-researcher エージェントを使用します

      • エージェントは agent-browser スキルの agent-browser コマンド（または curl）を使用してライブの Web コンテンツを取得します。トークン効率の良い取得順序を適用するよう指示してください: (1) AI フレンドリーなインデックスとして curl https://<site>/llms.txt を試す（llmstxt.org を参照）、(2) 事前変換された Markdown を取得するために curl <url> -H "Accept: text/markdown" を試す（Markdown for Agents 経由で Cloudflare ホストのドキュメントでサポートされています）、(3) フォールバックとして agent-browser でページを開きスナップショットを取得する

      • エージェントに、調査結果とともにリンクを返し、それらのリンクをリサーチドキュメントに含めるよう指示してください

      • エージェントは再利用可能なソースドキュメントを research/web/<YYYY-MM-DD>-<kebab-case-topic>.md に保存する必要があります（frontmatter に source_url、fetched_at、fetch_method を記載）。これにより、将来のリサーチが再取得せずにそれらを再利用できます

      • 統合された Web リサーチ成果物の出力ディレクトリ: research/web/:

        将来のセッションのために保持する価値のあるドキュメント（リファレンスドキュメント、API スキーマ、SDK ガイド、リリースノート、トラブルシューティングの記事、アーキテクチャ記事）を取得した場合、frontmatter に以下を記録して research/web/<YYYY-MM-DD>-<kebab-case-topic>.md に write します:

        ---
source_url: <original URL>
fetched_at: <YYYY-MM-DD>
fetch_method: read | llms.txt | markdown-accept-header | browser | browse
topic: <short description>
---

      • その後に抽出されたコンテンツ（ナビゲーションの装飾、広告、無関係な定型文を除去したもの）を続けます。これにより、将来の作業が再取得せずにその検索結果を再利用できます。何かを取得する前に、既存の最近のコピーがないか素早く find research/web/ を実行してください。

      • 例:

        • Redis のロック使用法をリサーチする場合、エージェントは関連する使用法を見つけ、Redis ドキュメントとコード参照への内部リンクを含むドキュメント research/web/2024-01-15-redis-locks-usage.md を作成する場合があります（そして取得した Redis ドキュメントを research/web/ の下にキャッシュします）
        • OAuth フローをリサーチする場合、エージェントは関連する外部記事を見つけ、それらの記事へのリンクを含むドキュメント research/web/2024-01-16-oauth-flows.md を作成する場合があります

    重要なのは、これらのエージェントをインテリジェントに使用することです:

    • まず locator エージェントで何が存在するかを見つけます
    • 次に、最も有望な調査結果に対して analyzer エージェントを使用し、それらがどのように機能するかを記述します
    • 異なるものを検索している場合は、複数のエージェントを並行して実行します
    • 各エージェントは自分の役割を理解しています - 何を探しているかを伝えるだけです
    • どのように検索するかについて詳細なプロンプトを書かないでください - エージェントはすでに知っています
    • エージェントは評価や改善ではなく、ドキュメント化していることを思い出させてください
    • 各サブエージェントのプロンプトに breaking_changes_allowed: true または breaking_changes_allowed: false を含めて、互換性に敏感な調査結果が適切な姿勢でドキュメント化されるようにしてください。

  5. すべてのサブエージェントの完了を待ち、結果を統合します：

    • 先に進む前に、すべてのサブエージェントのタスクが完了するまで待ちます
    • すべてのサブエージェントの結果（コードベースと調査結果の両方）をまとめます
    • 現在のコードベースで得られた情報を、第一の信頼できる情報源として優先します
    • 調査結果は、補足的な歴史的背景として使用します
    • 異なるコンポーネント間の関連性をつなぎます
    • 参照用に具体的なファイルパスと行番号を記載します
    • パターン、関連性、アーキテクチャ上の判断を明らかにします
    • 具体的な根拠を示して、ユーザーの調査質問に回答します
    • 調査結果から、元の質問の前提が誤っていることが判明した場合（たとえば、システムの動作が想定と異なる場合や、想定した場所にコンポーネントが存在しない場合）、文書を完成させる前にユーザーにその点を伝えます。これは有益な情報なので、埋もれさせないでください。

  6. 調査ドキュメントを作成します：

    • 調査ドキュメントのディレクトリ構成に従います：
research/
├── tickets/
│   ├── YYYY-MM-DD-XXXX-description.md
├── docs/
│   ├── YYYY-MM-DD-topic.md
├── notes/
│   ├── YYYY-MM-DD-meeting.md
├── ...
└──

  • 命名規則：

    • YYYY-MM-DD は今日の日付です
    • topic は調査トピックを簡潔に表す kebab-case の説明です
    • meeting は会議のトピックを簡潔に表す kebab-case の説明です
    • XXXX はチケット番号です（チケットがない場合は省略します）
    • description は調査トピックを簡潔に表す kebab-case の説明です
    • 例：
      • チケットあり：2025-01-08-1478-parent-child-tracking.md
      • チケットなし：2025-01-08-authentication-flow.md

  • YAML フロントマターに続けて本文を記述します：

    ---
date: !`date '+%Y-%m-%d %H:%M:%S %Z'`
researcher: [thoughts status に記載された調査担当者名]
git_commit: !`git rev-parse --verify HEAD 2>/dev/null || echo "no-commits"`
branch: !`git branch --show-current 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unborn"`
repository: !`basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown-repo"`
topic: "[ユーザーの質問／トピック]"
tags: [research, codebase, 関連するコンポーネント名]
status: complete
last_updated: !`date '+%Y-%m-%d'`
last_updated_by: [調査担当者名]
breaking_changes_allowed: [true または false]
compatibility_context: "[下流ユーザー／API の互換性方針の簡潔な説明]"
---

# 調査

## 調査質問

[元のユーザーの質問]

## 互換性に関する背景

[破壊的変更が許可されるかどうかを記載します。許可される場合は、既存の互換性シム、オプションのフラグ、レガシー API、公開 API は、維持すべき制約ではなく現状として記録します。許可されない場合は、互換性に影響する領域、下流のユーザー／呼び出し元、移行上の制約、および今後の作業で維持すべき動作を要約します。]

## 概要

[見つかった内容を概説し、何が存在するかを説明して質問に回答します]

## 詳細な調査結果

### [コンポーネント／領域 1]

- 存在する内容の説明（[file.ext:line](link)）
- 他のコンポーネントとのつながり
- 現在の実装の詳細（評価は含めません）

### [コンポーネント／領域 2]

...

## コード参照

- `path/to/file.py:123` - 該当箇所の説明
- `another/file.ts:45-67` - コードブロックの説明

## アーキテクチャのドキュメント

[コードベースで確認された現在のパターン、規約、設計の実装]

## 歴史的背景（research/ より）

[research/ ディレクトリ内の関連情報と参照]

- `research/docs/YYYY-MM-DD-topic.md` - モジュール X に関する情報
- `research/notes/YYYY-MM-DD-meeting.md` - 過去の社内エンジニアリング、顧客などとの議論に関するメモ
- ...

## 関連する調査

[research/ 内の他の調査ドキュメントへのリンク]

## 未解決の質問

[さらなる調査が必要な領域]

  1. GitHub のパーマリンクを追加する（該当する場合）：

    • main ブランチ上にいるか、コミットがプッシュ済みかを確認します：git branch --show-current および git status
    • main/master ブランチ上にいるか、プッシュ済みの場合は、GitHub のパーマリンクを生成します：
      • リポジトリ情報を取得します：gh repo view --json owner,name
      • パーマリンクを作成します：https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}
    • ドキュメント内のローカルファイル参照をパーマリンクに置き換えます

  2. 調査結果を提示する：

    • 調査結果の簡潔な概要をユーザーに提示します
    • 簡単に参照できるよう、主要なファイルへの参照を含めます
    • 追加の質問や説明が必要かどうかを尋ねます

  3. 追加質問に対応する：

  • ユーザーから追加の質問があった場合は、同じ調査ドキュメントに追記します
  • 更新内容を反映するよう、frontmatter の last_updated と last_updated_by フィールドを更新します
  • frontmatter に last_updated_note: "Added follow-up research for [brief description]" を追加します
  • 新しいセクションを追加します：## Follow-up Research [timestamp]
  • 追加調査に必要に応じて、新しいサブエージェントを起動します
  • ドキュメントの更新と同期を続けます

重要な注意事項：

  • この段階では、何も実装しないでください。包括的な調査ドキュメントを作成するだけです

  • 効率を最大化し、コンテキストの使用を最小化するため、必ず複数の Task エージェントを並行して使用してください

  • 常にコードベースを新たに調査してください。既存の調査ドキュメントだけに頼ってはいけません

  • research/ ディレクトリは、現状の調査結果を補足するための過去の情報を提供します

  • 開発者が参照できるよう、具体的なファイルパスと行番号を見つけることに注力してください

  • 調査ドキュメントは、必要なコンテキストをすべて含む自己完結型にしてください

  • 各サブエージェントへの指示は、読み取り専用のドキュメント作成作業に絞り、具体的にしてください

  • コンポーネント間のつながりと、システムの相互作用を記録してください

  • 調査を実施した時期を記載してください

  • 可能な場合は、恒久的な参照として GitHub へのリンクを追加してください

  • メインエージェントは、詳細なファイル読み込みではなく、結果の統合に集中してください

  • サブエージェントには、現状の例や使用パターンを記録させてください

  • research/ ディレクトリ全体を調査してください。research サブディレクトリだけに限定してはいけません

  • 最重要：あなたとすべてのサブエージェントは評価者ではなく、記録者です

  • 忘れないでください：あるべき姿ではなく、現状を記録してください

  • 提案は禁止：コードベースの現状のみを記述してください

  • ファイルの読み込み：サブタスクを起動する前に、言及されているファイルを必ず全文（制限やオフセットなし）読み込んでください

  • 互換性に関する方針：質問を分解する前に、必ず breaking_changes_allowed を特定してください。これはプロジェクト／調査における単一の方針であり、互換性フラグの追加を求めるものではありません。これを基に、今後の作業において旧 API や互換シムが制約となるかを記録してください

  • 重要な順序：番号付きの手順に必ず従ってください

    • サブタスクを起動する前に、必ず記載されたファイルを読み込んでください（ステップ 1）
    • 質問を分解する前に、必ず互換性に関する方針を特定してください（ステップ 2）
    • 結果を統合する前に、必ずすべてのサブエージェントの完了を待ってください（ステップ 5）
    • ドキュメントを作成する前に、必ずメタデータを収集してください（ステップ 6 の一部）
    • プレースホルダーの値を残したまま調査ドキュメントを作成してはいけません

  • Frontmatter の一貫性：

    • 調査ドキュメントの先頭には必ず frontmatter を含めてください
    • すべての調査ドキュメントで frontmatter のフィールドを統一してください
    • 追加調査を追記する際は frontmatter を更新してください
    • 複数語のフィールド名には snake_case を使用してください（例：last_updated、git_commit）
    • タグは調査対象のトピックとコンポーネントに関連するものにしてください

最終成果物

  • 詳細な仕様書や設計ドキュメントの作成に利用できる、包括的な調査結果を含み、適切に書式設定・リンクされた調査ファイルの一式
  • 重要：research/ ディレクトリ外に、その他の成果物やファイルを生成してはいけません

コメント

Markdown 対応