file-analysis

ファイル分析

使用する場合

• モジュール境界とファイル構成を把握するため、アーキテクチャレビューの前に使用します。
• 変更を加える前に構造を把握するため、初めて扱うコードベースを調査するときに使用します。
• リファクタリングや移行作業のスコープ見積もりの材料として使用します。

使用しない場合

• 一般的なコードの調査には、Explore エージェントを使用します
• 特定のパターンの検索には、Grep を直接使用します

必須の TodoWrite 項目

1. file-analysis:root-identified
2. file-analysis:structure-mapped
3. file-analysis:patterns-detected
4. file-analysis:hotspots-noted

各ステップを終えたら、対応する項目を完了としてマークします。

ステップ 1：ルートを特定する（file-analysis:root-identified）

• pwd で分析ルートディレクトリを確認します。
• モノレポの境界、ワークスペースのルート、サブプロジェクトのパスを記録します。
• マニフェストファイル（package.json、Cargo.toml、pyproject.toml など）からプロジェクトの種類（言語、フレームワーク）を把握します。

ステップ 2：構造をマッピングする（file-analysis:structure-mapped）

• tree -L 2 -d または find . -type d -maxdepth 2 を実行して、最上位のディレクトリ構成を把握します。
• 標準的なディレクトリ（src/、lib/、tests/、docs/、scripts/、configs/）を特定します。
• 後続の分析に影響する可能性がある、標準とは異なる構成パターンを記録します。

ステップ 3：パターンを検出する（file-analysis:patterns-detected）

• find . -name "*.ext" -not -path "*/.venv/*" -not -path "*/__pycache__/*" -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l を使用して、拡張子ごとにファイル数を数えます。
• 主な言語と、それぞれのファイル分布を特定します。
• 設定ファイル、生成ファイル、ベンダー依存関係を記録します。
• wc -l $(find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" -not -path "*/node_modules/*" -not -path "*/.git/*" -name "*.py" -o -name "*.rs" | head -20) を実行して、ファイルサイズをサンプル調査します。

ステップ 4：ホットスポットを記録する（file-analysis:hotspots-noted）

• 大きなファイル（「神オブジェクト」の可能性があるもの）を特定します：find . -type f -exec wc -l {} + | sort -rn | head -10。
• 複雑さを示している可能性のある、深くネストされたディレクトリに印を付けます。
• 通常とは異なる命名規則や配置のファイルを記録します。

完了条件

• TodoWrite の項目が、具体的な所見をもって完了していること。
• 後続のワークフロー（アーキテクチャレビュー、リファクタリング）で参照できる構造情報が整っていること。
• ファイル数、ディレクトリ構成、ホットスポットが、参照用に記録されていること。