file-organization

スキル：ファイル構成

対象範囲

• 対象：アプリやパッケージ内で関連する実装ファイルをまとめること、index.ts の公開 API、インポートパス、フォルダー名
• 対象外：Next.js の lucide スタイルのパッケージインポート最適化、Fastify のルート構成、Drizzle のスキーマ設計

前提条件

• TypeScript ESM を使用し、インポート指定子には .js 拡張子を付けます
• ディレクトリ名はケバブケースにします
• アプリ内グループのインデックスでは 名前付き 再エクスポートを使用します。パッケージのサブパスでは、そのフォルダーが公開モジュール境界である場合に export * を使用できます

原則

• 1 つの関心事に関する 2 つ以上の実装ファイル をフォルダーにまとめます
• すべてのエクスポートが同じランタイムを共有する場合、index.ts をグループの公開 API にします
• フォルダー内ではフォルダー名のプレフィックスを省きます（oauth-google.ts → oauth/google.ts）
• フォルダーの外からはグループをインポートします（.../feature/index.js）。フォルダー内では兄弟ファイルを直接インポートします
• 単一ファイルのモジュールはファイルのままにし、テストは実装の隣に配置します
• ランタイムが混在する場合は、名前付きエントリーファイルを持つフォルダーにし、統合インデックスは作成しません

制約

必須

• フォルダー名にはケバブケースを使用します
• アプリ内グループのインデックスでは名前付き再エクスポートを使用します（export * を使った巨大なバレルは避けます）
• フォルダーを作成する前に、ベース名の衝突を解決します（auth.ts と auth/）

禁止

• 親階層に巨大なバレルを追加しないでください（lib/index.ts、components/ui/index.ts）
• foo/foo.ts と薄い再エクスポート用インデックスを作成しないでください
• Fastify のオートロードツリー（routes/、plugins/）に index.ts を追加しないでください
• 異なるランタイムを使用するサーバーとクライアントのモジュールを、1 つのインデックスに統合しないでください

推奨

• グループのインデックスは、小さくまとまりのあるもの（1 つの機能領域）にします
• 再エクスポートによってインポート循環が発生する場合は、名前付きエントリーファイルを使用します
• 新しいルートバレルを追加するより、既存のパッケージサブパスを優先します

他のスキルとの関係

• next-v16 を補完します（バレルインポートの最適化と機能グループのインデックスは別物です）
• typescript-v6 を補完します（ESM パス、名前付きエクスポート）
• リポジトリのルールに例外（catalogs mapper、Drizzle schema index）が明記されている場合は、そちらがこのスキルより優先されます

パターン

グループインデックス（同じランタイム）

oauth/
  shared.ts
  google.ts
  index.ts    # named re-exports only

利用側：import { getOAuthAllowedCallbackUrls } from '../lib/oauth/index.js'

ランタイムの分割（統合インデックスなし）

logger/
  server.ts
  client.ts
  # no index.ts

利用側は名前付きエントリーファイル（logger/server、logger/client）を直接インポートします。

名前付きエントリー（循環の回避）

catalogs/
  index.ts      # dictionaries only
  mapper.ts     # imports from ./index.js — not re-exported

アンチパターン

パターン	理由
同じ階層でプレフィックスが乱立する	移動しにくくなります。フォルダーを使用してください
lib/index.ts ですべてを再エクスポートする	巨大なバレルとなり、ビルドを遅くし、境界を不明瞭にします
auth.ts と auth/ を並べる	モジュール解決で問題を引き起こす原因になります
cookies と document を統合するインデックス	サーバーとクライアントの境界を壊します