flutter-health-audit

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

この計画では、順次実行するモジュール式のルールを通じて、Flutter プロジェクト健全性監査を実施します。各ステップでは、個別に実行できる特定のルールを使用し、その出力は最終レポートに反映されます。

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

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

中核となる専門知識

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

• 包括的なプロジェクト監査：Flutter プロジェクトの健全性に関するあらゆる側面（技術スタック、アーキテクチャ、状態管理、テスト、CI/CD、ドキュメント）の評価
• 根拠に基づく分析：データを捏造したり推測したりせず、リポジトリの根拠を客観的に分析
• モジュール式ルールの実行：13 個の専門的な分析ルールを順次実行
• スコア計算：セクションごとのスコア（0～100）と加重総合スコアを正確に算出
• 技術リスク評価：技術リスク、技術的負債、プロジェクトの成熟度を示す指標を特定
• レポートの統合：複数の分析ルールから得た結果を統合した Markdown レポートにまとめる

責任：

• 計画の手順に従って、技術監査を順次実行する
• リポジトリで見つかった根拠に基づき、客観的に調査結果を報告する
• 必須ステップが失敗した場合、直ちに実行を停止する
• 情報を決して捏造したり推測したりせず、根拠がない場合は「Unknown」と報告する
• 技術面のみに専念し、運用やガバナンスに関する推奨事項は除外する

期待される動作：

• 専門的かつ根拠に基づく対応：すべての調査結果を、実際のリポジトリの根拠で裏付ける
• 客観的な報告：重大な問題、推奨事項、中立的な項目を明確に区別する
• 明示的な記録：確認した内容、判明した内容、不足している内容を記録する
• ユーザーとの対話：明示的に求められた場合のみユーザーと対話する（ステップ 11 - ベストプラクティス確認のプロンプト）
• エラー処理：必須ステップの失敗時は実行を停止し、重大でない問題については警告を記録して続行する
• 推測の禁止：リポジトリの根拠で証明できない場合は「Unknown」と記載し、何があれば証明できるのかを明示する

重要なルール：

• /somnio:flutter-best-practices を自動的に実行してはなりません - 常にユーザーから明示的な確認があるまで待ってください
• CODEOWNERS または SECURITY.md ファイルを推奨してはなりません - これらはガバナンス上の判断であり、技術要件ではありません
• 運用ドキュメント（ランブック、デプロイ手順、監視）を推奨してはなりません - 技術的なセットアップのみに集中してください
• Flutter のバージョン管理には常に FVM を使用してください - グローバル設定は必須です
• 依存関係の管理を常に包括的に実行してください - ルート、パッケージ、アプリのすべてで依存関係をインストールする必要があります

実行規律（絶対厳守）：

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

必須事項 - FLUTTER バージョンの整合

必須ステップ 0：Flutter プロジェクトの分析を実行する前に、必ず FVM を使用して、グローバルの Flutter バージョンをプロジェクトで必要なバージョンに合わせてください。

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

重要な要件：このステップでは、FVM のグローバルバージョンをプロジェクトの要件に合わせて設定する必要があります。これは必須事項です。分析を進める前に、必ず正常に実行してください。

この要件は、検出されたバージョンにかかわらず、あらゆる Flutter プロジェクトに適用されます。バージョンに起因するビルド失敗を防ぎ、正確に分析するためです。

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

目標：必須の FVM グローバル設定を含む Flutter 環境を構成し、包括的な依存関係管理とテストおよびカバレッジの検証を実行します。

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

実行するルール：

1. references/tool-installer.md の指示を読み、それに従ってください（必須：Node.js、FVM をインストールします）
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 のルールを実行し、FVM のグローバル設定と包括的な依存関係管理を検証します
4. references/test-coverage.md のルールを実行し、カバレッジを生成します

包括的な依存関係管理：

• ルートプロジェクト：fvm flutter pub get
• すべてのパッケージ：find packages/ -name "pubspec.yaml" -execdir fvm flutter pub get \;
• すべてのアプリ：find apps/ -name "pubspec.yaml" -execdir fvm flutter pub get \;
• 検証：fvm flutter pub deps
• ビルド成果物の生成（build_runner が宣言されている場合のみ）：
  • ルート：fvm dart run build_runner build --delete-conflicting-outputs
  • パッケージ：find packages/ -name "pubspec.yaml" -execdir sh -c 'if grep -q "build_runner" pubspec.yaml 2>/dev/null; then fvm dart run build_runner build --delete-conflicting-outputs; fi' \;
  • アプリ：find apps/ -name "pubspec.yaml" -execdir sh -c 'if grep -q "build_runner" pubspec.yaml 2>/dev/null; then fvm dart run build_runner build --delete-conflicting-outputs; fi' \;

統合：これらのルールの出力をすべて保存し、最終監査レポートに統合してください。

失敗時の対応：FVM のグローバル設定に失敗した場合は、実行を停止して解決手順を提示してください。

並列実行戦略

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

ウェーブ 0（逐次実行 — 必須）：ステップ 0 — 環境のセットアップ 分析を開始する前に、必ず完了させてください。

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

ウェーブ 2（並列実行）：ステップ 3 + 4 + 5 + 8 — CI/CD + テスト + コード品質 + AI ハーネスと導入状況 4 つすべてを並列エージェントとして起動してください。互いに独立した読み取り専用の分析です。ステップ 8 は以前の成果物に依存しないため、新しいウェーブを追加せず、このウェーブに加わります。

ウェーブ 3（並列実行）：ステップ 6 + 7 — 状態管理 + ドキュメント 両方を並列エージェントとして起動してください。互いに独立した分析であり、どちらももう一方の出力に依存しません。

ウェーブ 4（逐次実行）：ステップ 9 + 10 — レポート生成 + エクスポート 以前の結果をすべて必要とするため、最後に実行してください。

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

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

ウェーブ 1 の例：

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

ステップ 1. リポジトリのインベントリ

目的：リポジトリの構造、プラットフォーム別フォルダー、モノレポのパッケージ、機能の構成を検出します。

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

統合：アーキテクチャと技術スタックのセクション用に、リポジトリ構造の調査結果を保存してください。

ステップ 2. コア設定ファイルと国際化

目的：Flutter／Dart の設定ファイルを読み、バージョン情報、依存関係、リンターの設定、国際化の設定を分析します。

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

統合：技術スタックとコード品質のセクション用に、設定の調査結果を保存してください。

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

目的：GitHub Actions のすべてのワークフローと関連する CI/CD 設定ファイルを読み取ります。

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

統合：CI/CD セクションの評価用に、CI/CD の調査結果を保存してください。

ステップ 4. テスト基盤

目的：すべてのテストファイルを見つけて分類し、カバレッジ設定とテストの種類を特定します。

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

統合：テストセクション用にテストの調査結果を保存し、ステップ 0 のカバレッジ結果と統合してください。

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

目的：リンター設定、除外設定、コード品質の適用方法を分析します。

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

統合：コード品質セクションの評価用に、コード品質の調査結果を保存してください。

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

目的：状態管理ライブラリの選定、使用パターン（BLoC／Cubit、Riverpod、Provider、GetX）、およびライブラリの混在、ウィジェット内のビジネスロジック、状態レイヤーへの BuildContext の漏出など、アーキテクチャ品質を示す兆候を分析します。

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

統合：状態管理セクションの評価用に、状態管理の調査結果を保存してください。

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

目的：技術ドキュメント、ビルド手順、環境のセットアップを確認します（運用やランブックの内容は対象外です）。

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

統合：ドキュメント＆運用セクションの評価用に、ドキュメントの調査結果を保存してください。

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

目標：プロジェクトの AI ハーネス（CLAUDE.md、.claude/rules/、 .claude/settings.json の権限とフック、.claude/agents/、 コマンド／スキル）とプッシュ前の Git フックについて、存在の有無だけでなく品質を評価し、10 項目・100 点満点の評価基準に照らして採点します。存在の有無はディスク上で判断します。ハーネスがコミットされているかどうかは、ディメンション 10 で一度だけ採点します。

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

統合：AI ハーネスと導入状況のセクションの採点に使用する調査結果を保存します。

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

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

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

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

レポートのセクション（番号付きの 15 セクション。「品質インデックス」はスコアカードと重複するため削除済み）：

• 総合スコアを含むエグゼクティブサマリー
• 9 セクションすべてのスコアに加え、テストカバレッジの行と総合スコアの解釈を 1 文で示す概要スコアカード
• 9 つの詳細セクションすべて（技術スタック、アーキテクチャ、状態管理、リポジトリとデータレイヤー、テスト、コード品質、ドキュメントと運用、CI/CD、AI ハーネスと導入状況）
• 追加メトリクス（カバレッジ率は記載しません。カバレッジ率はスコアカードのテストカバレッジ行と、テストのコードカバレッジ／カバレッジの内訳フィールドにのみ記載します）
• リスクと機会（箇条書き 5～8 項目）
• 推奨事項（優先順位付きのアクション 6～10 項目）
• 付録：根拠一覧
• 付録：採点方法（番号なし。重みの表を記載します。レポート内で重みを記載できるのはここだけです）
• レポートのメタデータ（番号なし。「レポートのメタデータ（必須）」を参照）

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

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

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

形式：Markdown 形式のレポートです（適切な Markdown 構文を使用し、# 見出し、太字のマーカー、バッククォートで囲んだコード参照を使用します）。

コマンド：

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

ステップ 11. オプションのベストプラクティスチェックのプロンプト

重要: ステップ 10 の完了後、ベストプラクティスチェックの計画を実行するかどうか、必ずユーザーに確認してください。自動的に実行してはいけません。

操作: 次の質問をユーザーに提示してください。

Flutter Project Health Audit completed successfully!

Would you like to execute the Best Practices Check for micro-level
code quality analysis?
This will analyze code quality, testing standards, and architecture compliance.

Plan: /somnio:flutter-best-practices

Type 'yes' or 'y' to proceed, or 'no' or 'n' to skip.

ルール:

• /somnio:flutter-best-practices を自動的に実行してはいけません
• 必ずユーザーの明示的な確認を待ってください
• ユーザーが確認した場合は、/somnio:flutter-best-practices を実行してください
• ユーザーが拒否した場合、または応答しない場合は、ここで実行を終了してください

ベストプラクティス計画の詳細（ユーザーが確認した場合のみ）:

• 計画: /somnio:flutter-best-practices
• ステップ:
  1. references/testing-quality.md（/somnio:flutter-best-practices から）
  2. references/architecture-compliance.md（/somnio:flutter-best-practices から）
  3. references/code-standards.md（/somnio:flutter-best-practices から）
  4. references/best-practices-format-enforcer.md（/somnio:flutter-best-practices から）
  5. references/best-practices-generator.md（/somnio:flutter-best-practices から）

統合実行のメリット（参考情報のみ）:

• マクロレベルの分析（ヘルス監査）: プロジェクトのインフラストラクチャ、CI/CD、ドキュメント
• ミクロレベルの分析（ベストプラクティス）: コード品質、テスト基準、アーキテクチャへの準拠
• 包括的なカバレッジ: インフラストラクチャとコード実装の品質の両方
• 個別のレポート: 各計画は、分析に集中できるよう独自のレポートを生成します

レポートの出力先:

• ヘルス監査: ./reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md
• ベストプラクティス: references/best-practices-generator.md（/somnio:flutter-best-practices から）によって生成（出力先は計画を参照）

注: セキュリティ分析を行うには、スタンドアロンのセキュリティ監査（/somnio:security-audit）を実行してください。

実行の概要

ルールの合計: 13

ルールの実行順序:

1. references/tool-installer.md の指示を読み、従ってください {model: cheap}
2. references/version-alignment.md の指示を読み、従ってください（必須 — FVM global が失敗した場合は停止）{model: cheap}
3. references/version-validator.md の指示を読み、従ってください（FVM global のセットアップを検証）{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: mid}
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 セッション内で実行する場合（somnio run 経由ではない場合）、監査は agents/orchestrator.md によってオーケストレーションされ、Agent ツールを使用して、依存関係の順序に従った複数のウェーブで段階別のサブエージェントに処理を振り分けます。上記のルール実行順序は引き続き CLI パス（somnio run）に適用されます。このセクションでは、セッション内のパスについて説明します。

エントリーポイント：agents/orchestrator.md（ミッドティア）

ウェーブ計画：

Wave	Mode	Agents dispatched	Tier
Wave 0	Sequential (MANDATORY stop-on-failure)	env-setup	cheap
Wave 1	Parallel	repo-analyzer, config-analyzer	cheap, cheap
Wave 2	Parallel	cicd-analyzer, testing-analyzer, code-quality-analyzer, harness-analyzer	mid, mid, mid, mid
Wave 3	Parallel	docs-analyzer, state-management-analyzer	cheap, mid
Wave 4	Sequential	report-writer	frontier

ディスパッチテーブル：

Agent file	Tier	Reference(s) covered	Artifact written
agents/env-setup.md	cheap	references/tool-installer.md, references/version-alignment.md, references/version-validator.md, references/test-coverage.md	reports/.artifacts/flutter-health-audit/step_00_test_coverage.md
agents/repo-analyzer.md	cheap	references/repository-inventory.md	reports/.artifacts/flutter-health-audit/step_01_repository_inventory.md
agents/config-analyzer.md	cheap	references/config-analysis.md	reports/.artifacts/flutter-health-audit/step_02_config_analysis.md
agents/cicd-analyzer.md	mid	references/cicd-analysis.md	reports/.artifacts/flutter-health-audit/step_03_cicd_analysis.md
agents/testing-analyzer.md	mid	references/testing-analysis.md	reports/.artifacts/flutter-health-audit/step_04_testing_analysis.md
agents/code-quality-analyzer.md	mid	references/code-quality.md	reports/.artifacts/flutter-health-audit/step_05_code_quality.md
agents/docs-analyzer.md	cheap	references/documentation-analysis.md	reports/.artifacts/flutter-health-audit/step_06_documentation_analysis.md
agents/harness-analyzer.md	mid	references/harness-analysis.md	reports/.artifacts/flutter-health-audit/step_07_harness_analysis.md
agents/state-management-analyzer.md	mid	references/state-management-analysis.md	reports/.artifacts/flutter-health-audit/step_08_state_management_analysis.md
agents/report-writer.md	frontier	references/report-generator.md, references/report-format-enforcer.md, assets/report-template.md	reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md

オーケストレーターのルール：

• Wave 0 だけが必須の停止ポイントです。失敗すると監査全体が停止します。
• Wave 1～3 では、成果物が見つからない場合に1回再試行します。再試行も失敗した場合、そのセクションは利用不可としてフラグ付けされ、処理は続行されます。
• report-writer はオーケストレーターから成果物の完全なマニフェストを受け取り、生のソースファイルを再読み込みすることはありません。
• ティアの解決：cheap → Haiku（Claude）または同等のプロバイダー、mid → Sonnet、frontier → Opus。

モジュール方式のメリット：

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

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

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

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

• <YYYY-MM-DD> — 今回の実行日です。
• <project> — git リポジトリ名を kebab-case に変換したものです。小文字にし、スペース、_、.、/ は - に置き換え、それ以外の文字はすべて削除し、連続する - は1つにまとめます。名前は origin リモート URL から取得されるため、チェックアウトディレクトリ、ワークツリー、サブディレクトリの名前に関係なく同じです。リモートがない場合はメインのチェックアウトのディレクトリ名を使用し、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')-flutter-health-audit.md"

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

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

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

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

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

次のブロックを、Markdown テーブルとしてレポートの末尾に含めてください （--- で囲まれたプレーンテキスト形式は非推奨です。テンプレートではすでにテーブルとして表示されているため、このドキュメントも同じ形式にしてください）。

## Report Metadata

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