コードベースの構成：レイヤー・フィーチャー・ドメイン、どれを選ぶ？

新しいプロジェクトを開いて、ロジックを一行も書く前に最初にすることは――フォルダーを作ることです。controllers/ と名付けるかもしれません。orders/ かもしれません。どちらにしても、その静かな選択はすでにアーキテクチャの決定であり、その後のすべてを静かに形作ります：新しいチームメンバーがどれほど速く足場を見つけるか、一つの機能が変わったときにいくつのファイルを触るか、そして六ヶ月後にコードベースがあなたのビジネスのように読めるかフレームワークのように読めるかです。

この記事は三つの主なアプローチ――レイヤー別・フィーチャー別・叫ぶ（ドメイン別）――の実践的なツアーです。各会社の規模ごとの正直なトレードオフを添えています。一つの答えがすべての状況に勝つわけではありませんが、デフォルトではなく意図的に選択するための明確なメンタルモデルを持ってここを離れられるはずです。

フォルダー構造がアーキテクチャの決定である理由――細かい話ではない

人々はフォルダー構造を「ただの整理」と軽視します。それははるかに多くのことを意味します。コードをどうグループ化するかは、非常に重要であることがわかる三つのことを制御します：

• カップリング。一緒に変わるコードが遠く離れて住んでいると、小さな更新が毎回フォルダーをまたいだ遠征になります。一緒に住んでいれば、関連する変更は一つの場所にまとまります。
• 発見可能性。コードベースに不慣れな開発者は「課金コードはどこにあるか？」と尋ねます。その答え――一つのフォルダー、または五つの散らばったフォルダー――がオンボーディング時間を決めます。
• 影響範囲。新しい機能を追加したり古い機能を安全に削除したりするためにいくつのファイルを開かなければならないか？構造はその影響範囲を制限するか、制御なく広がるままにするかのどちらかです。

ソフトウェアシステムは、それを構築したチームのコミュニケーション構造を反映するという Conway の法則もここに適用されます。チームがビジネス機能（決済スクワッド・注文スクワッド）を中心に組織されているなら、フィーチャー別の構造は自然に感じられ、正しいバウンダリーを強制します。レイヤー別の構造はあなたと戦うことになります。

レイヤー別：おなじみのデフォルト

レイヤー別の整理は、技術的な役割でファイルをグループ化します。典型的な Node や Spring Boot プロジェクトはこのような形になります：

src/
├─ controllers/
│  ├─ OrderController.ts
│  ├─ UserController.ts
│  └─ BillingController.ts
├─ services/
│  ├─ OrderService.ts
│  ├─ UserService.ts
│  └─ BillingService.ts
├─ repositories/
│  ├─ OrderRepository.ts
│  ├─ UserRepository.ts
│  └─ BillingRepository.ts
└─ models/
   ├─ Order.ts
   ├─ User.ts
   └─ Invoice.ts

すべてのWebフレームワークのチュートリアルがここに行き着きます。Rails もそうです。Spring Boot のスターターもそうです。Express のジェネレーターもそうです。そのなじみ深さが主な資産です。

レイヤー別が輝く場所：

• 二〜三の機能を持つ小さなアプリ――構造が非常にフラットなので、ほとんど問題になりません。
• 全員がすべての機能をまたいで作業するチーム；レイヤーが専門化の単位です。
• 初期セットアップのスピードが長期的な明確さに勝るプロトタイプや内部ツール。

レイヤー別が痛む場所：

• 一つの機能がフォルダー全体に散らばっている。「払い戻し」機能を追加するには controllers/・services/・repositories/・models/ を触る必要があります。概念的には一つのことなのに四つのフォルダーです。
• 機能を削除することが考古学の作業になる。services/ のどのファイルが課金に属し、どれが注文に属するか、どうやってわかりますか？フォルダー名は教えてくれません。
• マージコンフリクトが増える。すべての機能変更が同じレイヤーレベルのファイルを触り、二人の開発者が並行して作業するときに衝突が起きます。

フィーチャー別：変更は一つのフォルダーに収まる

フィーチャー別の整理は、それが担うプロダクトのスライスでファイルをグループ化します。技術レイヤー（コントローラー・サービス・モデル）は依然として存在します――ただし、トップレベルではなく各フィーチャーフォルダーの内部に住みます：

src/
├─ orders/
│  ├─ OrderController.ts
│  ├─ OrderService.ts
│  ├─ OrderRepository.ts
│  └─ Order.ts
├─ billing/
│  ├─ BillingController.ts
│  ├─ BillingService.ts
│  ├─ BillingRepository.ts
│  └─ Invoice.ts
├─ auth/
│  ├─ AuthController.ts
│  ├─ AuthService.ts
│  └─ User.ts
└─ shared/
   ├─ database.ts
   ├─ logger.ts
   └─ Money.ts

フィーチャー別が輝く場所：

• 変更は一つのフォルダーに収まる。払い戻しフローを追加するには billing/ 内にファイルを追加します――他のフォルダーは触られません。影響範囲は小さく封じ込められています。
• 機能の削除がシンプル。フォルダーを削除します。外から何かがまだインポートしているなら、IDEがすぐに教えてくれます。
• オーナーシップが明白。決済チームが billing/ を所有し、アイデンティティチームが auth/ を所有します。モノレポのツールとコードレビュールールがこれを機械的に強制できます。
• オンボーディングが速い。注文に取り組む新入社員は orders/ だけを読みます。最初にコードベース全体を理解する必要はありません。

フィーチャー別が注意を要する場所：

• 共有コードの配置が厄介。Money 型は orders/ と billing/ の両方で使われます。orders/ に置くのは違和感があります。結局 shared/ に入りますが、誰も所有しなければそれ自体が第二のがらくた引き出しになりえます。
• フィーチャーをまたぐ依存には規律が必要。orders/OrderService.ts が billing/BillingService.ts から直接インポートすると、フォルダー構造が見えないカップリングを作ってしまいます。チームはリンティングルール（eslint-plugin-import/no-restricted-paths）やモジュール境界ツール（Nx・NestJS モジュール）を使って、これらを明示的にします。

Screaming Architecture：トップレベルは何を語るか？

Uncle Bob（Robert C. Martin）は有名なブログ投稿で Screaming Architecture という用語を作りました：「あなたのアプリケーションのアーキテクチャは何を叫んでいますか？トップレベルのディレクトリ構造と最上位パッケージのソースファイルを見たとき、それは叫んでいますか：ヘルスケアシステム、または会計システム、または在庫管理システム？それとも叫んでいますか：Rails、またはSpring/Hibernate、またはASP.Net？」

洞察はエレガントです：トップレベルのフォルダーが controllers/・models/・views/ なら、コードベースは MVCフレームワークを叫んでいます。フレームワークはツールです――読者が最初に出会うべきものではありません。

Screaming Architecture（ドメイン別とも呼ばれる）はフィーチャー別をもう一歩進めます。機能がトップレベルにあるだけでなく――それらの機能の名前は技術的な役割ではなく、ビジネス言語（ドメイン駆動設計のユビキタス言語）から直接引かれています：

// 「eコマースプラットフォーム」を叫ぶ
src/
├─ catalog/          // ドメイン概念：商品カタログ
├─ ordering/         // ドメイン概念：注文の配置と追跡
├─ fulfillment/      // ドメイン概念：ピッキング・梱包・出荷
├─ payments/         // ドメイン概念：請求・返金・請求書
└─ identity/         // ドメイン概念：アカウント・認証・権限

// フレームワークを叫ぶ代替案と比較：
src/
├─ controllers/      // 「MVC」を叫ぶ
├─ models/           // 「ORM」を叫ぶ
├─ views/            // 「テンプレートエンジン」を叫ぶ
└─ services/         // 「サービスレイヤーパターン」を叫ぶ

各ドメインフォルダーの内部レイアウトはチームに任されています――それで構いません。肝心なのは、トップレベルがインフラストラクチャではなくビジネスを伝えることです。新しい開発者（あるいはCTO・ビジネス側のドメインエキスパート）がトップレベルのフォルダーを読んで、どうやって作られているかを知らなくてもシステムが何をするかを理解できれば、成功です。

並べて比較

五つの実践的な次元にわたる正直な評価です：

良いチームがたどり着く実用的なハイブリッド

実際には、優れたチームは一つのアプローチを選んで宗教的な一貫性ですべてに適用するわけではありません。実用的なハイブリッドを使います：トップにフィーチャーまたはドメインフォルダー、その中に小さな技術レイヤー。

このハイブリッドは両方の良いところを手に入れます：

• トップレベルはビジネスを叫びます――新メンバーはすぐにこれがeコマースアプリであり、一般的なMVCのスケルトンではないことを知ります。
• 各フィーチャーが自己完結しています――課金フローへの変更は billing/ だけを触ります。
• 技術レイヤーは各フォルダーの内部に依然として存在しますので、MVCや Clean Architecture レイヤーで考える開発者は迷いません。フィーチャーフォルダーの内側を見るだけです。
• shared/ フォルダーが本当に横断的な関心事（Money 値オブジェクト・ロガー・データベース接続）を保持します。肝心なルール：shared/ に何かを追加する場合、それは逃げ道として捨てるのではなく、意図的に抽出・所有されるべきです。

チームのスケールで：強制されたバウンダリーとモノレポ

コードベースが成長して複数のチームが貢献するようになると、フォルダーの慣習だけでは不十分です――開発者はいつでも相対インポートでバウンダリーをまたぐことができます。次のステップはバウンダリーを強制することです：

• NestJS モジュールはモジュール間の依存を明示的にします：別のモジュールが exports するものへのアクセスだけが得られます。パブリックAPIを通らないモジュール境界をまたぐインポートはコンパイルエラーです。
• Nx のバウンダリールールで、どのフィーチャーまたはライブラリが他のどれに依存することを許可されるかを宣言し、CIのリントエラーとして強制できます。
• モノレポはこれを最も遠くまで進めます：各ドメイン（注文・課金・認証）が独自の package.json・独自のテスト・明示的に公開されたエクスポートを持つ独自パッケージになります。Turborepo と Nx が JavaScript エコシステムでこれを管理する主要なツールです。構造はフォルダーツリーよりパッケージのグラフに近くなります――しかし根本的なアイデアは同じです：ビジネス機能別にグループ化し、バウンダリーを明示的にし、機械的に強制する。

モノレポへの移行が常に必要なわけではありません。多くのチームは単一パッケージとよく規律されたハイブリッド構造で何年もうまくやっています。クロスチームのカップリングが本当の痛みになったとき――予防的にではなく――モノレポツールに手を伸ばしましょう。

会社の規模ごとの推奨

適切な構造は、今日あなたの組織がどこにあるかによります。各ステージへの直接的な推奨です：

違いを見る：機能を追加したときに何が点灯するか

レイヤー別とフィーチャー別の違いを感じる最も具体的な方法は、問うことです：新しい機能を追加するとき、どのボックスが点灯するか？

この図はフィーチャーベースのグループ化に対する最も明確な論拠です。「影響範囲」は抽象的な概念ではありません――それは一つのプルリクエストで開くフォルダーとファイルの数です。レビュアー・CIパイプライン・git blame はすべて、機能変更が一つの凝集したかたまりであり、すべてのレイヤーに薄く塗られたものではないときに、よりうまく機能します。

単一のサービス内でコードをどう構成するかを見てきたので、次の自然な質問は、一つのサービスでは不十分になったときに何をするかです。続きはこちら：モノリス → マイクロサービス。