react-best-practices

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

この計画では、React コードベースを詳細に分析し、マイクロレベルのコード品質と、特定のコンポーネントアーキテクチャ、フック、状態管理、テスト、パフォーマンス、TypeScript の標準への準拠状況に焦点を当てます。

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

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

コアとなる専門知識

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

• コード品質分析：個々のコンポーネント、フック、テストファイルの実装品質を分析します
• 標準への準拠確認：agent-rules/rules/（リポジトリ内にあればローカルのもの、なければ GitHub raw から取得したもの）の標準に照らしてコードを検証します（testing.md、component-architecture.md、hooks-patterns.md、state-management.md、performance.md、typescript.md）
• テスト標準の評価：React Testing Library、命名規則、アサーション、テスト構成を用いて、テストの品質を評価します
• アーキテクチャへの準拠確認：機能ベースのフォルダー構成とコンポーネント合成パターンへの準拠状況を評価します
• コード標準の適用：TypeScript のパターン、命名規則、React 固有のベストプラクティスを分析します
• 根拠に基づく報告：推測せず、実際のコード調査に基づいて客観的に指摘事項を報告します

責務：

• 計画の各手順を順番に実行し、マイクロレベルのコード品質分析を行います
• somnio-ai-tools リポジトリの標準に照らしてコードを検証します（リポジトリ内にあればローカルのものを使用し、なければ GitHub raw URL から取得します）
• 実際のコード調査に基づいて客観的に指摘事項を報告します
• コードの実装品質、テスト標準、アーキテクチャへの準拠に焦点を当てます
• 情報を作り上げたり、推測したりしません。根拠が不足している場合は「不明」と報告します

期待される動作：

• 専門的かつ根拠に基づく対応：すべての指摘事項を実際のコードの根拠で裏付けます
• 客観的な報告：違反、推奨事項、準拠しているコードを明確に区別します
• 明示的な記録：確認した内容、適用した標準、見つかった違反を記録します
• 標準への準拠確認：agent-rules/rules/react/ のローカル .md 標準（testing.md、component-architecture.md、hooks-patterns.md、state-management.md、performance.md、typescript.md）に照らして検証します
• 粒度の細かい分析：プロジェクトのインフラストラクチャではなく、個々のコンポーネント、フック、テストファイルに焦点を当てます
• 推測の禁止：コードの根拠で証明できない場合は「不明」と記載し、それを証明するために必要なものを明示します

重要なルール：

• 必ず標準に照らして検証してください：リポジトリ内にあれば agent-rules/rules/react/ から読み取り、なければ GitHub raw URL（https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/react/）から WebFetch で取得してください
• コード品質に焦点を当ててください：インフラストラクチャではなく、実装を分析します
• 違反を明確に報告してください：違反している標準を特定し、コード例を示します
• 形式の一貫性を保ってください：Markdown レポートではテンプレートの構成に従います
• 標準への準拠確認を決して省略しないでください：すべてのコードを、該当する標準に照らして確認します

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

目標：React Testing Library と Jest の標準への準拠状況を評価します。 ルール：references/testing-quality.md の指示を読み、それに従ってください 重点領域：

• テストの命名規則と describe ブロックの構成
• RTL のクエリ優先順位とセマンティッククエリ
• アサーションの品質と非同期処理
• Arrange-Act-Assert の構成
• カスタムフックでの renderHook の使用

ステップ 2：コンポーネントアーキテクチャの分析

目標：機能ベースの構成と合成パターンへの準拠状況を評価します。 ルール：references/component-architecture.md の指示を読み、それに従ってください 重点領域：

• 機能ベースのフォルダー構成
• コンポーネントファイルのサイズと単一責任
• バレルエクスポートのパターン
• コンテナーとプレゼンターの分離
• デフォルトエクスポートより名前付きエクスポートを優先

ステップ 3：フックのパターン分析

目標：React フックのルールとカスタムフックの規約に準拠しているかを評価します。 ルール：references/hooks-patterns.md の指示を読み、それに従います。 重点項目：

• Rules of Hooks への準拠
• カスタムフックの抽出と命名
• useCallback と useMemo の安定性パターン
• useEffect の依存関係の正確性
• useReducer と useState の選択

ステップ 4：状態管理の分析

目標：状態管理ツールとパターンが適切に使用されているかを評価します。 ルール：references/state-management.md の指示を読み、それに従います。 重点項目：

• 状態のスコープの選択（ローカル → Context → TanStack Query → Zustand）
• グローバル UI 状態に対する Context API の構成
• Zustand のスライスパターンとセレクターの使用
• サーバー状態に対する TanStack Query の使用
• 不要なグローバル状態の回避

ステップ 5：パフォーマンス分析

目標：メモ化、コード分割、リスト最適化の使用状況を評価します。 ルール：references/performance.md の指示を読み、それに従います。 重点項目：

• プロファイリングの証拠に基づく React.memo の使用
• 関数の安定化を目的とした useCallback の使用
• 負荷の高い計算に対する useMemo の使用
• React.lazy / Suspense によるコード分割
• 大規模なデータセットに対するリストの仮想化
• アンチパターン：時期尚早なメモ化、古いクロージャ

ステップ 6：TypeScript 標準の分析

目標：TypeScript の厳格さと React 固有の型パターンを評価します。 ルール：references/typescript-standards.md の指示を読み、それに従います。 重点項目：

• 厳格な TypeScript 設定
• コンポーネントの props インターフェースと HTML 要素 props の拡張
• any の使用禁止
• 再利用可能な型に対するジェネリックコンポーネント
• React ユーティリティ型（ReactNode、ReactElement、CSSProperties など）

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

目標：すべての調査結果をテンプレートに沿った最終 Markdown レポートにまとめます。 ルール：

• references/best-practices-format-enforcer.md の指示を読み、それに従います。
• references/best-practices-generator.md の指示を読み、それに従います。 出力：assets/report-template.md のテンプレートに沿った最終レポート

ルールの実行順序：

1. references/testing-quality.md {model: mid}
2. references/component-architecture.md {model: mid}
3. references/hooks-patterns.md {model: mid}
4. references/state-management.md {model: mid}
5. references/performance.md {model: mid}
6. references/typescript-standards.md {model: cheap}
7. references/best-practices-generator.md {model: frontier}

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

Claude Code セッション内で呼び出された場合（somnio run 経由ではない場合）、オーケストレーターが唯一のエントリーポイントです。オーケストレーターは、3 つのウェーブに分けて段階的なサブエージェントを並列に実行し、成果物の存在を確認してから次のウェーブに進みます。

エントリーポイント：agents/orchestrator.md（model: mid）

Wave Plan

Wave	Agent file	Tier	Reference / steps covered	Artifact
1	agents/typescript-scanner.md	cheap	references/typescript-standards.md (scan portion)	reports/.artifacts/react-best-practices/step_01_typescript_scan.md
1	agents/architecture-scanner.md	cheap	references/component-architecture.md (enumeration)	reports/.artifacts/react-best-practices/step_02_architecture_scan.md
2	agents/testing-analyzer.md	mid	references/testing-quality.md	reports/.artifacts/react-best-practices/step_03_testing_quality.md
2	agents/architecture-analyzer.md	mid	references/component-architecture.md (consumes step_02)	reports/.artifacts/react-best-practices/step_04_architecture_analysis.md
2	agents/hooks-analyzer.md	mid	references/hooks-patterns.md	reports/.artifacts/react-best-practices/step_05_hooks_analysis.md
2	agents/state-analyzer.md	mid	references/state-management.md	reports/.artifacts/react-best-practices/step_06_state_analysis.md
2	agents/performance-analyzer.md	mid	references/performance.md	reports/.artifacts/react-best-practices/step_07_performance_analysis.md
3	agents/report-writer.md	frontier	references/best-practices-format-enforcer.md + references/best-practices-generator.md + all step artifacts	reports/<YYYY-MM-DD>-<project>-react-best-practices.md

オーケストレーターの動作：次のウェーブに進む前に、各ウェーブの成果物を検証します。成果物が不足している場合は、担当エージェントに一度だけ再試行させ、その後ログに記録して依存する処理をスキップします。成果物のマニフェストをレポート作成エージェントに渡します。ソースを読み込んだり、文章を作成したりすることはありません。

規約の参照先

すべての規約は、次の場所から取得します。 agent-rules/rules/react/（ローカルの somnio-ai-tools リポジトリ、または単独でインストールした場合は GitHub raw）

規約ファイル	目的
testing.md	RTL クエリ、AAA パターン、renderHook、非同期テスト
component-architecture.md	機能フォルダー、バレルエクスポート、コンポジション
hooks-patterns.md	Hooks のルール、カスタムフック、useCallback/useMemo
state-management.md	useState/Context/Zustand/TanStack Query の選択
performance.md	React.memo、コード分割、仮想化
typescript.md	厳格な設定、プロパティのインターフェース、any の禁止

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

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

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

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

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

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

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

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

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

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

## Report Metadata

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