file-organizer

ファイル構成

概要

チームやコードベースの成長に合わせて拡張できる、整理されたプロジェクト構造を設計し、維持します。このスキルでは、モノレポのパターン、機能ベースとレイヤーベースのアーキテクチャ、命名規則、インデックス／バレルファイル、設定ファイルの配置、ドキュメントの構成について扱います。

プロジェクトのファイル構成を明確さと拡張性のために確立、監査、または再構成する必要がある場合は、いつでもこのスキルを適用してください。

複数フェーズのプロセス

フェーズ 1：評価

1. 現在のプロジェクト構造を監査し、課題を特定します
2. プロジェクトの規模を測定します（ファイル数、チームの人数、機能数）
3. 既存の命名規則とインポートパターンを特定します
4. 設定ファイルの配置場所を一覧にします
5. 循環依存や深い階層がないか確認します

停止 — 現状とその課題を把握せずに、新しい構造を提案してはいけません。

フェーズ 2：方針の選定

1. 以下の判断表を使って構成方針を選択します
2. 命名規則とファイル配置のルールを定義します
3. バレルエクスポートの境界を計画します
4. 設定ファイルの配置ルールを確立します
5. インポート順の規約を文書化します

停止 — 目標とする構造を文書化し、チームの合意を得るまでは、移行を開始してはいけません。

フェーズ 3：移行計画

1. 既存プロジェクトの移行経路を計画します（一括ではなく段階的に）
2. 移動するファイルと移動先を特定します
3. 必要なインポート変更を対応付けます
4. 可能な場合は、自動化された codemod を作成します
5. 移行によって問題が発生した場合のロールバック計画を定義します

停止 — 段階ごとにテストが通ることを確認せずに、移行を実行してはいけません。

フェーズ 4：実行と検証

1. 一度に 1 つの機能またはモジュールを移動します
2. 自動化ツールを使ってインポートを更新します
3. 移動のたびにテストが通ることを確認します
4. 移行が完了したら古い構造を削除します
5. チームが参照できるように規約を文書化します

アーキテクチャ方針の判断表

プロジェクトの規模	チームの人数	推奨	理由
< 20 ファイル	開発者 1～2 人	レイヤーベース	シンプルで、オーバーヘッドが少ない
20～100 ファイル	開発者 2～5 人	ハイブリッド	シンプルさと拡張性のバランスが取れている
100+ ファイル	開発者 5 人以上	機能ベース	自己完結型のモジュールによって競合が減る
コードを共有する複数のアプリ	任意	モノレポ	境界が明確な共有パッケージを利用できる
迅速なプロトタイプ／MVP	開発者 1～3 人	レイヤーベース	構造よりスピードを優先し、後でリファクタリングする
複数チームが関わるエンタープライズ	10 人以上	機能ベース + モノレポ	機能モジュールごとにチームの担当範囲を定められる

アーキテクチャパターン

機能ベース（ドメイン駆動）

ビジネスドメインごとに整理します。各機能は自己完結しています。

src/
  features/
    auth/
      components/
        LoginForm.tsx
        SignupForm.tsx
      hooks/
        useAuth.ts
      api/
        auth.api.ts
      types/
        auth.types.ts
      utils/
        auth.utils.ts
      __tests__/
        auth.test.ts
      index.ts          # Public API (barrel export)
    dashboard/
      components/
      hooks/
      api/
      types/
      index.ts
    billing/
      ...
  shared/               # Cross-feature shared code
    components/
      Button.tsx
      Modal.tsx
    hooks/
      useDebounce.ts
    utils/
      format.ts
    types/
      common.types.ts

最適な対象：開発者 5 人超のチーム、中～大規模アプリケーション、明確なドメイン境界。

レイヤーベース（技術）

技術的な関心事ごとに整理します。

src/
  components/
    Button.tsx
    Modal.tsx
    LoginForm.tsx
    DashboardCard.tsx
  hooks/
    useAuth.ts
    useDebounce.ts
  services/
    auth.service.ts
    billing.service.ts
  utils/
    format.ts
    validation.ts
  types/
    auth.types.ts
    billing.types.ts
  pages/
    Home.tsx
    Dashboard.tsx

最適な対象：小規模チーム（1～3 人）、シンプルなアプリケーション、迅速なプロトタイピング。

ハイブリッド（デフォルトとして推奨）

共有レイヤーと機能モジュールを組み合わせます。

src/
  app/                  # App-level concerns
    layout.tsx
    providers.tsx
    routes.tsx
  features/             # Feature modules
    auth/
    dashboard/
    billing/
  components/           # Shared UI components
    ui/                 # Design system atoms
    layout/             # Layout components
  hooks/                # Shared hooks
  lib/                  # Shared utilities
  types/                # Shared types
  config/               # App configuration
  styles/               # Global styles

モノレポのパターン

Turborepo / pnpm Workspaces

root/
  apps/
    web/                # Next.js web app
      package.json
    api/                # API server
      package.json
    mobile/             # React Native app
      package.json
  packages/
    ui/                 # Shared component library
      package.json
    config/             # Shared configs (ESLint, TypeScript)
      eslint/
      typescript/
      package.json
    utils/              # Shared utilities
      package.json
    types/              # Shared type definitions
      package.json
  package.json          # Root workspace config
  turbo.json            # Turborepo pipeline config
  pnpm-workspace.yaml

パッケージの境界

• アプリはパッケージに依存します。他のアプリには依存しません
• パッケージは他のパッケージに依存できます
• 循環依存は禁止です
• 各パッケージには、明確で単一の責務があります
• 共有パッケージは index.ts バレル経由でエクスポートします

設定の共有

// packages/config/typescript/base.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/config/typescript/nextjs",
  "include": ["src"]
}

命名規則

ファイルとディレクトリ

種類	規則	例
コンポーネント	PascalCase	UserProfile.tsx
フック	use を接頭辞とする camelCase	useAuth.ts
ユーティリティ	camelCase	formatDate.ts
型	.types を接尾辞とする camelCase	auth.types.ts
テスト	.test を接尾辞として同じ名前を使用	UserProfile.test.tsx
スタイル	.module.css を接尾辞として同じ名前を使用	UserProfile.module.css
定数	ファイル名は camelCase または UPPER_SNAKE	config.ts
API／サービス	.api または .service を付けた camelCase	auth.api.ts
ディレクトリ	kebab-case	user-profile/

コンポーネントファイルの命名

# Single-file component
Button.tsx

# Component with co-located files
Button/
  Button.tsx
  Button.test.tsx
  Button.stories.tsx
  Button.module.css
  index.ts            # Re-exports Button

インポート順の規約

// 1. External packages
import React from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Internal packages (monorepo)
import { Button } from '@repo/ui';

// 3. Feature-level imports
import { useAuth } from '@/features/auth';

// 4. Relative imports (same feature)
import { LoginForm } from './LoginForm';
import { authSchema } from './auth.types';

// 5. Styles
import styles from './Auth.module.css';

インデックスファイルとバレルエクスポート

バレルエクスポートのパターン

// features/auth/index.ts — Public API
export { LoginForm } from './components/LoginForm';
export { useAuth } from './hooks/useAuth';
export type { User, AuthState } from './types/auth.types';

// Do NOT export internal implementation details
// Do NOT export utility functions used only within the feature

バレルエクスポートの判断表

コンテキスト	バレルを使用するか	理由
フィーチャーモジュールのパブリック API	はい、常に	明確な境界と、制御された公開範囲を保てます
共有コンポーネントライブラリ	はい、常に	利用側にとって単一のインポートポイントになります
ユーティリティライブラリ	はい、常に	共有関数を見つけやすくなります
フィーチャー内（内部）	いいえ	直接インポートし、間接参照を避けます
循環依存が発生する場合	いいえ	循環を解消し、直接インポートします
ツリーシェイキングを損なうことが確認された場合	いいえ	バンドルサイズを抑えるため、直接インポートします

設定ファイルの配置

ルートレベルの設定

root/
  .editorconfig         # Editor settings
  .eslintrc.js          # ESLint config (or eslint.config.js)
  .gitignore            # Git ignore rules
  .prettierrc           # Prettier config
  .env.example          # Environment variable template
  docker-compose.yml    # Docker composition
  Dockerfile            # Container build
  package.json          # Dependencies and scripts
  tsconfig.json         # TypeScript config
  next.config.js        # Framework config
  tailwind.config.ts    # Tailwind config
  vitest.config.ts      # Test config

環境ファイル

.env                    # Local defaults (gitignored)
.env.example            # Template with dummy values (committed)
.env.local              # Local overrides (gitignored)
.env.development        # Development-specific (committed or not)
.env.production         # Production-specific (committed or not)
.env.test               # Test-specific (committed or not)

ドキュメントの構成

docs/
  architecture/
    adr/                # Architecture Decision Records
      001-framework.md
      002-database.md
    diagrams/
  api/                  # API documentation
  guides/
    getting-started.md
    deployment.md
  contributing.md

移行戦略

段階的な移行（推奨）

1. 既存のコードと並行して、移行先の構成を作成します
2. 一度に1つずつフィーチャー／モジュールを移動します
3. 自動コードモッドを使用してインポートを更新します
4. 移動のたびにテストを実行して確認します
5. 移行が完了したら、古い構成を削除します

自動化ツール

• ts-morph：プログラムによる TypeScript のリファクタリング
• jscodeshift：JavaScript のコードモッド
• IDE のリファクタリング：自動インポート更新を伴う名前変更／移動
• ESLint import/order：インポート順序を強制

アンチパターン／よくある間違い

アンチパターン	うまくいかない理由	代わりに行うこと
フォルダーの過度な階層化（4 階層超）	移動しにくく、インポートパスが長くなります	構成をフラット化し、パスエイリアスを使用します
utils/ を何でも入れる場所にする	保守できない雑多なフォルダーになります	ユーティリティをドメインまたは目的ごとに整理します
フィーチャー間の循環依存	ビルドの失敗や、所有者の不明確化を招きます	フィーチャーからは共有モジュールまたは自身のモジュールのみをインポートします
すべてを再エクスポートするバレルエクスポート	ツリーシェイキングを損ない、バンドルを肥大化させます	パブリック API のみをエクスポートします
一貫性のない命名（複数の規約が混在）	認知負荷やマージ競合を招きます	規約を1つ選び、リンターで徹底します
複数の場所に設定を分散させる	見つけにくく、保守しにくくなります	すべての設定をプロジェクトルートに置きます
テストを別のディレクトリツリーに置く	ファイルに対応するテストを見つけにくくなります	テストをソースコードと同じ場所に置きます
1つのフラットなフォルダーに100個以上のファイルを置く	移動が困難になります	サブモジュールまたはフィーチャーごとにグループ化します
インデックスファイルにロジックを含める	インポート時に予期しない副作用が発生します	インデックスファイルでは再エクスポートのみを行います
一度にすべてを移動する一斉移行	リスクが高く、ロールバックが困難です	段階的に移動し、そのたびにテストを行います

安易な正当化を防ぐためのガード

• 現在の問題点を理解せずに再構成しないでください。まず評価してください。
• チームの合意形成を省略しないでください。構成の変更は全員に影響します。
• すべてを一度に移行しないでください。テストで確認しながら、一度に1つのモジュールを移動してください。
• 「将来の拡張性」のために深くネストした構成を作らないでください。複雑さが必要になるまではフラットに保ってください。
• バレルエクスポートがバンドルサイズに与える影響を無視しないでください。バンドルアナライザーで確認してください。

統合ポイント

スキル	関連性
senior-frontend	フロントエンドのプロジェクト構成では、フィーチャーベースまたはハイブリッドのパターンに従います
senior-architect	アーキテクチャ上の判断が、モジュールの境界とパッケージ構成に反映されます
senior-fullstack	フルスタックプロジェクトでは、フロントエンドとバックエンドの構成を連携させる必要があります
clean-code	命名規約とモジュールの境界が、クリーンコードの原則を支えます
deployment	モノレポの構成は、CI/CD パイプラインの設定に影響します
laravel-specialist	Laravel プロジェクトでは、フレームワーク固有のディレクトリ規約に従います

スキルの種類

FLEXIBLE — プロジェクトの規模、チーム構成、複雑さに合った整理戦略を選択してください。命名規約とバレルエクスポートのパターンは推奨事項であり、既存のプロジェクト規約に合わせて調整してください。