file-organization

ファイル構成

「このコードベースでは、どのような構造上の境界を設けるべきか。また、再編を混乱させずに、その境界へどう移行すべきか」が主な問いである場合に、このスキルを使用します。

目的は、どのリポジトリにも当てはまるかのように、巨大なフォルダツリーを提示することではありません。 目的は、次のとおりです。

1. 実際に整理の単位となるものを特定する
2. 機能、共有、フレームワーク、パッケージの境界を分ける
3. 逸脱を防ぐ命名規則とインポート規則を定義する
4. 安全に移行できるよう計画する
5. 別のエンジニアやエージェントがすぐに適用できる構成の概要を提示する

構成を推奨する前に、references/boundary-decision-matrix.md を読んでください。 ファイルの移動やディレクトリ名の変更を行う前に、references/migration-checklist.md を読んでください。 問題にバレルファイル、エイリアスパス、またはチームの規約が含まれる場合は、references/naming-and-import-rules.md を読んでください。

このスキルを使用する場合

• 新しいリポジトリやアプリに、保守しやすいフォルダ戦略を選ぶ
• components/、hooks/、utils/、store/ フォルダが業務上の境界に合わなくなったリポジトリをリファクタリングする
• コードを機能モジュール、共有レイヤー、ルートセグメント、ワークスペースパッケージのどこに配置するか決める
• 大規模な再編や移行の前に、構成のずれを確認する
• 成長中のチーム全体で、命名、インポートパス、所有権のルールを標準化する
• モノレポ／ワークスペースへの分割が妥当か、時期尚早かを判断する
• インポートの破損、ファイルの重複、移動の中途半端な状態を最小限に抑える移行計画を作成する

このスキルを使用しない場合

• 主なタスクが再利用可能なコンポーネントの API、バリアント、またはスロット／プリミティブの合成を設計すること → design-system または design-system を使用します
• 主なタスクがフレームワークの状態の所有権、キャッシュ／ストアの境界、または URL／フォーム／サーバー状態の配置を決めること → state-management を使用します
• 主なタスクがマシン、サービス、ツールチェーン、またはコンテナをまたいでリポジトリを実行可能にすること → system-environment-setup を使用します
• 主なタスクがタスクランナー、ブートストラップスクリプト、フック、またはローカル CI コマンドの設計であること → deployment-automation を使用します
• 主なタスクがデプロイのトポロジー、またはホスト型 CI/CD のロールアウトであること → deployment-automation または vercel-deploy を使用します
• リポジトリで必要なのが、アーキテクチャ上の判断を伴わない小規模で機械的なファイル移動だけであること。その場合は構成設計をやり直さず、直接移動を実施します

手順

ステップ 1：フォルダを描く前に、構造上の課題を分類する

まず、依頼を次の形式に整理します。

structure_intake:
  repo_shape: single-app | app-plus-api | monorepo | library-cli | content-site | unknown
  current_pattern: type-based | feature-based | route-colocated | package-workspace | mixed | unknown
  main_pressure:
    - scattered-feature-code
    - unclear-shared-boundaries
    - framework-routing-collision
    - premature-monorepo-split
    - monorepo-needed-now
    - naming-drift
    - import-chaos
    - migration-risk
    - onboarding-confusion
    - unknown
  change_scope: greenfield | incremental-refactor | major-reorg | audit-only
  primary_boundary_unit: feature | shared-layer | route-segment | package | unknown
  confidence: high | medium | low

ユーザーの説明が曖昧な場合は、明らかに最小限の解釈を選び、その前提を明記します。

ステップ 2：主要な構成モードを 1 つ選ぶ

今回の実行では、主要なモードを必ず 1 つだけ選びます。

1. スターターの整理
   • 型ごとに分けたスターター構成が、まだ固まる前に修正できる規模である場合に使用します。
2. 機能のモジュール化
   • 業務領域が技術別フォルダに分散しており、機能ごとの所有権が必要な場合に使用します。
3. フレームワークのコロケーション
   • Next.js などのルーター規約に沿って、ルートセグメントへの配置を決める場合に使用します。
4. 共有レイヤーのガバナンス
   • リポジトリにすでに機能が存在する一方で、共有コードがあちこちに漏れ出している場合に使用します。
5. ワークスペース分割
   • 複数の実行可能なアプリ／サービス／パッケージがあり、apps/ と packages/ の境界が正当化される場合に使用します。
6. 移行の監査
   • リポジトリに必要なのが、新しい構成案よりも安全な移動計画である場合に使用します。

Step 3: 問題を解決できる最小の境界単位を選ぶ

次のルールに従います。

• 同じ業務領域でコンポーネント、フック、データアクセス、テスト、状態管理が一体となっている場合は、機能フォルダーを優先します。
• 共有レイヤーを使うのは、複数の機能で再利用され、所有者が明確なコードに限ります。
• ルーティング、レイアウト、ファイル規約の意味がアーキテクチャの一部であり、単なるファイル保存方法ではない場合は、フレームワークのコロケーションを優先します。
• ワークスペースパッケージを使うのは、デプロイ可能な複数のアプリ／サービス、再利用可能なライブラリ、または独立した依存関係／ランタイム要件がある場合に限ります。
• リポジトリが雑然としていると感じるだけで、パッケージ分割を進めてはいけません。多くのリポジトリに必要なのは、モノレポではなく、機能と共有コードに関するルールの改善です。
• 生成物、ドキュメント、スクリプト、テストは明確に分け、曖昧なユーティリティーフォルダーに埋もれさせないでください。

Step 4: 判断の順序に従う

次の場合は機能ごとにモジュール化する

• 1つのユーザー向け機能を理解するために、現在、多数の技術フォルダーにまたがるファイルを開く必要がある
• 1つのドメインの変更で、繰り返し components/、hooks/、utils/、api/、store/ に手を入れている
• チームが機能または業務領域ごとの明確な責任範囲を必要としている

次の場合はフレームワークのコロケーションを使う

• ルートセグメント、ローダー、レイアウト、サーバー／クライアントの境界、またはファイル規約によって、コードの配置場所が決まる
• フレームワークのドキュメントですでに特別なファイルや予約済みパスが定義されている
• 本来の目的は、フレームワークに逆らうことなくルート／機能を中心に整理することである

次の場合は共有レイヤーのガバナンスを適用する

• リポジトリにすでに機能ごとの構成がある一方で、共有フォルダーが何でも入る場所になっている
• 何かが本当に共有されているのか、単に2回再利用されているだけなのか、チーム内で頻繁に議論になる
• インポートパスやバレルファイルによって境界が見えにくくなっている

次の場合はワークスペースを分割する

• リポジトリに、依存関係や実行環境が異なる複数のアプリ／サービス／パッケージが含まれている
• 共有ライブラリに、バージョン管理された明示的なパッケージ境界が必要である
• パッケージごとにビルド／テスト／デプロイ上の要件が実質的に異なる

次の場合は移行監査を行う

• 構成の方針はほぼ固まっているものの、慎重に進めないと、移動によってインポート、ドキュメント、テスト、責任範囲が壊れる可能性がある
• チームが段階的な移行、エイリアス、コードモッド、または互換性を保つためのシムを必要としている

Step 5: 構造上の境界を明確にする

適切な構成案では、何を担当しないのかも明示します。

例：

• 本質的な課題が再利用可能なコンポーネントプリミティブと API の形状なら、design-system を案内します
• 本質的な課題がデザイントークン／ライブラリ全体の UI ガバナンスなら、design-system を案内します
• 本質的な課題がランタイム／サービス／ツールチェーンのセットアップなら、system-environment-setup を案内します
• 本質的な課題が繰り返し使うスクリプトとタスクのエントリーポイントなら、deployment-automation を案内します
• 本質的な課題が状態管理／キャッシュの責任範囲なら、state-management を案内します

複数の要望が混在するのはよくあることです。1つのフォルダー戦略ですべてを解決しようとせず、明確に分けてください。

Step 6: 再利用可能な命名ルールとインポートのガードレールを定める

推奨する構成では、次のルールをそれぞれ明示します。

• ディレクトリーの目的 — ここに何を置き、何を置かないか
• 命名スタイル — フォルダーとファイルの大文字・小文字の規約
• 共有と機能のルール — コードを共有フォルダー／パッケージに移す条件
• 公開 API のルール — 機能／パッケージのエクスポートを1つの境界ファイル経由にするかどうか
• インポートのルール — 隣接する機能間の深いインポートを禁止するかどうか
• テスト／ドキュメント／ストーリーの配置ルール — 機能と同じ場所に置くか、方針に基づいて一元管理するか

よくない兆候：

• utils/ や shared/ が、何でも入る場所になっている
• 機能のコードが、最上位の技術フォルダー5つに分散している
• 責任範囲を曖昧にし、暗黙の密結合を招くバレルファイル
• 実際のパッケージ／ランタイム境界がないのに、apps/ + packages/ への移行を進めている
• フレームワークの特別なファイルが、コロケーションのルールもないまま、無関係なドメインロジックと混在している

ステップ 7：ファイルを変更する前に移行計画を立てる

何かを移動する前に、次の項目を網羅した変更計画を作成します。

1. 現在のホットスポットと、それが扱いにくい理由
2. 目標とする境界モデル
3. 段階的な移動順序
4. エイリアス／インポートまたはバレルによる互換性維持の方針
5. テスト／ビルド／ドキュメントの検証手順
6. ロールバックまたは部分的な導入に対する安全策

リポジトリが活発に開発されている場合は、ひとまとめの大規模な名前変更より、段階的なリファクタリングを優先します。

ステップ 8：ファイル構成の概要を作成する

すぐに実行に移せる、簡潔な成果物を提示します。

推奨形式：

# File Organization Brief

## Mode
- Primary mode:
- Why this mode fits:

## Boundary choice
- Primary organizing unit:
- What belongs in feature/shared/route/package boundaries:
- What stays out of scope:

## Recommended structure
- Top-level folders/packages:
- One example feature/package layout:
- Naming/import rules:

## Migration plan
1. First step
2. Second step
3. Verification step

## Handoffs
- Adjacent skills:
- Risks / follow-up work:

ステップ 9：テンプレートへの盲従より明確さを優先する

既存の構成を刷新する場合：

• 流行のテンプレートではなく、現在のリポジトリが抱える課題に沿った提案にします
• 役立つ場合はフレームワークの規約を活用しますが、フレームワークのファイルをアーキテクチャ全体と混同しないようにします
• コードを最小限で長く使える境界モデルへ移行します
• 命名規則とインポート規則を、細かな整理ではなくアーキテクチャの一部として扱います
• フロントエンド、バックエンド、フルスタックのリポジトリに共通する、応用可能な原則を維持します

出力形式

必ず ファイル構成の概要、リポジトリ構成の推奨案、または 移行監査 を返します。

必須要件：

• 構成を提案する前に、構成上の問題を分類する
• 主となる構成モードを 1 つ選ぶ
• 境界の単位を明示する
• 関連するスキルへの誘導先を含める
• 命名規則とインポートのガードレールを示す
• 既存のリポジトリについては移行計画を含める

例

例 1：型別のスターター構成が限界を迎えている

入力

components、hooks、utils、store がありますが、チェックアウトの変更のたびに 4 つすべてのフォルダーに手を入れています。この React アプリをどう再構成すればよいでしょうか？

望ましい出力の方向性

• モード：feature modularization
• チェックアウト／認証／カタログ用のフィーチャーフォルダーと、小規模な共有レイヤーを推奨する
• コードを共有領域に移せる条件を定めるルールを追加する
• 状態の所有権に関する具体的な内容は state-management に誘導する

例 2：Next.js のルートフォルダーが散らかってきた

入力

Next.js の App Router リポジトリで、ルートファイル、データ用ヘルパー、ビジネスロジックが app/ 内のあちこちに混在しています。フレームワークの規約を尊重しながら、すっきりした構成にしたいです。

望ましい出力の方向性

• モード：framework colocation
• Next.js が想定する場所に特別なルートファイルを置く
• ルート固有のコードはルートセグメント内にまとめ、再利用可能なドメインロジックはルート専用ファイルの外にあるフィーチャー／共有境界へ移す
• URL を変更せずに整理できる場合は、ルートグループやプライベートフォルダーに言及する

例 3：チームがパッケージへの分割を検討している

入力

このリポジトリを apps/ と packages/ に分割するべきでしょうか？ 現在、ウェブアプリ、ワーカー、共有 UI ライブラリがあります。

望ましい出力の方向性

• モード：workspace split
• 実行可能なターゲットと共有ライブラリを基準に、パッケージ境界の必要性を説明する
• デプロイ対象には apps/、再利用可能なライブラリやツールには packages/ を推奨する
• 最終的なツリーを示すだけでなく、移行手順と検証手順を含める

ベストプラクティス

1. 好みのアーキテクチャの流行語ではなく、リポジトリが抱える課題から始める。
2. 変更による影響範囲の拡大を抑える、最小限の境界モデルを優先する。
3. 共有コードは既定の配置先ではなく、ルールで管理される例外として扱う。
4. フレームワークの規約を構成の参考にしつつ、意図せず雑多な置き場にならないようにする。
5. 依存関係、ランタイム、デプロイ対象が本当に必要とする場合に限り、パッケージに分割する。
6. インポートと公開 API のルールは早い段階で定める。これらも構成システムの一部である。
7. 稼働中のリポジトリでは、段階的な移行と検証手順を用いる。

参考資料

• Feature-Sliced Design のフォルダー構成に関する記事
• Bulletproof React の README
• Bulletproof React のプロジェクト構成
• Next.js のプロジェクト構成に関するドキュメント
• Turborepo のリポジトリ構成に関するドキュメント
• MIT Comm Lab のファイル構成に関するガイダンス