project-architecture-report

プロジェクトアーキテクチャレポート

プロジェクトを分析し、役立つHTMLファイルを作成します。レポートを読めば、存在するもの、その仕組み、問題点、今後コードベースで必要になりそうなことをすばやく把握できます。

クイックスタート

同梱のインベントリスクリプトを実行し、調査結果をスタンドアロンのHTMLレポートにまとめます。

node scripts/project-inventory.mjs --root /path/to/project --out .scratch/project-inventory.json

デフォルトのレポートパス：.scratch/project-architecture-report.html

ワークフロー

1. 対象範囲とレポートパスを定義します。指定がない場合は、現在のリポジトリを調査して.scratch/project-architecture-report.htmlに書き込みます。
2. ローカルの信頼できる情報を読みます：AGENTS.md、CLAUDE.md、README.md、CONTEXT.md、ADR、マニフェスト、環境設定のサンプル、CI、テスト、デプロイ設定、ドキュメント、チケットやPRDの成果物。
3. project-inventory.mjsを実行します。利用できる場合は、プロジェクト固有のマップも追加します：ルート一覧、DBスキーマ、OpenAPI／GraphQLスキーマ、マイグレーション履歴、パッケージグラフ、テストグラフ、ビルドグラフ、生成クライアント。
4. 有用であれば、広範な分析を独立したサブエージェントへの質問に分割します：構成／依存関係、ランタイムフロー、データ／ストレージ、UI／APIのサーフェス、テスト／ツール、リスク／ギャップの検出。親エージェントが最終レポートを担当し、矛盾を解消します。
5. エントリポイントから状態や副作用までフローを追跡します：ユーザーフロー、リクエストフロー、バックグラウンドジョブ、CLIコマンド、認証／セッション経路、ストレージへの書き込み、外部API、エラー経路。
6. 依存関係を特定します：ランタイム、開発／ビルド、内部パッケージ、生成コード、外部サービス、ブラウザー／ランタイムの前提、環境変数、隠れた運用上の結合。
7. データモデルを抽出します：永続化されるエンティティ、インメモリ状態、ファイル、キャッシュ、キュー、イベント、スキーマ、マイグレーション、検証ルール、所有者、ライフサイクル。
8. ユーザーが許可しない限り、外部依存なしでHTMLを作成します。CSS、目次、一覧しやすいカード／テーブル、単なるパスとしてのコードパスへのリンク、インラインのMermaidソースまたはシンプルなHTML／CSSのフローブロック、今後必要な改善の提案を含めます。
9. 検証します：レポートファイルが存在すること、ローカルで開けること、ローカルアセットへの参照にリンク切れがないこと、以下の必須セクションが含まれていること。

必須のHTMLセクション

• 概要：プロジェクトの目的、現在の構成、今後必要になりそうなこと
• アーキテクチャマップ：パッケージ、アプリ、エントリポイント、モジュール、所有者
• ランタイムフロー：主要なユーザー／リクエスト／ジョブ／CLIフロー
• データモデル：エンティティ、状態、永続化、スキーマ、ライフサイクル
• 依存関係：パッケージの依存関係、外部サービス、ツール、環境変数
• コードインベントリ：ファイル、シンボル、ルート、テスト、スクリプト、生成パス
• 問題点：重複、浅いモジュール、レガシー、テスト不足、リスクの高い結合
• ニーズマップ：維持／変更／削除、改善の単位、未解決の質問
• 付録：実行したコマンド、生成したインベントリのパス、前提、ギャップ

スタイル

簡潔さを保ちつつ、必要な情報はすべて含めます。文章よりも、正確なパス、テーブル、フローの手順を優先します。不確かな点にはNeeds evidenceと明記します。