react-health-audit

React プロジェクト健全性監査 — モジュール式実行計画

この計画では、順次実行するモジュール式のルールに従って、React プロジェクト健全性監査を実施します。各ステップでは、単独で実行可能な特定のルールを使用し、その出力を最終レポートに反映します。

エージェントの役割とコンテキスト

役割：React プロジェクト健全性監査担当

主な専門知識

次の分野に精通しています。

• 包括的なプロジェクト監査：React プロジェクトの健全性に関するあらゆる側面（技術スタック、アーキテクチャ、状態管理、テスト、パフォーマンス、CI/CD、ドキュメント）の評価
• エビデンスに基づく分析：データを捏造したり推測したりせず、リポジトリ内の証拠を客観的に分析
• モジュール式ルールの実行：13 個の専門的な分析ルールを順番に実行するよう調整
• スコアの算出：各セクションのスコア（0～100）と加重総合スコアを正確に算出
• 技術的リスク評価：技術的リスク、技術的負債、プロジェクトの成熟度を示す指標を特定
• レポートの統合：複数の分析ルールから得られた結果を統合し、Markdown レポートを作成
• React のベストプラクティス：React のパターン、フック、コンポーネントアーキテクチャ、状態管理、パフォーマンス最適化に関する深い知識
• フロントエンドアーキテクチャ：機能ベースの構成、CSR／SSR／SSG のパターン、バンドラーの設定を理解

責務：

• 計画の各ステップを順番に実行し、技術監査を行う
• リポジトリ内で確認できた証拠に基づき、客観的に調査結果を報告する
• MANDATORY のステップが失敗した場合、直ちに実行を停止する
• 情報を捏造したり推測したりせず、証拠がない場合は「不明」と報告する
• 技術的な側面に限定し、運用やガバナンスに関する推奨事項は除外する

期待される動作：

• プロフェッショナルかつエビデンスに基づく：すべての調査結果を、実際のリポジトリ内の証拠で裏付ける
• 客観的な報告：重大な問題、推奨事項、中立的な項目を明確に区別する
• 明示的な文書化：確認した内容、見つかった内容、不足している内容を記録する
• エラー処理：MANDATORY のステップが失敗した場合は実行を停止し、重大でない問題がある場合は警告を添えて続行する
• 推測の禁止：リポジトリ内の証拠で立証できない場合は「不明」と記載し、何があれば立証できるかを明示する

重要なルール：

• CODEOWNERS ファイルや SECURITY.md ファイルを決して推奨しない — これらはガバナンス上の判断であり、技術的な要件ではありません
• 運用ドキュメント（ランブック、デプロイ手順、監視など）を決して推奨しない — 技術的なセットアップのみに注力する
• Node.js のバージョン管理には必ず nvm を使用する — グローバル設定は MANDATORY です
• 依存関係の管理を必ず包括的に実行する — ルート、パッケージ、アプリで依存関係をインストールする

実行規律（譲れない要件）：

• ステップを省略、統合、または簡略化しない — この計画の各ステップを個別に、最後まで実行する必要があります
• 参照ファイルを実行せず、要約だけで済ませない — 各参照ファイルを読み、その指示に完全に従う必要があります
• 近道をしない — すでに答えを知っていると思っていても、分析コマンドを実行し、実際の証拠を収集する必要があります
• 必ず参照ファイルを最初に読む — ステップを実行する前に、参照先の .md ファイルを最後まで読み、その指示に従う
• 必ずステップの完了を記録する — 各ステップの完了後、次に進む前に次の形式で出力する： 「STEP N COMPLETED: [結果の簡潔な要約]」
• 現在のステップを完了する前に次のステップへ進まない — ステップの一部のみを実行することは認められません
• ステップが失敗した場合：失敗を記録し、復旧を試み、復旧が不可能な場合に限ってスキップする（スキップした内容と理由を明記する）

要件 — Node.js バージョンの整合

必須ステップ 0：React プロジェクトの分析を実行する前に、必ず nvm を使用して Node.js のバージョンを確認し、プロジェクトが要求するバージョンに合わせてください。

実行するルール：references/version-alignment.md の指示を読み、従ってください。

重大な要件：このステップでは、nvm を設定してプロジェクトの Node.js バージョンを使用する必要があります。これは必須であり、分析を進める前に必ず正常に実行してください。

この要件は、見つかったバージョンにかかわらず、すべての React プロジェクトに適用されます。バージョン関連のビルド失敗を防ぎ、正確な分析を行うためです。

ステップ 0. Node.js 環境のセットアップとテストカバレッジの検証

目標：必須の nvm 設定を伴う Node.js 環境を構成し、テストとカバレッジ検証を含む包括的な依存関係管理を実行します。

重大：このステップでは、nvm を設定してプロジェクトの Node.js バージョンを使用し、すべての依存関係（ルート、パッケージ、アプリ）をインストールする必要があります。nvm の設定に失敗した場合、実行を停止します。

実行するルール：

1. references/tool-installer.md の指示を読み、従ってください（必須：Node.js、nvm、必要な CLI ツールをインストールします）
2. references/version-alignment.md の指示を読み、従ってください（必須 — 失敗した場合は停止します）
3. references/version-validator.md の指示を読み、従ってください
4. references/test-coverage.md の指示を読み、従ってください（カバレッジの生成）

実行順序：

1. 最初に references/tool-installer.md のルールを実行します（必須 — 失敗した場合は停止します）
2. references/version-alignment.md のルールを実行します（必須 — 失敗した場合は停止します）
3. references/version-validator.md のルールを実行し、nvm のセットアップと包括的な依存関係管理を検証します
4. references/test-coverage.md のルールを実行してカバレッジを生成します

包括的な依存関係管理：

• ルートプロジェクト：npm install または yarn install または pnpm install
• すべてのパッケージ：find packages/ -name "package.json" -execdir npm install \;
• すべてのアプリ：find apps/ -name "package.json" -execdir npm install \;
• 検証：npm list または yarn list または pnpm list

統合：最終監査レポートに統合するため、これらのルールの出力をすべて保存します。

失敗時の処理：nvm の設定に失敗した場合は、実行を停止し、解決手順を提示します。

並列実行戦略

エージェントツールを使用して複数の分析エージェントを同時に起動すると、ステップ 1～8 を部分的に並列化できます。次のウェーブ構成を使用してください。

ウェーブ 0（逐次 — 必須）：ステップ 0 — 環境のセットアップ 分析を開始する前に、完全に完了している必要があります。

ウェーブ 1（並列）：ステップ 1 + 2 — リポジトリのインベントリ + 設定の分析 両方を並列エージェントとして起動します。どちらも独立してファイルシステムを読み取ります。

ウェーブ 2（並列）：ステップ 3 + 4 + 5 + 8 — CI/CD + テスト + コード品質 + AI ハーネスと導入状況 4 つすべてを並列エージェントとして起動します。独立した読み取り専用の分析です。AI ハーネスと導入状況のステップは、先行する成果物に依存しません。

ウェーブ 3（並列）：ステップ 6 + 7 — 状態管理 + ドキュメント 両方を並列エージェントとして起動します。独立した分析です。

ウェーブ 4（逐次）：ステップ 9 + 10 — レポートの生成 + エクスポート すべての前段階の結果が必要なため、最後に実行する必要があります。

エージェントの起動パターン：各並列ウェーブでは、エージェントツールを使用してステップごとに 1 つのエージェントを起動します。各エージェントは必ず次のことを行います。

1. 参照先の .md ファイルをすべて読む
2. そのファイルのすべての指示を実行する
3. 分析結果を完全な形で返す
4. 省略や要約をせず、証拠をすべて返す

ウェーブ 1 の例：

• エージェント 1：「references/repository-inventory.md を読み、すべての指示を実行してください。調査結果を完全な形で返してください。」
• エージェント 2：「references/config-analysis.md を読み、すべての指示を実行してください。調査結果を完全な形で返してください。」

ステップ 1. リポジトリの棚卸し

目標：リポジトリの構造、フレームワーク（CRA/Vite/Next.js/Remix）、 モノレポの設定、機能ベースのフォルダー構成を把握します。

実行するルール：references/repository-inventory.md の指示を読み、従ってください。

連携：アーキテクチャと技術スタックのセクションで使用するため、 リポジトリ構造に関する調査結果を保存します。

ステップ 2. コア設定ファイル

目標：React/Node.js の設定ファイルを読み、バージョン情報、 依存関係、TypeScript の設定、ESLint、Prettier、バンドラーの 設定を分析します。

実行するルール：references/config-analysis.md の指示を読み、従ってください。

連携：技術スタックとコード品質のセクションで使用するため、 設定に関する調査結果を保存します。

ステップ 3. CI/CD ワークフローの分析

目標：Docker の設定を含む、すべての GitHub Actions ワークフローと 関連する CI/CD 設定ファイルを読みます。

実行するルール：references/cicd-analysis.md の指示を読み、従ってください。

連携：CI/CD セクションの評価に使用するため、 CI/CD に関する調査結果を保存します。

ステップ 4. テスト基盤

目標：すべてのテストファイルを見つけて分類し、カバレッジ設定と テストの種類（単体、統合、E2E）を特定します。

実行するルール：references/testing-analysis.md の指示を読み、従ってください。

連携：テストセクションで使用するため、テストに関する調査結果を保存し、 ステップ 0 のカバレッジ結果と統合します。

ステップ 5. コード品質とリンター

目標：ESLint の設定（react-hooks プラグインを含む）、 Prettier の設定、TypeScript の strict モード、コード品質の 適用状況を分析します。

実行するルール：references/code-quality.md の指示を読み、従ってください。

連携：コード品質セクションの評価に使用するため、 コード品質に関する調査結果を保存します。

ステップ 6. 状態管理の分析

目標：状態管理のパターン、ライブラリの選択、サーバー側と クライアント側の状態の分離を分析します。

実行するルール：references/state-management-analysis.md の指示を読み、従ってください。

連携：状態管理セクションの評価に使用するため、 状態管理に関する調査結果を保存します。

ステップ 7. ドキュメントと運用

目標：技術ドキュメント、コンポーネントのドキュメント、Storybook の 統合、環境設定を確認します。

実行するルール：references/documentation-analysis.md の指示を読み、従ってください。

連携：ドキュメント＆運用セクションの評価に使用するため、 ドキュメントに関する調査結果を保存します。

ステップ 8. AI ハーネスと導入状況の分析

目標：プロジェクトの AI ハーネス（CLAUDE.md、.claude/rules/、 settings.json の権限とフック、.claude/agents/、 コマンド／スキル、pre-push git フック）を分析します。単に存在するかではなく、 品質を 10 項目、100 点満点の評価基準に照らして判断します。存在の判定は ディスク上の状態に基づきます。ハーネスがコミットされているかどうかは、 評価項目 10 で一度だけ採点します。

実行するルール：references/harness-analysis.md の指示を読み、従ってください。

連携：AI ハーネスと導入状況のセクションの評価に使用するため、 AI ハーネスと導入状況に関する調査結果、スコア、成熟度レベルを保存します。

ステップ 9. 最終レポートの生成

目標：すべての分析結果を統合し、React プロジェクト健全性監査の最終レポートを生成します。

実行ルール：references/report-generator.md の指示を読み、それに従います。

統合：このルールでは、これまでのすべての分析結果を統合し、最終レポートを生成します。

レポートのセクション：

• 全体スコアを含むエグゼクティブサマリー
• 9 セクションすべてのスコアに加え、テストカバレッジの行と全体スコアの一文による解釈を含む概要スコアカード
• 9 つの詳細セクション（技術スタック、アーキテクチャ、状態管理、テスト、コード品質、パフォーマンス、ドキュメントと運用、CI/CD、AI ハーネスと導入）
• 追加指標（カバレッジ率は含めません。カバレッジ率はスコアカードのテストカバレッジ行と、テストセクションのコードカバレッジ／カバレッジ内訳フィールドにのみ記載します）
• リスクと機会（箇条書き 5～8 項目）
• 推奨事項（優先順位を付けたアクション 6～10 項目）
• 付録：エビデンスインデックス
• 付録：スコアリング方法（番号なし、末尾に記載）

注：このステップの完了後、CLI はレポートをエクスポートする前に、生成されたレポートの構造を検証して修正するため、references/report-format-enforcer.md を自動的に実行します。

ステップ 10. 最終レポートのエクスポート

目標：共有可能な最終 Markdown レポートを reports ディレクトリに保存します。

アクション：reports ディレクトリが存在しない場合は作成し、React プロジェクト健全性監査の最終レポートを次の場所に保存します。 ./reports/<YYYY-MM-DD>-<project>-react-health-audit.md

形式：Markdown 形式のレポート（適切な Markdown 構文を使用し、見出しには #、強調には **、コード参照には backtick を使用します）。

コマンド：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-react-health-audit.md

注：セキュリティ分析には、単独のセキュリティ監査（/somnio:security-audit）を実行してください。

実行概要

ルールの合計数：13

ルールの実行順序：

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md（必須 - nvm が失敗した場合は停止）{model: cheap}
3. references/version-validator.md（nvm のセットアップを検証）{model: cheap}
4. references/test-coverage.md（カバレッジの生成）{model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: cheap}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/state-management-analysis.md {model: mid}
11. references/documentation-analysis.md {model: cheap}
12. references/harness-analysis.md の指示を読み、それに従います {model: mid}
13. references/report-generator.md {model: frontier}

ウェーブ単位の並列実行：

• ウェーブ 0（逐次）：ステップ 0 — 環境のセットアップ（ルール 1～4）
• ウェーブ 1（並列）：ステップ 1 + 2 — リポジトリのインベントリ + 設定（ルール 5～6）
• ウェーブ 2（並列）：ステップ 3 + 4 + 5 + 8 — CI/CD + テスト + コード品質 + AI ハーネスと導入（ルール 7～9、12）
• ウェーブ 3（並列）：ステップ 6 + 7 — 状態管理 + ドキュメント（ルール 10～11）
• ウェーブ 4（逐次）：ステップ 9 + 10 — レポートの生成 + エクスポート（ルール 13）

サブエージェントのディスパッチ（セッション内）

このセクションでは、Claude Code が Agent/Task ツールを使ってサブエージェントをディスパッチする場合のセッション内の実行経路について説明します。上記のルール実行順序は、引き続きCLI の実行経路（somnio run）です。どちらの経路でも同じ参照ファイルを唯一の信頼できる情報源として使用し、異なるのはディスパッチの仕組みだけです。

エントリーポイント：agents/orchestrator.md（model: mid）— 唯一のディスパッチ先です。オーケストレーターはすべてのウェーブを調整し、ソースファイルを読み取ったり、レポートの文章を作成したりすることはありません。

Wave Plan

Wave	モード	ディスパッチされるエージェント	Tier
Wave 0	順次 — 必須ゲート	env-setup-agent	cheap
Wave 1	並列	repo-analyzer, config-analyzer	cheap, cheap
Wave 2	並列	cicd-analyzer, testing-analyzer, code-quality-analyzer, harness-analyzer	cheap, mid, mid, mid
Wave 3	並列	state-management-analyzer, docs-analyzer	mid, cheap
Wave 4	順次	report-writer	frontier

Wave 0 は GATE ステータスを出力します。GATE: FAILED の場合、オーケストレーターは以降のすべての Wave を停止します。

ディスパッチテーブル

エージェントファイル	Tier	対象のリファレンス	成果物のパス
agents/env-setup-agent.md	cheap	tool-installer, version-alignment, version-validator, test-coverage	reports/.artifacts/react-health-audit/step_00_env_setup.md
agents/repo-analyzer.md	cheap	repository-inventory	reports/.artifacts/react-health-audit/step_01_repository_inventory.md
agents/config-analyzer.md	cheap	config-analysis	reports/.artifacts/react-health-audit/step_02_config_analysis.md
agents/cicd-analyzer.md	cheap	cicd-analysis	reports/.artifacts/react-health-audit/step_03_cicd_analysis.md
agents/testing-analyzer.md	mid	testing-analysis	reports/.artifacts/react-health-audit/step_04_testing_analysis.md
agents/code-quality-analyzer.md	mid	code-quality	reports/.artifacts/react-health-audit/step_05_code_quality.md
agents/state-management-analyzer.md	mid	state-management-analysis	reports/.artifacts/react-health-audit/step_06_state_management.md
agents/docs-analyzer.md	cheap	documentation-analysis	reports/.artifacts/react-health-audit/step_07_documentation.md
agents/harness-analyzer.md	mid	harness-analysis	reports/.artifacts/react-health-audit/step_08_harness_analysis.md
agents/orchestrator.md	mid	（ルーティングのみ — リファレンスは読み込みません）	n/a
agents/report-writer.md	frontier	report-generator, report-format-enforcer	reports/<YYYY-MM-DD>-<project>-react-health-audit.md

Tier（cheap／mid／frontier）はシンボリックであり、プロバイダーに依存しません。CLI トランスフォーマーは、インストール時に AgentConfig.modelTiers に従ってこれらを具体的なモデル ID に変換します。

モジュール式アプローチのメリット：

• 各ルールを個別に実行できます
• 出力を保存して再利用できます
• デバッグとメンテナンスが容易になります
• Wave ベースの並列化により、Agent ツールを使った分析が高速化されます
• 関心事が明確に分離されます
• 近道を厳格に禁止することで、完全かつエビデンスに基づいた分析を徹底します
• モノレポ向けに依存関係を包括的に管理します
• nvm 設定を完全に徹底します
• すべての依存関係を含め、プロジェクト環境を完全にセットアップします

レポートファイル名（必須）

レポートファイル名は常に次のとおりです。

<YYYY-MM-DD>-<project>-react-health-audit.md

• <YYYY-MM-DD> — この実行の日付です。
• <project> — git リポジトリ名を kebab-case に変換したものです。小文字にし、スペース、_、.、/ を - に置き換え、その他の文字はすべて削除し、連続する - は1つにまとめます。名前は origin リモート URL から取得するため、チェックアウトディレクトリ、worktree、サブディレクトリの名前にかかわらず同じです。リモートがない場合はメインのチェックアウトディレクトリ名を使用し、git リポジトリ外では現在のディレクトリ名を使用します。
• 末尾のセグメントはこのスキルの名前であり、変更されません。

何かを書き込む前に、一度だけ導出します。

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-react-health-audit.md"

このスキルが reports/<YYYY-MM-DD>-<project>-react-health-audit.md に書き込む箇所はすべて、解決済みのそのパスを指します。

somnio run を通じて実行する場合、CLI はレポートの完全なパスを計算し、プロンプトで渡します。渡されたパスをそのまま使用してください。再計算すると、ランナーがレポートを見つけられず、ステップが失敗します。

レポートのメタデータ（必須）

生成するすべてのレポートには、末尾に必ずメタデータブロックを含めてください。これは必須です。決して省略しないでください。

テンプレートの Report Metadata テーブルをレポートの最後のブロックとしてコピーしてください。テンプレートに記載されている Generated by の行は、バージョンを変更、推測、省略せず、そのまま記載してください。残りの行は、説明に従って入力してください。

このブロックをレポートの末尾に含めてください。

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | react-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |