familiarize

STARTER_CHARACTER = 🗺️

概要を把握する

ソースコードへの書き込みは禁止です。エージェントも使用しません。完了時に、読み取ったファイルとシンボルを一覧表示してください。

引数

ユーザーが調査対象のサブディレクトリまたはパスを指定した場合は、それを SCAN_TARGET として使用します。 対象が指定されていない場合は、プロジェクトのルート全体を調査します。

---

Step 1: スキャンルートを設定する

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

SCAN_TARGET が特定された場合は、サブディレクトリとして扱います：SCAN_ROOT=$PROJECT_ROOT/<SCAN_TARGET>。パスが存在しない場合は、その旨を報告して終了します。

SCAN_TARGET が指定されていない場合は、SCAN_ROOT=$PROJECT_ROOT とします。

続行する前に、スキャンルートを明示してください。

---

Step 2: Serena のセットアップ

2a. オンボーディングの確認

mcp__serena__check_onboarding_performed を呼び出します。

• ツールを呼び出せない場合は、SERENA=false に設定して Step 3 に進みます。
• オンボーディングがすでに完了している場合は、SERENA=true に設定します。
• オンボーディングが完了していない場合は、mcp__serena__onboarding を実行し、返された指示に従ってプロジェクトを調査し、メモリファイルを書き込みます。
• Serena の呼び出しでエラーが発生した場合は、SERENA=false に設定して続行します。

オンボーディングが完了またはスキップされたら、すぐに Step 2b に進みます。オンボーディングの指示で求められている範囲を超えて、調査やメモリへの書き込みを続けないでください。

2b. 既存のメモリを読み込む

SERENA=true の場合は、mcp__serena__list_memories を呼び出します。メモリが存在する場合は、それぞれを mcp__serena__read_memory で読み込みます。これらはプロジェクトに関する事前のコンテキストを提供します。

続行する前に、Serena が有効かどうかと、読み込んだメモリの数を明示してください。

---

Step 3: コンテキストドキュメント

3a. CLAUDE.md ファイル

SCAN_ROOT 以下にあるすべての CLAUDE.md ファイルを検索します（.git/ パスは除外）。それぞれを読み込みます。

find "$SCAN_ROOT" -name "CLAUDE.md" -not -path "*/.git/*" -not -path "*/node_modules/*"

3b. .llmdocs/ ディレクトリ

SCAN_ROOT 以下にあるすべての .llmdocs/ ディレクトリを検索します。それぞれについて、すべての .md ファイルを読み込みます。

find "$SCAN_ROOT" -type d -name ".llmdocs" -not -path "*/.git/*"

次に、見つかった各ディレクトリについて：

ls "$LLMDOCS_DIR"/*.md

該当する各ファイルを読み込みます。

見つからない場合は、何も通知せずにスキップします。

3c. 最近のコミット

git log --oneline -20

---

Step 4: リポジトリのメタデータ

これらのファイルが SCAN_ROOT に存在する場合は、確認してそれぞれを読み込みます。存在しないファイルは、コメントせずにスキップします。

設定ファイル

• .envrc
• .env.example
• .gitignore
• .gitattributes

パッケージマニフェスト

• package.json
• pyproject.toml
• Cargo.toml
• go.mod
• Gemfile
• requirements.txt
• pom.xml
• build.gradle

ビルドおよびタスク設定

• Makefile
• Taskfile.yml
• justfile
• Rakefile

コンテナ

• Dockerfile（Dockerfile.* などのバリエーションを含む）
• docker-compose*.yml

IaC（ファイル名のみを一覧表示し、内容は読み込まない）

• terraform/*.tf
• serverless.yml
• sam-template.yaml

CI/CD（ファイル名のみを一覧表示し、内容は読み込まない）

• .github/workflows/*.yml
• .gitlab-ci.yml
• Jenkinsfile
• .circleci/config.yml

ドキュメント

• スキャンルートにある README.md

---

Step 5: コード構造

5a. ディレクトリツリー

ノイズとなるディレクトリを除外し、深さ 3 まで表示します：

find "$SCAN_ROOT" -maxdepth 3 \
  -not -path "*/.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/__pycache__/*" \
  -not -path "*/vendor/*" \
  -not -path "*/.terraform/*" \
  -not -path "*/.venv/*" \
  -not -path "*/venv/*" \
  -not -path "*/dist/*" \
  -not -path "*/build/*" \
  -not -path "*/.next/*" \
  -not -path "*/target/*" \
  | sort

5b. エントリーポイントのシンボル

ファイル名のパターンに基づいて、SCAN_ROOT 以下のエントリーポイントファイルを特定します：

• main.*、index.*、app.*、cli.*
• __main__.py
• cmd/*/main.go
• src/lib.rs、src/main.rs
• server.*、handler.*

一致するものを最大 5 件集めます。スキャンルートに近いファイルを優先してください。

SERENA=true の場合：各一致ファイルに対して、depth: 2 を指定して mcp__serena__get_symbols_overview を実行します。これにより、トップレベルのシンボルとその子要素（メソッド、属性、ネストされた型）が返されます。ファイルからシンボルが返された場合は記録し、そのファイルに対する bash の代替処理はスキップします。次に、最も重要なエントリー関数を 1～2 個（例：main、run、createApp、setup）選び、include_body: true を指定して mcp__serena__find_symbol を呼び出し、その実装を読み取ります。これにより、初期化の順序、依存関係の接続、起動フローが明らかになります。

SERENA=false の場合、または Serena がファイルに対して空の結果を返した場合やエラーになった場合は、そのファイルの先頭 80 行を読み込みます。

5c. アーキテクチャシンボルの検索（Serena のみ）

SERENA=false の場合は、この手順をスキップします。

mcp__serena__find_symbol を使用して、一般的なアーキテクチャシンボルを探します。relative_path パラメーターで、各検索の範囲を SCAN_ROOT に限定します。include_body: false と depth: 1 を使用します。

次の name_path_pattern の値を検索します（結果がないものはスキップします）。

• main
• app
• server
• router
• handler
• config
• middleware
• schema
• model

find_symbol の呼び出しは合計 10 回までに制限します。アーキテクチャの構造が明らかになったら、そこで終了します。

見つかったシンボルのうち、最も関連性の高い 2～3 個（複数のファイルに出現するシンボルや、子要素が多いシンボル）について、必要に応じて mcp__serena__find_referencing_symbols を呼び出し、どの要素から呼び出されているかを調べます。このツールには、find_symbol の結果にある name_path（例：MyClass/my_method）と relative_path（シンボルが定義されているファイル）の両方が必要です。参照の検索は 3 回までに制限します。

5d. ソースファイルのシンボルマッピング

5a のディレクトリツリーから、ソースディレクトリ（設定ファイル、ドキュメント、テストではなく、ソースファイルを含むディレクトリ）を特定します。

SERENA=true の場合は、各ディレクトリにつき代表的なソースファイルを最大 5 つ選び、depth: 2 で mcp__serena__get_symbols_overview を実行します。クラス名、関数名、インターフェース名、メソッドシグネチャを記録します。ファイルからシンボルが返されない場合（未対応の言語、エラー）は、そのファイルについて bash に切り替えます。

SERENA=false の場合、または Serena がファイルに対して何も返さなかった場合は、先頭 80 行を読み取ります。

以下は、どちらの方法でもスキップします。

• テストファイル（*_test.*、*.test.*、*.spec.*、test_*）
• 生成ファイル（*.min.js、*_pb.go、*.generated.*、*.g.dart）
• ロックファイル（package-lock.json、yarn.lock、poetry.lock、Cargo.lock）

5e. 型とインターフェースの一覧

mcp__serena__find_symbol を使用して、主要な型定義を探します。次の name_path_pattern の値を検索し、include_body: false と depth: 1 を指定して、範囲を SCAN_ROOT に限定します。

• interface
• type
• enum
• struct
• dataclass
• schema
• dto

呼び出しは合計 7 回までに制限します。見つかった型のうち、特に中心的な 2～3 個（エントリーポイントで参照されている型、または複数のファイルに出現する型）については、include_body: true を指定して mcp__serena__find_symbol を呼び出し、定義全体を読み取ります。これにより、プロジェクトを支えるドメインモデルとデータ構造を把握できます。

SERENA=false の場合は、この手順をスキップします。

5f. テスト構成

5a のツリーから、テストディレクトリとファイルを特定します。

• test/、tests/、spec/、__tests__/ という名前のディレクトリ
• *_test.*、*.test.*、*.spec.*、test_* に一致するファイル

見つかったテストファイルをすべて列挙します。その後、代表的なテストファイルを 2～3 個選びます。

SERENA=true の場合：テスト関数名やクラス名を確認するため、depth: 1 で mcp__serena__get_symbols_overview を実行します。

SERENA=false の場合：先頭 60 行を読み取ります。

次の項目を記録します。使用しているテストフレームワーク（インポートやアサーションから推定）、テストの命名規則、テストがユニットテスト形式か統合テスト形式か、存在するテストユーティリティやフィクスチャ。

---

Step 6: レポート

次の 2 つのセクションを出力します。

読み取ったファイルとシンボル

読み取ったすべてのファイルと見つかったシンボルを、手順ごとにまとめて列挙します。Serena の結果については、ファイルパスと件数の概要（例：「クラス 3 件、関数 12 件、インターフェース 2 件」）を記載します。bash に切り替えて読み取ったファイルについては、ファイル名のみを記載します。

概要

読んだ内容全体に基づいて、プロジェクトを要約してください。以下の3つのセクションを順番に扱ってください。散文で合計10～14段落にしてください。概要内に箇条書きや見出しを入れないでください。

仕組み（技術的な説明）：

• プロジェクトが何をするか
• 技術スタックと主要な依存関係
• コードの構成（主要なディレクトリとそれぞれの役割）
• 公開 API の範囲と主要な抽象化（クラス、インターフェース、エクスポートされる関数）
• ドメインモデルと主要なデータ型（型／インターフェースの一覧に基づく）
• モジュール間の関係と依存関係の流れ（参照の検索結果とエントリーポイントの本体に基づく）
• コードで確認できる規約やパターン（命名、エラー処理、レイヤー構造）
• テスト戦略（フレームワーク、カバレッジの方針、テストの構成）

重要性（価値と目的）：

• プロジェクトがどのような問題を解決し、誰を対象としているか
• どのような代替手段があり、このプロジェクトはどう異なるか（README、ドキュメント、またはコードのパターンから推測してください）
• コードから見て取れるアーキテクチャ上のトレードオフ（何を優先し、何を後回しにしたか）
• 技術的負債や保守上のリスク（テスト不足、古い依存関係、不明確な境界など）
• 特筆すべき点、不足している点、不明確な点

使い方（利用開始方法）：

• ビルド方法（ビルドシステム、コンパイル手順、依存関係のインストール）
• 実行またはインストール方法（エントリーポイント、起動コマンド、デプロイ方法）
• テスト方法（テストフレームワーク、テストコマンド、テストの場所）
• 新しいコントリビューターに必要となる主なワークフロー（開発サイクル、一般的な作業）
• 設定項目と実行環境の要件

レポートの後、指示を待ってください。