新しいプロジェクトを始める前の机で、ノートPCに出てきた階層の案と手元の紙のメモを見比べながら、この切り方で半年後も迷わないかと考えている開発者
設計・レビューでのAI活用約14分

AIにフォルダ・パッケージ構成を相談する｜後で崩れない切り方

新しいプロジェクトの初日。AIに「この構成でフォルダを切って」と頼むと、controllers/、services/、models/、utils/ がきれいに並んだ案が数秒で出てきます。見た目は整っているし、どこかで見たことのある形なので、そのまま採用した——。 半年後、services/ には40ファイル以上が積み上がり、utils/ は「置き場所に迷ったものの最終処分場」に。機能をひとつ直すたびに、4つのフォルダを行ったり来たりしている。そんな経験、ありませんか。

あなたの判断が甘かったわけではありません。AIの案は一般的なテンプレートとしては正しいことが多いんです。ただ、AIはこのチームで「どんな変更が、どれくらいの頻度で来るか」を知らないまま切っています。そこを人が少し渡すだけで、構成の相談はぐっと実りあるものになります。

結論：AIにフォルダ・パッケージ構成を相談するときは、①「よく来る変更」と「依存させたくない方向」を先に渡す、②「層で切る」「機能で切る」など2〜3案を出させ、変更シナリオを当てて「何フォルダ触るか」で比べる、③決めた構成は「依存の向き」と「迷ったときの置き場」を1枚のルールに残す、の3手順で進めます。AIに構成を決めさせるのではなく、判断材料を並べさせる。決めるのは、変更の起き方を知っている人です。

フォルダ構成は、最初に一度決めたら終わりの仕事ではありません。 でも、最初に「何を基準に切ったか」を言葉にしておくだけで、半年後の崩れ方はかなり変わります。

なぜAIの構成案は「後で崩れる」になりやすいのか

AIの案が崩れやすいのは、案そのものが悪いからというより、切り方を決める材料が足りないからです。よく見かけるのは次の4つです。

どれも、AIにこのプロジェクトならではの事情が渡っていないことから起きています。

「層で切る」と「機能で切る」を、変更シナリオで比べる

左右2つの棚を並べた図。左の棚は同じ形の箱が種類ごとに横一列ずつ並んだ棚で「層で切る」、右の棚は色違いの箱が1段ごとにひとまとまりで並んだ棚で「機能で切る」
層で切ると「同じ種類のもの」が集まり、機能で切ると「一緒に変わるもの」が集まります。どちらが正しいかではなく、よく来る変更でどちらが触る場所を少なくできるかで比べます

構成の切り方は、大きく分けると2つの考え方があります。

層で切る機能で切る
集まるもの同じ種類のもの（画面・処理・データアクセス）一緒に変わるもの（請求・会員・予約）
例controllers/ services/ repositories/billing/ members/ reservations/
向いている場面小さめのアプリ、機能の境目がまだ見えないとき機能が増えていく、チームで分担するとき
崩れやすい所1つのフォルダが肥大化する。1機能の修正で多くのフォルダを触る機能をまたぐ共通処理の置き場に迷う

実務では、機能で大きく分けて、その中を層で分ける混合型もよく使われます。どれが正解というより、よく来る変更で、触る場所を少なくできるのはどれかで比べるのが、いちばん地に足のついた選び方です。

そこで役に立つのが「変更シナリオ」です。たとえば次のような、実際に来そうな変更を3つ書き出します。

  1. 請求書に「支払期限」の項目を追加する
  2. 会員の退会処理に、データ削除の予約を加える
  3. 管理画面だけに、検索の絞り込み条件を1つ足す

そして各案について、「この変更で、いくつのフォルダを触るか」を数えます。層で切った案では1の変更が controllers/・services/・repositories/・views/ の4か所に散らばる一方、機能で切った案なら billing/ の中だけで済む——といった違いが、具体的に見えてきます。

数が少ない案が常に勝ちではありませんが、「よく来る変更ほど、1か所で済む」構成は、半年後も崩れにくくなります。

AIへの相談の仕方（コピーして使えます）

最初に渡したいのは、コードよりも事情です。次の型で頼んでみてください。

新しく作る（または整理し直す）アプリのフォルダ・パッケージ構成を相談したいです。
まだ1つに決めず、判断材料を並べてください。

## 前提（分かる範囲で）
- 言語・フレームワーク：（例：TypeScript / Next.js、Python / Django など）
- 主な機能：（例：会員、予約、請求、管理画面）
- よく来る変更：（例：請求まわりは月1回ほど仕様変更がある）
- 触る人：（例：管理画面は別チームが担当）
- 依存させたくない方向：（例：業務ルールのコードは、DBや外部APIの都合を知らないでいてほしい）

## お願いしたいこと
1. 構成案を2〜3つ（例：層で切る／機能で切る／機能の中を層で切る）、それぞれフォルダの木構造で
2. 各案の「向いている点」「崩れやすい点」
3. 下の変更シナリオそれぞれで、各案だと「触るフォルダ」がどこになるか（表で）
4. フレームワークの規約上、動かせない（動かさない方がいい）フォルダがあれば、その理由
5. `utils` や `common` のような共通フォルダを作るなら、何を入れて何を入れないかの線引き

## 変更シナリオ
- （実際に来そうな変更を3つ）

ルール：
- このプロジェクトの事情が分からず判断できない点は、推測で決めずに「要確認」として、何を確かめれば決められるかを書く
- どれか1案を推す場合は、上の前提のどれを根拠にしたかを明記する

答えが出てきたら、人が見るのは3か所です。

  1. 変更シナリオの表：AIが「触るフォルダ」を正しく数えているか。ここが外れていると比較が全部ずれます。自分の頭でも一度たどってみます。
  2. 「要確認」の項目：ここが一番価値のある出力です。チームで決めていなかったこと（たとえば「認証は機能なのか共通なのか」）が浮かび上がります。
  3. 推している根拠：AIが前提のどれを根拠にしたか。根拠が一般論だけなら、その推しは割り引いて受け取ります。

大きな方針（モノリスのまま分けるのか、サービスごとに分けるのか等）で迷っている段階なら、先にAIのアーキテクチャ案を鵜呑みにしない｜比較の型で全体の比べ方を整理しておくと、フォルダの話がぶれにくくなります。

決めたら、「依存の向き」と「迷ったときの置き場」を1枚に残す

構成が崩れるのは、多くの場合、決めた後です。新しいファイルを作るたびに「これ、どこに置く？」が起き、そのたびに少しずつずれていきます。そこで、決めた構成と一緒に、短いルールを1枚残しておきます。AIにこう頼むと下書きが作れます。

決めた構成は下のとおりです。この構成を守るための短いルールを、
READMEに貼れる形で書いてください（全体で20行程度まで）。

- 各フォルダに「置くもの／置かないもの」を1行ずつ
- フォルダ間の依存の向き（どこからどこを参照してよいか、してはいけないか）
- 置き場に迷ったときの決め方（例：「1つの機能でしか使わないなら、その機能のフォルダに置く」）
- 共通フォルダに入れてよい条件

--- 決めた構成 ---
（木構造を貼る）

依存の向きは、文章で決めるだけだと少しずつ破られていきます。余力があれば、ツールで機械的に確かめるのも一つの手です。

どれも最初から全部のルールを入れなくて大丈夫です。「業務ルールのフォルダから、DBアクセスのフォルダを直接参照しない」のような、一番守りたい1本から始めれば十分です。なぜこの構成にしたかは、AIにADRのドラフトを書かせる｜設計判断の「なぜ」を残す型の型で残しておくと、後から来た人が迷いません。

すでにあるプロジェクトを整理し直すときは

既存のプロジェクトで構成を変えたくなったら、一気に移さないことが大切です。

AIに移動の手順を作らせる場合は、「1回の変更で動かすのは1機能分まで」「移動と修正はコミットを分ける」と範囲を区切って頼みます。複数ファイルにまたがる変更の追い方は、AIに複数ファイルの変更を任せる｜差分を見失わない追い方で詳しく整理しています。

構成を相談しておくと、何が変わるか

ありがちな落とし穴と、その回避

明日からやること（小さく始める3つ）

  1. 最近の変更を3つ思い出して、それぞれ「何フォルダ触ったか」を数えてみる：触る場所が多かった変更が、今の構成の弱いところです。
  2. その3つを変更シナリオにして、上の相談の型でAIに2〜3案を出してもらう：まだ何も動かさず、表と「要確認」だけ眺めます。
  3. 今の構成のまま、「迷ったときの置き場」のルールを3行だけ書く：構成を変えなくても、これだけで崩れ方がゆるやかになります。

コピーして使う「フォルダ・パッケージ構成 相談チェックリスト」

# フォルダ・パッケージ構成 相談チェックリスト

## 1. AIに渡す前に
- [ ] 言語・フレームワークと、その規約で決まっている置き場所を書いた
- [ ] 主な機能と、よく来る変更（頻度つき）を書いた
- [ ] 誰がどこを触るか（チームの分担）を書いた
- [ ] 依存させたくない方向を1つ以上書いた
- [ ] 実際に来そうな変更シナリオを3つ用意した

## 2. 案を比べるとき
- [ ] 案を2〜3つ出させ、1案に決め打ちさせなかった
- [ ] 変更シナリオごとに「触るフォルダ」を表で比べた
- [ ] 表の数え方が合っているか、自分でもたどって確かめた
- [ ] 「要確認」の項目を、チームで決めるべきこととして拾った
- [ ] AIが推す案の根拠が、一般論ではなく前提に基づいているか見た

## 3. 決めたあと
- [ ] 各フォルダの「置くもの／置かないもの」を1行ずつ残した
- [ ] 依存の向きを書き、守りたい1本はツールで確かめられるようにした
- [ ] 迷ったときの置き場の決め方と、共通フォルダに入れる条件を決めた
- [ ] なぜこの構成にしたかを、ADRなどに残した

## 4. 既存プロジェクトを整理し直すとき
- [ ] 一度に動かすのは1機能分までにした
- [ ] 移動だけのコミットと、修正のコミットを分けた
- [ ] 移動の前後で、ビルドとテストが通ることを確かめた

最後に

フォルダ構成に、どのプロジェクトにも通用する正解はありません。 だからこそ、「よく来る変更が1か所で済むか」という自分たちの物差しで選んだ構成は、半年後に迷ったときの道しるべになります。「どこに置くか」を言葉にしておくことは、未来のチームの迷う時間を、静かに減らす仕事です。

明るいオフィスで、すっきり整理された階層の図が映る画面を見ながら、同僚と並んでほっとした表情で話している開発者

一度に全部整えなくて大丈夫です。今日は、最近の変更を3つ思い出して「何フォルダ触ったか」を数えるところから。変更の起き方を知っているのはあなたで、案を並べるのはAI。その分担で、構成は少しずつ「迷わない」ものになっていきます。

よければ、こちらも

関連用語