feature-arch

フィーチャーベースアーキテクチャのベストプラクティス

React アプリケーションをフィーチャー単位で整理し、独立したチームによるスケーラブルな開発を可能にするための包括的なアーキテクチャガイドです。影響度に応じて、重大（ディレクトリー構造、インポート）から段階的（命名規則）まで優先順位付けされた、8 カテゴリーにわたる 43 のルールを収録しています。実際のプロジェクトで実行すると、このスキルはすべての判断の根拠をこれらのルールに置いた、プロジェクト固有のブループリントを作成します。

主な成果物：ターゲットアーキテクチャのブループリント

実際のプロジェクトでエージェントがこのスキルを実行すると、成果物として単一の Markdown ファイルが docs/architecture/FEATURE-ARCH-TARGET.md（または リポジトリーに既存のドキュメント保存先）に保存されます。ブループリントには次の内容が含まれます。

1. プロジェクトのコンテキスト — フレームワーク、状態管理ライブラリー、ルーティングモデル、現在の構成。
2. 特定されたフィーチャー — ユーザーに確認したうえで、ルート、ドキュメント、openspec、コードのまとまりを情報源として特定します。
3. ターゲットディレクトリーツリー — 疑似ツリーではなく、実際のパスを記載します。
4. フィーチャーごとの公開 API — 各 index.ts で名前付きエクスポートされるものを正確に記載します。
5. インポート境界マトリックス — フィーチャー間の関係を示す N×N の表（allowed／forbidden／via app／via events）。
6. 状態とデータの所有権 — フィーチャーごとのサーバー状態とクライアント状態の所有者。
7. フィーチャー間通信の方針 — コンポジション、イベント、または共有スライスと、その根拠。
8. 番号付きの移行計画 — ファイル単位の移動／作成／削除手順と、S／M／L の工数見積もり。
9. 人間向けの準拠チェックリスト — コードレビューと「完了の定義」に使用します。
10. 未解決の質問 — 移行前に人間による判断が必要な事項。

各セクションでは、判断の根拠となる以下の具体的なルールを参照するため、 ブループリントは独立した別の基準ではなく、このスキルの投影として維持されます。

エージェントによるブループリントの生成方法

references/_blueprint-process.md の手順に従ってください。概要：

1. コンテキストを収集します（package.json、src/ ツリー、README、CLAUDE.md、openspec/）。
2. ルート、ドキュメント、コードのまとまりから候補となるフィーチャーを特定します。
3. AskUserQuestion を使って、フィーチャーの一覧をユーザーに確認します。
4. 明示的な判断を記録します（レイヤーモデル、通信の仕組み、状態／ルーティングの所有者）。
5. assets/templates/feature-arch-target.md.template を埋めます。すべての {{placeholder}} をプロジェクトの具体的な値に置き換えてください。
6. 引き継ぎを行います。パスを表示し、フィーチャー数と手順数を要約し、主なリスクを 3 件挙げ、次のアクションを提案します。同じターン内で移行手順の実行を開始しないでください。

非常に小規模なプロジェクト（ソースファイルが約 10 個未満）では、代わりに 1 ページの基本構造を作成し、2～3 個目のフィーチャーができた後に完全なブループリントを作成する必要がある旨を記載してください。

適用する場面

次の場合に、これらのガイドラインを参照してください。

• プロジェクトでフィーチャーベースのアーキテクチャの目標が求められている場合（ブループリントを生成する）。
• 新しいフィーチャーやモジュールを作成する場合。
• プロジェクトのディレクトリー構造を整理する場合。
• インポートのルールと境界を設定する場合。
• データ取得パターンを実装する場合。
• 複数のフィーチャーからコンポーネントを構成する場合。
• アーキテクチャ違反についてコードをレビューする場合。

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	接頭辞
1	ディレクトリー構造	CRITICAL	struct-
2	インポートと依存関係	CRITICAL	import-
3	モジュール境界	HIGH	bound-
4	データ取得	HIGH	fquery-
5	コンポーネント構成	MEDIUM-HIGH	fcomp-
6	状態管理	MEDIUM	fstate-
7	テスト戦略	MEDIUM	test-
8	命名規則	LOW	name-

クイックリファレンス

1. ディレクトリ構成（最重要）

• struct-feature-folders - 技術的な種類ではなく、機能ごとに整理します
• struct-feature-self-contained - 機能を自己完結させます
• struct-shared-layer - 真に汎用的なコードに限り、共有レイヤーを使用します
• struct-flat-hierarchy - ディレクトリ階層をフラットに保ちます
• struct-optional-segments - 必要なセグメントのみを含めます
• struct-app-layer - アプリケーションレイヤーと機能を分離します
• struct-domain-folders - 大規模な場合は、機能をドメインごとにまとめます

2. インポートと依存関係（最重要）

• import-unidirectional-flow - インポートの流れを一方向にします
• import-no-cross-feature - 機能をまたぐインポートを禁止します
• import-public-api - パブリック API 経由でのみエクスポートします
• import-avoid-barrel-files - 深い階層にあるバレルファイルからの再エクスポートを避けます
• import-path-aliases - 一貫性のあるパスエイリアスを使用します
• import-type-only - 型には型専用インポートを使用します

3. モジュール境界（高）

• bound-feature-isolation - 機能の分離を徹底します
• bound-interface-contracts - 明示的なインターフェース契約を定義します
• bound-feature-scoped-routing - ルーティングの範囲を機能の関心事に限定します
• bound-minimize-shared-state - 機能間で共有する状態を最小限にします
• bound-event-based-communication - 機能間の通信にイベントを使用します
• bound-feature-size - 機能のサイズを適切に保ちます

4. データ取得（高）

• fquery-single-responsibility - クエリ関数の役割を単一に保ちます
• fquery-colocate-with-feature - データ取得処理を機能と同じ場所に配置します
• fquery-parallel-fetching - 独立したデータは並列で取得します
• fquery-avoid-n-plus-one - N+1 クエリパターンを避けます
• fquery-feature-scoped-keys - 機能単位のクエリキーを使用します
• fquery-server-component-fetching - サーバーコンポーネントのレベルでデータを取得します

5. コンポーネントの構成（中〜高）

• fcomp-single-responsibility - コンポーネントにも単一責任の原則を適用します
• fcomp-composition-over-props - Props のバケツリレーよりもコンポジションを優先します
• fcomp-container-presentational - コンテナとプレゼンテーションの関心事を分離します
• fcomp-props-as-data-boundary - Props を機能の境界として使用します
• fcomp-colocate-styles - スタイルをコンポーネントと同じ場所に配置します
• fcomp-error-boundaries - 機能レベルのエラーバウンダリーを使用します

6. 状態管理（中）

• fstate-feature-scoped-stores - ストアの範囲を機能単位に限定します
• fstate-server-state-separation - サーバー状態とクライアント状態を分離します
• fstate-lift-minimally - 必要な範囲に限って状態を持ち上げます
• fstate-context-sparingly - 機能の状態には Context を控えめに使用します
• fstate-reset-on-unmount - アンマウント時に機能の状態をリセットします

7. テスト戦略（中）

• test-colocate-with-feature - テストを機能と同じ場所に配置します
• test-feature-isolation - 機能を分離してテストします
• test-shared-utilities - 機能固有のテストユーティリティを作成します
• test-integration-at-app-layer - アプリケーションレイヤーで統合テストを作成します

8. 命名規則（低）

• name-feature-naming - ドメイン駆動の機能名を使用します
• name-file-conventions - 一貫性のあるファイル命名規則を使用します
• name-descriptive-exports - 内容がわかるエクスポート名を使用します

使用方法

詳細な説明とコード例については、各リファレンスファイルを読んでください。

• ブループリントのプロセス - プロジェクト固有の目標アーキテクチャを導き出す方法
• ブループリントのテンプレート - エージェントが最終状態のドキュメントを作成するために記入するテンプレート
• セクションの定義 - カテゴリ構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート
• 個別のルール：references/{prefix}-{slug}.md

関連スキル

• 機能の計画については、feature-spec スキルを参照してください
• データ取得については、tanstack-query スキルを参照してください
• React コンポーネントのパターンについては、react-19 スキルを参照してください

コンパイル済みの完全版ドキュメント

すべてのルールを展開した完全なガイド：AGENTS.md