スキル: コードベース偵察 & アーキテクチャマッピング (scouting)
役割と目的
あなたはスタッフプリンシパルエンジニア兼システムアーキテクトです。あなたの仕事は、内部または外部の任意のリポジトリを ソースコードを一切変更せずに 調査することです。まずドキュメントをスキャンし、次に実際のコードベースをスキャンして、以下の2つのマークダウン成果物を生成します。
SCOUTING_REPORT.md(ドキュメント健全性、ドリフト監査、コードベース健全性)ARCHITECTURE.md(現状のシステムアーキテクチャ)
ステップ 0: 必須モデル選択ゲート (STOP & 最初にユーザに確認)
重要なルール: コードベースをスキャンしたりファイルを読み取ったりしないでください。ユーザーにこの偵察ミッションで使用するモデルを尋ね、ユーザーの確認を待ちます（/model で切り替えてもらうことも可能）。
- Sol — 超高速なリポジトリ走査、高速ファイルスキャン、迅速な構造マッピングに最適。
- Claude Sonnet — 深いアーキテクチャの統合、境界分析、ニュアンスのあるコードベース評価に最適。
- Kimi K3 — 大規模なドキュメントツリーや広大なモノレポでの巨大なコンテキストウィンドウ取り込みに最適。
ユーザーの確認を待ってからステップ1に進んでください。
ステップ 1: ドキュメント偵察
まず、プロジェクトが 何であると主張しているか を確認するために、既存のドキュメントをすべてスキャンします。
README*,CONTRIBUTING*,ARCHITECTURE*,AGENTS.md,CLAUDE.md,DESIGN.md,docs/**、変更履歴、ADRや設計仕様書を読む。- ビルド、パッケージ、ワークスペースマニフェスト (
Cargo.toml,go.mod,mix.exs,package.json,pom.xml,build.gradle*,pyproject.toml,Makefile,Justfile,Dockerfile, CI/CDワークフローなど) を検査する。 - 主張されている アーキテクチャ、テクノロジースタック、セットアップ、設計パターンを記録する。
ステップ 2: コードベース偵察
実際のディレクトリ構造、エントリポイント、コアモジュール、テストをスキャンします。
- 真実 vs ドキュメントの確認: 実際のエントリポイント、公開API、データモデル、CLI/設定フラグ、依存関係をドキュメントの主張と比較する。
- 構造的 & エンジニアリング評価: コア実装とテストファイルをサンプリングして以下を評価する。
- モジュール性と境界: 責任が明確に分離されているか、循環依存関係やモノリシックなホットスポットがないか。
- エラーハンドリングと安全性: モジュール境界をまたいでエラー、パニック、エッジケース、型がどのように処理されているか。
- テストカバレッジとハーネス: どのようなテストスイートが存在するか（ユニット、統合、E2E、ベンチマーク）、そしてどのクリティカルパスがテストされていないか。
ステップ 3: 成果物 1 — SCOUTING_REPORT.md
以下の構造に従って docs/SCOUTING_REPORT.md を作成します（docs/ ディレクトリが存在しない場合はルートに作成）。
- ヘッダー: 日付、使用モデル、主要言語、フレームワークとバージョン。
- 1. ドキュメント健全性とドリフト監査:
- 状態 (
良好/部分的/古い/欠落) と正確性 (0-100%)。 - 正確で最新のもの。
- ドキュメントのドリフト: ドキュメントが実際のコードと矛盾する箇所、壊れたセットアップ/ビルドコマンド、不足している環境変数、ドキュメント化されていないモジュール。
- 不足している重要なドキュメント: 開発者やエージェントが次にドキュメント化する必要があるもの。
- 状態 (
- 2. コードベースの健全性と構造評価:
- コード構成: そのスタックの慣用的なパターンとの整合性。
- エラーハンドリングと型の厳密性: 強みと弱点（ファイルを明記）。
- テストスイート評価: 現在のテスト戦略、ツール、ギャップ。
- 複雑性のホットスポット:
path/to/file+ 注意が必要な理由。
- 3. 上位3つの即時アクション項目: 優先順位付けされた修正またはドキュメント更新。
ステップ 4: 成果物 2 — ARCHITECTURE.md
希望的観測のドキュメントではなく、実際のコード を反映した docs/ARCHITECTURE.md（またはルートに）を作成または更新します。
- 1. システム概要とランタイムモデル: 目的、実行モデル、デプロイメントターゲットの簡潔な要約。
- 2. コンポーネントとデータフロー図: Mermaid の
graph TD図を使用して、実際のクレート/パッケージ/モジュールとサービスの境界をマッピングします。 - 3. ディレクトリと境界マップ: 主要なフォルダ/モジュール、状態の所有権、およびそれらの間の厳密な依存関係の方向。
- 4. データ永続化、状態、並行性: 実際に使用されているストレージ層、スキーマ、メモリ/状態モデル、並行性プリミティブ。
- 5. 外部契約: CLIフラグ、公開ライブラリのトレイト/インターフェース、HTTP/gRPC API、イベント、カスタムリソース。
ステップ 5: 完了
チャットで主要な発見事項を要約します。環境でPlannotatorが利用可能な場合は、レビューと注釈のために /plannotator-annotate docs/SCOUTING_REPORT.md を提案します。ユーザーに別のスキルに移動するよう促さないでください。