学生のチーム開発におけるフォルダ構成

---
title: フォルダ構成は “初動” が命 ー 小規模チームこそディレクトリ設計を固めよう
---

> **ディレクトリを先に決めろ。さもなくば未来のチームが泣く。**  
> 最近、学生同士でチーム開発をして痛感した教訓です。

意外なことに *フォルダ構成* だけを扱った記事は多くありません。  
企業は独自ルールを社内ドキュメントで完結させるし、個人開発では「とりあえず動く」構成で済ませがち。  （個人的な憶測…）
でも、メンバーが 3 人を超えた瞬間から **“依存ファイル”** が増殖しはじめ、マージで地獄を見ます。

本稿では **小規模〜学生チームでも導入しやすい** ディレクトリ設計の考え方と、フロント／バックエンドのひな形をまとめました。  
「正解は環境次第」と割り切りつつ、“最低限これだけ守ると崩れない” と思うことを紹介します。  

---

## なぜフォルダ構成が重要なのか

*コード位置* が決まっていないと、ファイルを探す時間・コンフリクトの解決時間・バグ調査コストがめちゃくちゃ大変になり最後は全て消すみたいなことが起きます。
特に **Pull Request が走るたびに同じファイルが競合する** 状況は、ディレクトリの線引きが曖昧な典型例です。

---

## ディレクトリ設計の指針として

| # | 指針 | 一言メモ |
|---|------|-----------|
| 1 | **すぐにわかる** | `tree`コマンドを見ただけでわかるように |
| 2 | **責任を分離** | 他機能フォルダからの参照を避ける |
| 3 | **簡単に新機能** | 機能、ページの追加はフォルダを増やすのみ |
| 4 | **汎用機能を** | 全体で使用する機能はsrc直下に |
| 5 | **影響を局所に** | 変更をしても影響を最小に |
| 6 | **自然と身につく** | 役割分離からオブジェクト指向を |

要は **「誰が見ても迷わない」×「あとで増やせる」** 仕組みを用意しておくこと。  
この 6 つを意識しておくだけで、後からの修正回数が減ります。さらに、オブジェクト指向が身につくかも。



### フロント（React）例 

```text
project-root/
├── public/                  # 静的アセット
├── src/
│  ├── index.tsx             # エントリーポイント
│  ├── App.tsx               # ルートコンポーネント
│  │
│  ├── components/           # 再利用 UI
│  ├── services/             # API ラッパー
│  ├── hooks/                # 共通カスタムフック
│  ├── utils/                # 汎用関数
│  │
│  └── pages/                # ★機能／画面単位で完全分離
│     ├── Home/
│     │   ├── HomePage.tsx
│     │   ├── hooks/useHomeData.ts
│     │   └── components/HomeBanner.tsx
│     ├── Login/
│     └── Dashboard/
│
└── README.md

```
ポイントは「ページ直下に、その機能にだけ関係するファイルをまとめる」こと。
これで 担当者は自分のフォルダだけ見れば完結 し、他人の作業をほぼ汚染しません。
共通 UI は src/components/ へ、横断的な処理は src/services/・src/hooks/ へ逃がすのがバランス良し。

### バックエンドに関して
バックエンドに関してチームで開発したことないですが、最初の5原則に習いがら開発することでスムーズに開発が可能になると思います。
簡単にバックエンドのフォルダ構成を紹介すると
```text
src/
├── controllers/    # API ハンドラ
├── services/       # ビジネスロジック
├── models/         # DB スキーマ / ORM
├── routes/         # URL ⇔ controller
├── middlewares/    # 認証 / エラー処理
└── utils/          # 共通関数
```

## チーム開発で効き目を実感する瞬間
* オンボーディングが秒速
README にツリー図を 1 枚貼るだけで、新メンバーが全体像を掴める。
**ChatGPTやCloudに質問する時もすぐ理解してくれる。**
* コンフリクトが激減
フォルダ単位で責任範囲が閉じているので、同時並行開発も怖くない。
* コードレビューの質が上がる
変更が局所的 → メンバーがロジック理解に集中できる。
* いつの間にかいろんな言語を習得
オブジェクト指向が見につことでPythonやC++、Javaなどが理解しやすくなる。

## まとめ
フォルダ構成は“とりあえず”で決めない。
ベストプラクティスはプロジェクトごとに変わるけれど、
6個の指針を押さえた設計 を最初に敷いておくと、
あとで技術が変わっても慌てずに済むと思います。

小さなチーム開発でも、この型を敷くだけで未来の自分とメンバーを救えます 🎉


## 📚 参考文献・関連ドキュメント
- [Flask Templates — Python Beginners documentation](https://python-adv-web-apps.readthedocs.io/en/latest/flask3.html)  
- [Project Layout — Flask Documentation (3.1.x)](https://flask.palletsprojects.com/en/stable/tutorial/layout/)  
- [Getting Started: Project Structure | Next.js](https://nextjs.org/docs/app/getting-started/project-structure)  
- [Next.js directory organization best practices | Sentry](https://sentry.io/answers/next-js-directory-organisation-best-practices/)  
- [Popular React Folder Structures and Screaming Architecture](https://blog.webdevsimplified.com/2022-07/react-folder-structure/)  
- [Screaming Architecture - Reactのディレクトリ構成を進化させる(和訳) #JavaScript - Qiita](https://qiita.com/mwkiyo/items/9549207680e71833a654)  
- [Vue.js ディレクトリ構成 色々試してみた #Vuex - Qiita](https://qiita.com/tockn/items/2ce68b99e0839df52200)  
- [How to Structure a Large Scale Vue.js Application – Vue School Articles](https://vueschool.io/articles/vuejs-tutorials/how-to-structure-a-large-scale-vue-js-application/)  
- [【初心者向け】バックエンドのフォルダー構成をわかりやすく解説！ - nocoderi](https://qiita.com/kaisei_siratama/items/aeadf2e98cee7a43beb0)  
- [もう迷わない！ドメイン駆動開発をベースにクリーンアーキテクチャを取り入れたPython最強フォルダ構成ガイド - Qiita](https://qiita.com/fmkt/items/d7185720855c592195e4)  
- [エンジニアが開発しやすい環境作りをする – Sreake](https://sreake.com/blog/directory-structure-good-practice/) 
- [知っておきたいフォルダ管理術~フォルダ構成のポイント~ - Qiita](https://qiita.com/hukusuke1007/items/3105dbf7b99574cbc9e1)  

---