turborepo-architecture

Turborepo アーキテクチャ

Turborepo と Bun/pnpm のワークスペース向けの、移植可能なモノレポの標準構成です。このスキルだけで利用でき、ほかのスキルには依存しません。

役割： ワークスペースの配線、パッケージ境界、Turbo のタスク／キャッシュ、ルートスクリプト。

対象外： Turbo CLI の詳細なドキュメント、リモートキャッシュベンダーの設定、またはアプリ内の機能モジュール構成（HTTP ルート／Start ページは、そのスタックのアプリケーションアーキテクチャのドキュメントを参照してください）。

対象のリポジトリにモノレポのルール（例：AGENTS.md）がすでに記載されており、内容が競合する場合、ユーザーからこのスキルへの移行を求められていない限り、リポジトリのルールを優先します。

スタックのデフォルト設定（コア）

項目	デフォルト
パッケージマネージャー	Bun ワークスペース（すでに pnpm/npm を使用している場合はそれでも構いません）
レイアウト	apps/*、packages/*
オーケストレーション	Turborepo（turbo.jsonc / turbo.json）
内部パッケージ	"exports": { ".": "./src/index.ts" } — Bun は TypeScript を直接実行します
環境変数	アプリが .env と T3 Env の src/env.ts を管理し、パッケージは .make(options) を受け取ります
検証	完了時のチェックでは依存グラフ全体を使用し、編集途中の反復では --filter を使用します

モード

1. スキャフォールド — checklist.md と tree.md に沿って、新しいアプリ／パッケージを作成します。
2. 適用 — スクリプト、依存関係、Turbo への参加を適切に追加します。
3. レビュー — rules.md と照らし合わせ、変更案を提示します。

ハードルール（コア）

1. ワークスペースと共有バージョン指定 — 共有依存関係にはカタログ（または同等の仕組み）を使用し、ワークスペース依存関係には workspace:* を使用します。
2. Turbo がスクリプトをオーケストレーションします — Turbo はパッケージマネージャーではありません。パッケージスクリプトから、同じタスクに対して turbo run を再帰的に呼び出してはいけません。
3. transit DAG — スクリプトを持たない transit / topo ノードを dependsOn: ["^transit"] とともに使用し、依存パッケージのソース変更時に無効化しながら、typecheck / test を並列実行できるようにします。
4. 永続タスク／変更を加えるタスクはキャッシュしません — dev、ウォッチサーバー、format、lint:fix、typegen には cache: false を設定し、長時間実行されるプロセスには persistent: true も設定します。
5. Lint／format／test／typecheck はワークスペースごとのスクリプトにします。Turbo が実行し、スクリプトのないパッケージはスキップします。
6. 環境変数はアプリが管理します。パッケージのライブラリコードで process.env を読み取ってはいけません — オプションをファクトリー／Layer に渡します。
7. 内部エントリーポイントには、パッケージを公開／ビルドする場合（dist/）を除き、./src/index.ts を使用します。
8. パッケージ名で絞り込みます — 意図せずフォルダーパスで絞り込まず、--filter=@org/api を使用します。
9. 稼働中のモノレポでは、明確な破壊的変更を優先します — 同じ変更でシム／二重書き込み／非推奨のエイリアスを削除し、呼び出し元もまとめて更新します。
10. 完了時の検証では、ユーザーが品質チェックの延期を明示的に求めていない限り、依存グラフ全体を検証します。

詳細：rules.md、tree.md、examples.md。

段階的な参照

必要な情報	参照先
標準的な構成	references/tree.md
ルールとアンチパターン	references/rules.md
スキャフォールド／レビューのチェックリスト	references/checklist.md
良い構成と悪い構成	references/examples.md
オプションのオーバーレイ	以下の拡張機能

拡張機能

該当するスタックが存在する場合（またはユーザーから求められた場合）にのみ読み込みます。

条件	拡張機能
Bun workspaces.catalog／名前付きカタログ	with-catalog.md
ルートのみの Knip	with-knip.md
パッケージごとの Oxlint + Oxfmt	with-oxlint-oxfmt.md
Vitest スクリプト + turbo テストタスク	with-vitest-workspaces.md
アプリの環境設定とパッケージの .make	with-env-packages.md
パッケージ内の Effect サービス	with-effect-packages.md
オプトインの型生成／OpenAPI コード生成	with-typegen.md
ネストされた packages/<group>/* + 2 つ目のスコープ	with-engine-nested.md
turbo prune --docker + 空のルートディレクトリ	with-docker-deploy.md
明示的なインポート可否の表	with-dependency-boundaries.md
ローカルインフラ用のルート compose ヘルパー	with-compose-local.md

境界とアプリのアーキテクチャ

このスキルが担当するのはモノレポの配線とパッケージの境界です。アプリ内部の機能フォルダ構成（Elysia モジュール、TanStack Start のルート）は、そのアプリのアーキテクチャガイダンスに属します。ここで別の HTTP/UI 構成を考案しないでください。