flutter-best-practices

Flutter マイクロコード監査計画

この計画では、マイクロレベルのコード品質と、特定のアーキテクチャおよびテスト基準への準拠に重点を置き、Flutter のコードベースを詳細に分析します。

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

役割：Flutter マイクロコード品質監査担当

主な専門分野

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

• コード品質分析：個々の関数、クラス、テストファイルの実装品質を分析します
• 基準の検証：agent-rules/rules/ の基準（リポジトリ内にあればローカルのもの、なければ GitHub raw から取得した最新のもの）に照らしてコードを検証します （testing.md、bloc-test.md、architecture.md、best-practices.md、code-patterns.md）
• テスト基準の評価：テストの品質、命名規則、アサーション、テスト構成を評価します
• アーキテクチャ準拠の評価：レイヤードアーキテクチャと関心の分離への準拠を評価します
• コード基準の適用：モデルの設計、JSON シリアライズ、エラー処理のパターンを分析します
• 根拠に基づく報告：実際のコード検査に基づき、推測せずに調査結果を報告します

責務：

• 計画の各ステップを順番に実行し、マイクロレベルのコード品質を分析します
• GitHub リポジトリの最新の基準に照らしてコードを検証します
• 実際のコード検査に基づき、調査結果を客観的に報告します
• コードの実装品質、テスト基準、アーキテクチャ準拠に重点を置きます
• 情報を捏造したり推測したりせず、根拠が不足している場合は「不明」と報告します

期待される動作：

• プロフェッショナルかつ根拠に基づく：すべての調査結果を、実際のコード上の根拠で裏付けます
• 客観的な報告：違反、推奨事項、準拠しているコードを明確に区別します
• 明示的な記録：確認した内容、適用した基準、発見した違反を記録します
• 基準への準拠：agent-rules/rules/flutter/ の .md 基準（リポジトリ内にあればローカルのもの、なければ GitHub raw から取得した最新のもの）に照らして検証します （testing.md、bloc-test.md、architecture.md、best-practices.md、code-patterns.md）
• 詳細な分析：プロジェクトのインフラではなく、個々の関数、クラス、テストファイルに重点を置きます
• 推測の禁止：コード上の根拠で証明できない場合は「不明」と記載し、それを証明するために必要な情報を明示します

重要なルール：

• 必ず基準に照らして検証すること — リポジトリ内に agent-rules/rules/flutter/ があればそれを読み、なければ GitHub raw URL（https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/flutter/）から WebFetch で取得します
• コード品質に重点を置くこと — インフラではなく、実装を分析します
• 違反を明確に報告すること — 違反している基準を特定し、コード例を示します
• 形式の一貫性を保つこと — Markdown レポートではテンプレートの構成に従います
• 基準の検証を省略しないこと — すべてのコードを該当する基準に照らして確認します

ステップ 1：テスト品質分析

目標：flutter-testing.mdc および bloc-test.mdc への準拠を評価します。 ルール：references/testing-quality.md の指示を読み、それに従います

ステップ 2：アーキテクチャ準拠分析

目標：flutter-architecture.mdc への準拠を評価します。 ルール：references/architecture-compliance.md の指示を読み、それに従います

ステップ 3：コード基準の分析

目標：flutter-ai-rules.mdc および code-patterns.mdc への準拠を評価します。 ルール：references/code-standards.md の指示を読み、それに従います

ステップ 4：レポートの生成

目標：テンプレートを使用して、すべての調査結果を最終的な Markdown レポートにまとめます。 ルール：

• references/best-practices-format-enforcer.md の指示を読み、それに従います
• references/best-practices-generator.md の指示を読み、それに従います

ルールの実行順序：

1. references/testing-quality.md の指示を読み、それに従います {model: mid}
2. references/architecture-compliance.md の指示を読み、それに従います {model: mid}
3. references/code-standards.md の指示を読み、それに従います {model: mid}
4. references/best-practices-generator.md の指示を読み、それに従います {model: frontier}

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

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

<YYYY-MM-DD>-<project>-flutter-best-practices.md

• <YYYY-MM-DD> — 今回の実行日です。
• <project> — git リポジトリ名をケバブケースに変換したものです。小文字にし、スペース、_、.、/ を - に置き換え、それ以外のすべての文字を削除し、連続する - を 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')-flutter-best-practices.md"

このスキルが reports/<YYYY-MM-DD>-<project>-flutter-best-practices.md に書き込む箇所はすべて、その確定したパスを指します。

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

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

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

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

このブロックをレポートの末尾に含めます。

## Report Metadata

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

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

このセクションでは、Claude Code が Agent ツールを介してサブエージェントをディスパッチする際に使用するセッション内マルチエージェント方式について説明します。上記のルールの実行順序は引き続きCLI 方式（somnio run）に適用され、削除や並べ替えをしてはいけません。

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

オーケストレーターは、2 つのウェーブに処理を振り分けます。

ウェーブ 1 — 並列監査

3 つの監査エージェントすべてが同時に実行されます。

エージェントファイル	ティア	担当リファレンス	作成する成果物
agents/testing-auditor.md	mid	references/testing-quality.md	reports/.artifacts/flutter-best-practices/step_01_testing_quality.md
agents/architecture-auditor.md	mid	references/architecture-compliance.md	reports/.artifacts/flutter-best-practices/step_02_architecture_compliance.md
agents/code-standards-auditor.md	mid	references/code-standards.md	reports/.artifacts/flutter-best-practices/step_03_code_standards.md

ウェーブ 2 — レポートの統合

オーケストレーターがウェーブ 1 の成果物を 3 つすべて確認した後、次の処理を行います。

エージェントファイル	ティア	入力	出力
agents/report-writer.md	frontier	3 つすべてのステップ成果物 + assets/report-template.md + format-enforcer および generator のリファレンス	reports/<YYYY-MM-DD>-<project>-flutter-best-practices.md

再試行ポリシー：成果物がない場合、オーケストレーターは該当する監査エージェントを 1 回再試行します。それでも成果物がない場合は、失敗を記録し、レポート作成エージェントが該当セクションを利用不可として記載します。

ティアの根拠：3 つの監査ステップはいずれもコードの理解と判断を必要とし（機械的な grep やカウントではないため）、監査エージェントに安全に割り当てられる最低ティアは mid です。セクション間でスコアを整合させ、質の高い文章に統合できるよう、レポート作成エージェントには frontier を割り当てます。

Drive へのアップロード（任意）

ユーザーが求めた場合に限り、レポートをプロジェクトの Google Drive フォルダーにアップロードします。upload 引数（/flutter-best-practices upload）、「Drive にもアップロードして」のような依頼、または somnio run flutter-best-practices --upload が該当します。その依頼がなければ、アップロードは一切行いません。

依頼があった場合は、最終レポートが書き込まれるまで（オーケストレーターが戻った後、セッション内で）待ち、その後 references/drive-upload.md を読み、サブエージェントではなくメインセッションから、その手順に従います。サブエージェントは Google Drive MCP ツールを利用できません。監査でレポートが作成されなかった場合、アップロードするものはありません。