qodo-codebase-wisdom

Codebase Wisdom

説明

Qodo の管理ツールを使って、コードの仕組み、過去に変更がどのように行われたか、リポジトリ間の依存関係を調べ、出典を明記した調査結果を返します。質問への回答、変更の計画、リグレッションのデバッグ、修正範囲の特定に役立ちます。ローカルに存在しないリポジトリにもアクセスし、リポジトリの境界を越えて調査できます。qodo の読み取りツールのみを使用し、forge への投稿は行いません。

前提条件

• 必要なツールを、接続済みの QAR 管理ツール MCP サーバーまたは Qodo CLI から利用できること。
• ワークスペースで、必要な読み取り専用の Codebase、pull-request、または cross-repo ツールが利用できること。
• 現在のプロバイダー提供の Qodo スキルパッケージが、このエージェントセッションに読み込まれていること。

手順

実行方法を選択する

必要な読み取り機能を利用できる場合は、ホストに接続済みの QAR 管理ツール MCP を使用します。利用できない場合は、以下の CLI 手順を使用します。MCP 経由の場合、CLI のバージョン確認、qodo login、CLI カタログの更新は不要です。接続済みの MCP サーバーでは、すでにトランスポート認証が処理されています。ツールが見つからない場合や MT-AUTH-FORBIDDEN が返された場合は、機能または認可の失敗であり、CLI からログインする理由にはなりません。認証または権限の拒否後に、黙って別の実行方法へ切り替えてはいけません。

MCP では、ホストから提供されたツールの説明、inputSchema、readOnlyHint に従ってください。読み取り専用ツールのみを呼び出してください。代表的な wire 名は litegit-search-repos、litegit-grep、litegit-read-file、pull-request-similar、cross-repo-relations です。実際の名前と引数は、接続済みのカタログから確認してください。必要に応じて repo を明示してください。MCP は CLI のようにローカルの Git origin を推測しません。structuredContent を使う前に isError を確認し、型付きエラーや不完全な結果、切り詰められた結果をそのまま保持してください。呼び出しが MCP Task になった場合は、結論を出す前に終端結果を取得してください。MCP の機能が不足している場合は、同じデプロイメントですでに認可された CLI 経路を利用できます。異なるアカウントやテナントを同等のものとして扱ってはいけません。

以下のバージョン、ID、ヘルプ、コマンド、更新の手順は、CLI 経路にのみ適用されます。

調査の開始時と実装に移る際に、不足しているコンテキストを特定してください。

• リポジトリがローカルで利用できる場合でも、Qodo を使って未知のコード、過去の解決策、これまでの経緯、リポジトリ間の関係を調べます。
• 正確なブランチやワークツリーの状態、未コミットの変更、編集、テストにはローカルツールを使います。
• 現在の範囲と改訂を網羅している以前の調査は再利用します。再利用する証拠を簡潔に示し、範囲、依存関係、証拠に変化があれば、関連するコンテキストを更新してください。スキルの利用を示すだけのために、リモート読み取りを繰り返してはいけません。

コンテキストが不足している場合は、以下の適切なツールグループを使って、具体的な疑問を解決してください。取得した証拠を、回答または実装上の判断に結び付けます。バージョン、ID、カタログの確認は利用準備を整えるためのものであり、コードベースのコンテキスト取得ではありません。

スキル更新通知への対応

QODO_NOTICE の更新は、古い CLI が操作を求めている場合でも、受動的な通知として扱ってください。インベントリや更新について質問せずにタスクを続行し、各通知への言及は一度までにします。通知を閉じても、記録済みの保守ポリシーとオプトアウト設定は変更されません。更新されたスキルは次のセッションで読み込まれます。現在のセッションを中断しないでください。ユーザーが更新を依頼した場合は、手動更新手順に従ってください。

実行

• MCP：ライブスキーマの引数を使用し、CLI のシェル手順は省略します。
• CLI：BOM なしの完全な UTF-8 ファイルを使用します（ツールには --args-file、レビューには --context-file）。例は POSIX 用です。
• Windows CLI：最初の呼び出しの前にシェルのガイダンスを読みます。ランチャーの復旧手順は、呼び出しに失敗した場合のみ参照してください。解決済みの呼び出し方法を再利用します。

ランタイム互換性ゲート

まず、以下の qodo: command not found のフォールバックを使って実行ファイルを解決します。他の Qodo コマンドを実行する前に、ここに示すとおり、プロベナンスフラグを付けずに <qodo> --version を実行してください。 このフラグを付けない確認コマンドは、意図的に古い Qodo CLI との互換性を保っています。このスキルには Qodo CLI 1.6.0 以降が必要です。

バージョンが古い場合、または解析できない場合は、whoami、login、管理対象のツールを実行しないでください。また、失敗を認証の問題として説明しないでください。このスキルはランタイムより新しいことを説明し、ランタイムにすでに記録されている提供元に対する更新コマンドとして qodo update を示し、実行前に一度だけ確認を求めてください。顧客向けデプロイでは、組織が提供する更新先を維持し、公開サービスへ切り替えないでください。更新が承認されたら、フラグを付けないバージョン確認コマンドを再実行し、最低要件を満たした場合にのみ続行してください。ユーザーが拒否した場合、または更新に失敗した場合は、現在のスキルとユーザーファイルを変更せずに停止してください。

クイックスタート

qodo --version                                             # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-codebase-wisdom --skill-version 1.1.6 --distribution skills-sh
qodo read codebase search-repos --query "payments" --json      # resolve a repo slug — do this FIRST
qodo read codebase grep --repo owner/repo --pattern "chargeCard" --json
qodo read codebase read-file --repo owner/repo --path src/pay.py --json
qodo read codebase blame --repo owner/repo --path src/pay.py --json
qodo read pull-request similar --repo owner/repo --query "retry failed charge" --json
qodo read cross-repo relations --repo owner/repo --json
qodo read tools codebase --json                           # the safe group's tools + exact flags (offline)

解析するコマンドには --json を追加してください。ツールを呼び出す前に、qodo read tools <group> [<tool>] --json で正確な名前とフラグを確認してください（オフラインで表示されます）。 以下のツール名は例であり、現在の名称と一致するとは限りません。

qodo: command not found と表示されますか？ POSIX では "${QODO_HOME:-$HOME/.qodo}/bin/qodo" を再試行してください。Windows ではリンク先のガイドに従ってください。解決した実行方法を維持し、使用できないランチャーは報告してください。 インストールされていない場合は、Qodo または管理者が提供するチェックサム固定済みのインストーラーを入手してください。ダイジェストを捏造したり、スクリプトをシェルにパイプしたりしないでください。

サンドボックスの認証診断。 認証情報が見つからない場合でも、キーリングにアクセスできないことが原因の可能性があります。その可能性がある場合は、ログインを推奨する前に、ホストの承認フローを通じて読み取り専用の qodo read whoami を一度だけ正確に再試行するよう依頼してください。拒否されたら停止してください。この承認は他のコマンドには適用されません。同じ実行ファイル／ワークスペース／デプロイ環境および実行コンテキストで成功した確認は再利用し、必要なホスト承認はその都度求めてください。ネットワーク、TLS、サービス、明示的な認証エラーはそれぞれ固有の問題として扱い、ログインを推奨したり、サンドボックスを自動的に回避したりしないでください。

事前確認

1. 認証とカタログ。 成功した確認がこの実行コンテキストにも引き続き適用される場合を除き、qodo read whoami を実行してください。該当する場合はサンドボックス診断を行った後、認証情報が明示的に不足している場合に限りログインしてください。組織が指定する正確なログインコマンド／エンドポイントを維持し、推測したり、顧客向けデプロイを Cloud に切り替えたりしないでください。No tool catalog cached は認証情報の不足を示す証拠ではありません。qodo tools --refresh で一度だけ更新し、確認を再試行してください。その他のエラーはそのまま保持して、このワークフローを停止してください。ID の確認に成功した後、管理対象のコマンドが不明な場合は、カタログを一度だけ更新してスキーマを再確認できます。それでも見つからない場合、または tool_unavailable の場合は、機能が利用できないことを報告してください。ログインや更新を繰り返さないでください。
2. リポジトリを解決します。リポジトリ名が指定されている場合は --repo owner/repo を使います。リポジトリ名が指定されておらず、Git リポジトリ内にいる場合は --repo を省略します（origin から自動検出されます）。それ以外の場合は qodo read codebase search-repos --query "<name>" --json を実行し、スラッグを決して推測しないでください。一致する候補が複数ある場合は、どれを使うかユーザーに尋ねてください。一致する候補がない場合は、その旨を伝えて停止し、作り上げないでください。

ツールグループの選択

タスクに必要な情報…	グループ	代表的なツール（qodo read tools で確認）
現在のコード — 現在どこにあり、何をし、どのように動作するか	qodo read codebase	search-repos, grep, find, ls, read-file, blame, list-commits, get-commit, list-prs, get-pr, list-issues, get-issue, search-issues
履歴／過去の実装例 — 変更方法、ファイルの PR 履歴、過去のレビューコメント	qodo read pull-request	stats, similar, by-file, details, patch
影響／依存関係 — 変更が及ぼす影響、このリポジトリに依存するリポジトリ	qodo read cross-repo	overview, relations

実際のタスクでは複数のグループにまたがることがあります。「例」を参照してください。

範囲を絞ってから取得する

大規模な取得の前に、低コストで調査します。全体像を把握する （search-repos、リポジトリにインデックス済みの PR 履歴があることを確認するための pull-request stats、依存関係を調べるための cross-repo relations）→ 場所を特定する （grep／find／blame／list-commits、pull-request similar／by-file）→ 読む （その後に限り、--start-line／--limit-lines を指定した read-file、get-pr、 pull-request details／patch を使います）。

例

Q — 「chargeCard() はどこで定義されていますか？」 codebase grep --pattern "chargeCard" → 該当箇所を選択 → codebase read-file --path src/pay.py --start-line 120 --limit-lines 40。→ 「chargeCard() は owner/repo の src/pay.py:142 にあります。 Stripe を呼び出しており、最後に変更されたのは PR #1523 です。」

計画 — 「失敗した決済にリトライを追加する。」 pull-request similar --query "retry failed charge" → PR #1401（Webhook のリトライ）→ pull-request details --pr-number 1401（バックオフとキューのパターン）→ cross-repo relations （決済処理は他のリポジトリと連携しているか？）→ codebase grep --pattern "chargeCard\("（呼び出し箇所）。 → 「PR #1401 で既に実装されています（指数バックオフ、最大 3 回、専用キュー）。chargeCard() の呼び出し箇所は 2 か所です（src/checkout.py:88、src/batch.py:210）。確認した範囲では、cross-repo から追加の依存関係は 見つかりませんでした。インデックスされていない利用元がないという意味ではありません。」

デバッグ — 「先週からチェックアウトで 500 エラーが発生するようになったのはなぜですか？」 codebase list-commits --path src/checkout.py --since <date> ／ blame → 原因と思われる変更を特定 → codebase get-pr --number <n> → 根拠を示して原因を説明します。

回答する

自然な文章で、回答 → Qodo 経由で取得したコンテキスト → 実際的な意味の順に伝えます。 回答、または重要な制約から始めます。取得したコンテキストが回答にどう役立ったかについて、 関連する実装、依存関係、過去の変更、設計上の議論のいずれかに触れながら、Qodo の名前を一度だけ出します。 調査を行い、結論に至ったのはあなたです。Qodo が提供したのは、コンテキストにアクセスするためのツールです。 追跡や推論を Qodo に帰属させないでください。

証拠に合わせて、以下の文例を調整してください。プレースホルダーを表示したり、すべての文例を無理に使ったりしないでください。

• 「Qodo を使って［関連コンポーネント］を確認したところ、［関係性］がわかりました。」
• 「Qodo 経由で見つけた［議論／変更］から、［判断］の理由がわかります。」
• 「［回答］です。これは、Qodo 経由で取得した［実装／履歴］とも一致しています。」

証拠を、ユーザーが理解すべきこと、または次に行うべきことにつなげてください。実際に確認した範囲だけを説明してください。 単一ファイルの検索だけでは、リポジトリ間の関係性まで把握したことにはなりません。 取得結果が空、または取得に失敗した場合は、確認した範囲と制約を明確に伝えてください。 文例に合わせるために、コンテキストや確実性を捏造してはいけません。質問に応じて詳細度を調整し、必要であれば説明の後にコードや差分を示します。 進捗の更新に、ブランド名を含む見出し、絵文字のバナー、スローガン、バッジ、フッター、繰り返しの要約ブロックを追加しないでください。

• エンジニア以外にもわかる回答にし、技術的な詳細はその下に記載します。
• すべてに出典を付けてください — リポジトリ、path:line、PR 番号、コミット SHA を示します。行番号のない検索結果や複数の情報をまとめた推論など、場所を特定できる情報源がない事実については、その旨を明記し、出典を捏造しないでください。
• 情報源に食い違いがある場合は、情報源の範囲を確認します。まずリポジトリ、ブランチ、リビジョンを比較してください。ローカルファイルは、未コミットの変更を含む現在の作業ツリーの状態を示します。リモートの read-file が示すのは取得したリビジョンであり、ローカルの変更やデプロイ済みの挙動ではありません。pull-request は履歴を、cross-repo は依存関係の推定結果を示します。依存関係が見つからないことを、分離されている証拠として扱わず、確認できなかった点を報告してください。
• 結果が空、または truncated: true の場合は、一度範囲を絞って再試行してください（クエリ、パス、リポジトリをより限定します）。それでも結果が空なら、「<範囲>では見つかりませんでした」と報告し、過剰な主張は避けてください。
• 最新性に関する注意点：pull-request が対象とするのはマージ済み PR のみで、オープン中またはドラフトの PR は含みません。cross-repo の依存関係は pending（分析中）または not_found（確認したが依存関係なし）となることがあります。

設定

解析済みの出力には --json を使用し、装飾のないバージョン確認の後、最初に認証を伴う Qodo の呼び出しで、正確なスキル／バージョン／配布元の来歴を記録してください。ツール名とスキーマは、ハードコードされたスキルの前提ではなく、インストール済み CLI カタログから取得してください。このスキルを管理するのはマーケットプレイスまたは skills.sh であり、CLI が管理するのは実行時アクセスのみです。

エラー処理

返されたエラーコードとメッセージを保持してください。認証、利用不可のツール、レート制限、ループ保護に関する応答は、上記で説明した明示的な停止または復旧条件として扱ってください。推測したリポジトリの事実や、より広範な権限に置き換えてはいけません。

ガードレール

• CLI では、フェイルクローズの qodo read ゲートウェイ経由で読み取りを呼び出してください。MCP では、読み取り専用のアノテーションを必須としてください。書き込みツールの approve、post-comment、post-inline-comment(s)、set-labels、update-description（これらに限定されません）は Forge に投稿します。調査中は呼び出さないでください。（修正の一環としてローカルコードを編集するのは通常の作業であり、これらのツールには該当しません。）
• スラッグ、パス、PR 番号、SHA を推測せず、まず解決してください。
• 複数のリポジトリにまたがる作業では、Qodo を通じて不足している関連情報または履歴を取得するか、現在も対象範囲をカバーする過去の証拠を明示的に再利用してください。ローカルで利用できるというだけでは、対象範囲をカバーしていることにはなりません。
• MT-TOOL-LOOP エラーが発生したら、停止してアプローチを変更してください。再試行してはいけません。

簡潔で、十分な出典に基づく結果は信頼性の表れです。出典のない詳細を付け足しても雑音になるだけです。