AI時代のフォルダ構造：Role-first（役割優先）はオワコンなのか？

この記事のまとめ¹

• 🤖 AIネイティブな構造の台頭: AIエージェントが文脈を読みやすい「バーティカルスライス」や「ドメイン中心」が今のトレンドです
• 💀 役割別（技術役割別）ディレクトリ構成は本当にオワコンか？: 結論から言うと、オワコンではありません。言語やフレームワークの「自由度」によっては、むしろ役割別構成が有利なケースがあります
• 🛠️ AI時代の生存戦略: プロジェクトの特性に合わせて構造を選び、AGENTS.md や @see コメントでAIの「探索の取りこぼし」を防ぐ具体的なノウハウを解説します

はじめに

2025年末以降、より良い推論により多くの重み（計算資源）を割り当てるアプローチが広がり、LLMの推論能力は目に見えて向上しました。こうしたモデルが出てきたことで、人間が直接コードを書く比重も急速に下がりつつあります。

これまでLLMを単なる検索やコードスニペットの参照用途として使っていた開発者も、いまはAIがもたらす圧倒的な生産性向上を前に、バイブコーディングや仕様駆動開発の導入を検討する流れになってきました。

レガシーコードを大量に抱える企業も例外ではありません。AIが要求事項をより明確に理解し、コード修正・変更の成功率を高められるように、ドメイン駆動設計（DDD）を導入したり、既存システムをAIネイティブな構造へ再編して生産性を最大化しようとする取り組みが、重要な選択肢になりつつあります。

AIコーディングエージェントが限られた文脈の中で作業する状況では、ドメイン間の境界を明確にすることが生産性に大きく影響します。ポイントは、AIモデルに限られたコンテキストウィンドウの中で必要なコードだけを集中して読ませ、他ドメインへの影響を最小化することです。そうすると、人間が直接コードを修正・補正する介入をできるだけ減らせます。だからこそAI時代は、ドメイン境界をどう切り出すか、そしてそれをフォルダ構造と規約でどう表すかが、以前よりもさらに重要になりました。

DDDを考えると、自然とフォルダ構造についても考えざるを得ません。AIコーディングエージェントに尋ねると、「AI時代はファイル探索がしやすいドメイン中心構造やバーティカルスライスが有利です」と答えることが多いです。ただ、それは本当にあらゆる状況に当てはまる一般的な方法なのでしょうか。

本稿では、AIの推奨の裏側にある文脈を掘り下げつつ、いまも役割別（技術役割別）ディレクトリ構成が有効である理由を探っていきたいと思います。さらに、プロジェクトの言語的特性に応じて、どのような場合にドメイン中心アーキテクチャが有利で、どのような場合に役割別構成が有利なのか、AI駆動開発により適した戦略を考えていきます。

注意：本稿の手順や指針に従っても、AIモデルの自律的な判断や推論の流れによっては AGENTS.md が参照されない場合があります。本稿の狙いは、望ましい結果に近づく確率を高めて手戻りを減らすことにあり、常に指針の遵守を保証するものではありません。

役割別（技術役割別）ディレクトリ構成（Layered / Role-First Packaging）

ここでいう「役割別（技術役割別）ディレクトリ構成」は、Service / UseCase / Repository / DTO / Enum のように技術的な役割（レイヤー）を先に切ってから、その配下にドメイン（または機能）を配置する考え方です。

※この記事では以降、長いので 「役割別構成」 と呼びます。

役割別構成は、役割ごとに先に分けて、各役割の下でドメインを分けていくやり方です

app/
 ├── controllers/
 │    ├── UserController.php
 │    └── ProductController.php
 ├── services/
 │    ├── UserService.php
 │    └── ProductService.php
 └── repositories/
      ├── UserRepository.php
      └── ProductRepository.php

ドメイン中心アーキテクチャ（Domain-Centric Packaging）

ドメイン中心アーキテクチャは、ドメインを先に分類する方式です。ドメインごとにフォルダを作り、その下に Service、UseCase、Repository、DTO、Enum を配置します。ドメイン別に先に分けて、各ドメインの下で役割を分けていくやり方です。

app/
 ├── users/
 │    ├── UserController.php
 │    ├── UserService.php
 │    └── UserRepository.php
 └── products/
      ├── ProductController.php
      ├── ProductService.php
      └── ProductRepository.php

AI時代のアーキテクチャ配置方式：バーティカルスライス

バーティカルスライスは、ドメイン中心構造を機能単位でもっと細かく分割した形です。ユーザー登録、ユーザー照会のように機能単位でフォルダを分け、その中に DTO、Service、Controller をまとめて入れる方式です。

特定の機能を修正するとき、その機能フォルダだけを見ても関連実装を比較的一つのまとまりとして把握できます。そのため、AIモデルの探索コストやミスを下げるうえで有利です。

このため、バイブコーディングや仕様駆動開発を行う際にAIへ相談すると、バーティカルスライスアーキテクチャを勧められることが多いです。

AGENTS.mdで共通規約と役割別の詳細ガイドを指定する

AGENTS.md は、AIコーディングエージェントに対して、プロジェクトの共通規約と作業原則を伝えるための基本的な指針ドキュメントです。リポジトリ全体に共通して適用する原則はルートの AGENTS.md に置き、特定のドメインや下位フォルダにだけ必要な詳細ルールは、より深い階層の AGENTS.md に分けて配置できます。²

こうした階層構造にしておくと、プロジェクト全体の共通ルールと、特定ドメイン／下位パッケージだけに適用したい細かなルールを同じ仕組みで書けます。そのため、フォルダ構造と連動させて指針を置くほど、AIにより具体的なガイドラインを渡しやすくなります。³

役割優先の構成では、Service／Repository のように「役割」ごとにルール・注意点・コーディングスタイルを切り分けやすいです。そのため、AIに実装を任せてみて期待した結果にならなかった場合でも、該当する役割のルールだけを追加・修正しながら継続的にチューニングしやすくなります。

全体共通の原則はリポジトリルートの AGENTS.md に置き、役割別の細かな規約は各役割ディレクトリ直下の AGENTS.md に分けて運用するとよいです。こうしておくと、変更はその役割の AGENTS.md に閉じるので、全体ルールを不用意に揺らさずに管理できます。

.
├── AGENTS.md                     # 全体共通（命名規則、設計方針、禁止事項など）
└── app/
    ├── controllers/
    │   ├── AGENTS.md             # Controller層のルール（薄く保つ、DTO変換の方針など）
    │   ├── UserController.php
    │   └── ProductController.php
    ├── services/
    │   ├── AGENTS.md             # Service層のルール（ユースケース単位、例外方針、Tx境界など）
    │   ├── UserService.php
    │   └── ProductService.php
    └── repositories/
        ├── AGENTS.md             # Repository層のルール（クエリ方針、N+1回避、返却型など）
        ├── UserRepository.php
        └── ProductRepository.php

このようにしておくと、AIが変更対象の近くで必要なルールを見つけやすくなり、探索の取りこぼしを防いで、より狙いどおりのコードを得られる可能性が高まります。

AGENTS.md の良い点は、特定のエディタに依存しない、リポジトリ単位の基本指針として使いやすいところです。チームメンバーがどのツールを使っていても同じ規約ドキュメントをリポジトリ内に置けますし、AIが参照すべき設計原則やコーディングスタイルもコードと一緒に管理しやすいです。そのため、リポジトリ全体の基本規約は AGENTS.md を中心に説明するのが自然です。

Cursor というエディタを使う場合は、.cursor/rules でパスごとの詳細ルールを追加して補完できます。ただし、これは Cursor という特定エディタでのみ使える手段です。基本は、エディタに関係なく指針を適用できるように共通規約は AGENTS.md に置き、Cursor のルールで適用する規則は Cursor を使うメンバーが出てきた段階で追加するのがよいです。.cursor/rules と AGENTS.md のガイドラインが重複する場合は、.cursor/rules 側から AGENTS.md を参照する形にしておくと、指針の読み落としを減らしやすくなります。もちろん、AGENTS.md のパスをリンクして読ませる形は、AIモデルが読まない可能性がわずかに残ります。ガイドラインを確実に読ませたい目的なら、.cursor/rules を使うほうが向いています。

AGENTS.md の代わりに STYLE_GUIDE.md のようなファイル名を使うこともできます。⁴ ただし、現在のAIコーディング生態系では AGENTS.md という名前が共通指針ドキュメントとして広く使われています。特別な理由がなければ、この慣例に従うほうが無難です。⁵

コーディングスタイルの多様性

言語ごとにコーディングスタイルのばらつきがあり、これはAI時代のフォルダ構造配置戦略に大きく影響を及ぼします。

自由度が比較的大きい言語と小さい言語があります。コーディングスタイルが似通っていて大きなばらつきが少ない言語がある一方で、非常に多様なコーディングスタイルを取り得る言語もあります。前者は Go や Spring フレームワークを使う Java、後者は JavaScript、TypeScript、Python、PHP、Ruby などです。

自由度が小さい言語（Java/Spring, Go など）

• 言語自体のスタイルが単純であるか、ライブラリやフレームワークによって構造が強く規定されます
• あえて AGENTS.md がなくても、比較的一貫した品質のコードが出やすいです
• 推奨：AIが関連ファイルを把握しやすいドメイン中心構造やバーティカルスライスアーキテクチャのほうが有利なことが多いです

自由度が大きい言語（JS, TS, Python, PHP など）

• 言語自体の自由度が高く、ライブラリをラップしたり継承したりするなど、設計の仕方が非常に多様です
• AIに各プロジェクトに合ったアーキテクチャやコーディングスタイルを AGENTS.md で注入しないと、望んだ形の成果物を得にくい可能性が高いです
• ジレンマ：ドメイン中心構造やバーティカルスライスの場合、上位の共通 AGENTS.md にすべてのルールを盛り込むか、機能別リンクを追加して、AIがドメインフォルダ配下のコードを探索するときにリンク先の機能別ガイドラインも一緒に参照してくれることに期待するしかありません。一方で役割別構成は、各役割フォルダ（Service、Repository など）にファイルを一つ置くだけで済むため、むしろAIが各役割ごとのスタイルを参照しやすく、一貫したコード品質を引き出すうえで有利になります

規約と自由度による違い

ここまでは便宜上、言語を基準に見てきましたが、実際により重要なのは、言語そのものよりも、採用しているライブラリ／フレームワークのエコシステムにおける規約や慣例がどれだけ構造を規定するかです。規約の強いスタックほど、バーティカルスライスの探索上の利点が大きく働き、自由度の高いスタックほど、役割ごとのルールを強く注入できる構造のほうが向いている場合があります。

TypeScript でも NestJS や Angular のようなケースは規約の強いスタックに当たり、Java でも Spring のようなフレームワークなしで開発するなら、自由度の高いスタックに当たります。

役割別（技術役割別）ディレクトリ構成の限界を克服するプロンプティング技法

役割別構成がAI駆動開発の時代にあまり勧められないと言われる理由は、AIエージェントのコンテキストウィンドウ（文脈サイズ）の制約と、ノイズの増加にあります。

AIは、把握しなければならないスコープが小さいほど、コアロジックに集中しやすく、ノイズになりやすいコードを避けやすいです。そのため良い成果物が出やすくなります。

一方で、自由度の高い言語やスタックでは役割・レイヤーごとの制約が重要です。AIの冗長なコーディングを防ぎ、人間にとって理解しやすいコードを維持するには、やむを得ず役割別構成を採用しなければならない場合があります。

このとき、AIの探索失敗をできるだけ減らすために、次の二つの方法を提案します。

• レイヤー参照関係の明示：役割別構成で探索の取りこぼしを減らすには、アーキテクチャレベルでレイヤーを明確に定め、参照順序を決めておく必要があります。プロジェクト上位の共通 AGENTS.md や別の設計文書に、レイヤー間の参照関係と順序パターンを明記しておくと、異なるフォルダに属する関連コード同士でもAIがたどりやすくなります

• 明示的な道しるべの提供（@see コメント）：基本的にファイル間の参照関係は import でAIに伝えられます。ただし、ファイルのネームスペースを直接参照できないケースもあります。その場合はコメントを道しるべとして使います。たとえば PHP の Blade ファイルのように、文字列パスでファイル位置を決めるケースがそうです。このときコメントに @see /path/to/file のようにパスを追加しておけば、AIエージェントがどのファイルを追加で探索すべきかを把握しやすくなります

参考：skills/*.md と AGENTS.md の運用ガイド

最近は、AGENTS.md とあわせて skills/*.md 形式のガイダンス文書を併用するケースも増えています。⁶

併用する場合は、どの指針をどこに置くかを先に決めておく必要があります。skills/*.md は作業内容や目的に応じて必要な指針を選択的に参照する性格が強い一方で、AGENTS.md はコードを生成・修正する位置（フォルダ）を基準に、近くの指針を適用しやすいです。

skills/*.md に内容が過度に集まると、ガイドラインのカテゴリ分けが明確でなくなったり、プロジェクト規模が大きくなって指針が増えたときに一部の指針を参照し漏らしたりする可能性があります。また、ルール同士の衝突によって意図と異なる結果につながることもあります。これに対して AGENTS.md は、レイヤー／役割フォルダ単位でルールを紐づけられるため、適用範囲が比較的明確で、他の領域へ影響する可能性も抑えやすいです。

そのため、共通規約はルート（またはルートに近い）AGENTS.md に置き、プロジェクト全体の戦略（プロジェクト構造、コーディング方針、レイヤー分離戦略）や反復手順（例：マイグレーション作成の原則）のように、フォルダ探索の前に先に決めておくべき内容は skills/*.md に分離して肥大化しないように運用するのがよいです。そして skills によってファイルが適切な場所に生成されたあと、その場所で適用すべきローカル制約は該当フォルダの AGENTS.md に置き、指針の適用先を分ける戦略が有効です。

規約の強さに応じたトレードオフの考慮

ドメイン中心構造やバーティカルスライス構造では、ドメイン／機能単位でフォルダが細かく分かれるため、役割別・レイヤー別に AGENTS.md を置こうとすると重複管理が増え、保守ポイントが多くなりがちです。その結果、全体規約を skills/*.md により強く依存することになり、文書が肥大化したり、指針の適用が曖昧になったりするリスクも出てきます。

一方、規約の強いエコシステムであれば、AI は基本構造やコーディングパターンを比較的安定して推論できます。この場合は、まずドメイン中心のパッケージングによって探索範囲を絞ることを優先し、追加のスタイル制約は補助的に扱うのがよいでしょう。ローカルの AGENTS.md には規則本文を重複して書くのではなく、共通の役割別ルールや skills/*.md への参照リンクだけを置く運用も取れます。リンク方式は状況によって一部の反映漏れのリスクが残りますが、探索コストの削減や変更範囲の縮小というメリットを最大化できるため、十分に許容できるトレードオフと言えます。

一方、自由度の高いエコシステムではスタイル制御が重要です。そのため、skills/*.md には探索前に必要な全体原則・手順のみを記載して軽く保ち、AGENTS.md にはローカル制約などを中心にスタイルを管理します。ドメイン関係を把握する過程で AI の探索コストが上昇する可能性はありますが、import や @see で参照経路を明示すれば関係を追跡しやすくなり、統制もしやすくなります。これはスタイル制約と探索コストの十分に許容できるトレードオフです。

最後に

コーディングエージェントが開発生産性を大きく押し上げている今、AIの生産性を最大限活用するために、さまざまな検討が進められていると思います。

AIが読むべき文脈の範囲をどれだけ狭められるか、そしてコードベースの規約をどれだけ一貫して制約できるかで、人間の介入の度合いは変わってきます。人間の介入が減るほどボトルネックも減り、生産性は向上します。

AI時代のフォルダ構造は、もはや良いアーキテクチャに従うだけの話でもなく、チームメンバー間のタスク分担だけを考えればよい問題でもありません。
ドメイン間の分離でコードとプロダクトのずれを減らすことを超えて、AIエージェントの探索コスト、変更成功率、そして人間の介入量の減少を左右し、生産性を決める問題になりました。

トレンドの変化が速いAI時代では、設計構造がAIにどれほど影響するかについて、定量実験で十分に証明された研究はまだ多くありません。そのため、実務者の経験や判断、そしてSNSやコミュニティで共有されるノウハウが大きな比重を占めているのが状況です。

この記事は、個人的に経験し考えてきたノウハウを書き起こしたものです。AIモデルやツールが発展すれば、この感覚や判断も変わっていく可能性があります。したがって、プロジェクト構造を設計するときに何を優先順位として置くべきかを見直すための参考資料程度に読んでいただければと思います。

_{※本記事は、ChatGPTを活用して文章表現の見直し（推敲）と構成の整理を行いました。}

1. Geminiで要約しました。 ↩

2. 特にAIモデルの中でも Codex は AGENTS.md の活用に積極的です。https://developers.openai.com/codex/guides/agents-md#how-codex-discovers-guidance ↩

3. Codex applies guidance from the closest AGENTS.md to each changed file. You can place more specific instructions deeper in the tree when particular packages need extra scrutiny. https://developers.openai.com/codex/integrations/github/#enable-automatic-reviews ↩

4. Codex を使う場合は、AIモデル向けの指示事項を AGENTS.md 以外の別名ファイルで追加できる設定も提供されています。 https://developers.openai.com/codex/guides/agents-md/#customize-fallback-filenames ↩

5. https://agents.md/ ↩

6. Codexの場合プロジェクトルートから.agents/skills/*.mdで適用できます。https://developers.openai.com/codex/skills#where-to-save-skills ↩