はじめに
こんにちは！👋 2025年新卒で、もうすぐ2年目の先輩になるエンジニアのパクパクです 🔥
みなさん、「クリーンアーキテクチャ（Clean Architecture）」という言葉を聞いたことはありますか？
OJTの最後にメール開発チームに配属されて、私もこのアーキテクチャにこれから触れていくことになりました。
この記事では、クリーンアーキテクチャを初めて触った新人エンジニアの視点で、概念を理解しつつ、実際のディレクトリにどう落とし込むかを順番に整理してみます。
1. 全部一つのディレクトリにまとめちゃダメですか？
クリーンアーキテクチャがなぜ必要なのか、おもちゃ作りにたとえて見てみます。
🔨 Before：ひとり工房
皆さんが「ひとりでおもちゃを作る工房」を運営していると想像してください。設計図を描いて、部品を作って、組み立てて、梱包して… 全部ひとりでやります。
最初はそれでも回ります。でも注文が増えると、だんだん問題が出てきます。
問題1：1か所直すと全部が揺らぐ
問題2：部品だけを単体で検査できない
問題3：材料の仕入れ先を変えにくい
コードにすると、だいたいこんな感じです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
def make_and_ship_toy(): # DBから部品データを取得 db = mysql.connect(host="localhost", user="root") parts = db.query("SELECT * FROM toy_parts") # 組み立て指示書を作成.. instructions = create_instructions(parts) # 倉庫に保存.... s3 = boto3.client("s3") s3.upload(instructions, "instructions.pdf") # 通知を送信...... smtp = smtplib.SMTP("example.com") smtp.send(notification) |
たとえば mysql.connect を PostgreSQL に変えたら？
db.query の戻り値 parts の型が変わり、本来 DB と無関係なはずの create_instructions(parts) まで修正が必要になります。
🏭 After：役割が分かれたおもちゃ工場
次は工場にアップグレードして、役割ごとにチームを分けてみましょう！
| 工場のチーム | 役割 |
|---|---|
| 設計チーム | 「車輪は4つ、色は赤」みたいなコアのルールを決める |
| 製造チーム | 設計チームのルールに沿って、作る手順を指揮する |
| 材料調達チーム | 外部の業者から部品を仕入れる |
| 注文受付窓口 | お客さまの注文を受けて、製造チームへ渡す |
こうやって分けると、さっきの3つの問題がきれいに解決します！
✅ 車輪の形を変えても → 設計チームだけ直せばいい
✅ 車輪だけ単体検査できる → 設計ルールを独立してテストできる
✅ 木材業者を変えても → 材料調達チームだけ直せばいい（設計はそのまま）
これをプロジェクトのフォルダ構成に当てはめると、こうなります。
| 工場のチーム | 業務のフォルダ | 役割 |
|---|---|---|
| 設計チーム | entities | ビジネスルール |
| 製造チーム | usecases | 処理の流れを指揮する |
| 材料調達チーム | gateways | DB、S3、メールなど外部接続 |
| 注文受付窓口 | apis、batches | ユーザー操作や実行要求の受付 |
2. おもちゃ工場で見るクリーンアーキテクチャ
上のアーキテクチャを基にして、おもちゃ工場についての内容で画像を生成してみました。
いちばん内側：きらきらコア（Entities）
工場の核となる設計ルールです。
「車輪は4つで、色は赤」みたいに、誰が作ってもどこで作っても 絶対に変わらないルールです。
コードでは entities フォルダがこの役割を担当します。
2つ目の円：おもちゃをつくる手順（Use Cases）
工場の作業手順書です。
「1. 車輪を付ける → 2. 色を塗る → 3. 梱包する」みたいに、具体的な手順の流れを決めます。
コードでは usecases フォルダがこの役割です。
「部品を集めて → 組み立てて → 出荷する」みたいに、処理の流れを指揮します。
3つ目の円：つなぐための道具（Interface Adapters）
工場の接続アダプタです。大きく2種類あります。
どちらも「内側の世界」と「外側の世界」をつなぐ役割です。
- 入口（注文受付窓口）：ユーザーの要求を受けて工場の中へ渡す →
apis、batches - 出口（材料調達ポータル）：外から材料を持ってきて工場へ渡す →
gateways
いちばん外側：外の世界の便利なもの（Frameworks & Drivers）
自分たちで作ったものではなく、持ってきて使う便利な道具です。
- FastAPI（Webフレームワーク）
- SQLAlchemy（DB ORM）
依存は内側に向けてだけ！
クリーンアーキテクチャでいちばん大事なルールは、これひとつです。
内側の円は、外側の円の存在を絶対に知らないこと！
おもちゃ工場で言うと：
- 材料調達チーム（外側）が設計ルール（内側）を参照する → OK！
- 設計ルール（内側）が「A社の木材で作れ」と特定の業者（外側）を指名する → NO！
設計チームは「木材が必要」とだけ書いて、どの業者から持ってくるかは気にしません。
こうしておくと、業者をAからBに変えても、設計を変えずに済むからです！
コードでも同じです。
entities（内側）はgateways（外側）を import しないusecases（内側）は「どんな倉庫に保存して」のような具体的な保存方法は知りません。ただ「倉庫に保存して」と依頼するだけです。
3. プロジェクトのフォルダ = 工場の区画図
では実際に、プロジェクトの app/ フォルダを見てみましょう。
ここで紹介するフォルダ名（entities、usecases など）はあくまで一例です。プロジェクトやチームによって命名は異なります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
app/ │ ├── entities/ 🟡 コアのルール │ ├── toy_car.py ← おもちゃの車のルール │ ├── toy_robot.py ← おもちゃのロボットのルール │ └── ... │ ├── usecases/ 🟠 処理の流れ │ ├── gift_sets/ │ │ └── pack.py ← ギフトセットを梱包する流れ │ ├── toy_cars/ │ │ └── assemble.py ← おもちゃの車を組み立てる流れ │ └── orders/ │ └── cancel.py ← 注文キャンセルの流れ │ ├── apis/ 🟢 注文受付窓口 │ └── v1/ │ ├── toy_cars.py ← おもちゃの車の注文 │ └── orders.py ← 注文管理 ├── batches/ 🟢 指示書 │ └── pack_gift_set.py ← CLIコマンド │ ├── gateways/ 🟢 外部接続 │ ├── parts_db/ ← 部品データベース担当 │ ├── warehouse/ ← 倉庫（ファイル保存）担当 │ ├── delivery/ ← 配送（通知送信）担当 │ └── supplier/ ← 仕入れ先API担当 │ └── main.py |
ポイント
1. gateways/ の下にサブフォルダがたくさんある！
gateways は接続先が複数あるので、接続先ごとにサブフォルダを切っています。
|
1 2 3 4 5 |
gateways/ ├── parts_db/ ← 部品データベースから取得・保存 ├── warehouse/ ← 倉庫へアップロード・ダウンロード ├── delivery/ ← 配送（通知送信） └── supplier/ ← 仕入れ先API呼び出し |
2. usecases/ の中も、業務ごとにフォルダがある！
手順書（Use Case）も種類ごとに分かれます。「ギフトセット梱包用」「おもちゃの車組み立て用」「注文キャンセル用」みたいな感じです。
動作の流れ
おもちゃ工場には pack-gift-set という指示書があります。ギフトセットを組み立てて出荷する機能です。
実行すると、だいたいこんな順番で動きます。
|
1 2 3 4 5 6 7 8 |
[注文受付] [制作指示] 🟢 batches/ → 🟠 usecases/ CLIコマンド実行 処理の流れを指揮 ┌───────────────┴───────────────┐ [部品調達] [完成品出荷] 🟢 gateways/ 🟢 gateways/ DB参照・部品確認 配送通知・倉庫保存 |
- 担当者がCLIでコマンドを実行 →
batches/が注文を受付 usecases/の手順書が「部品確認 → 組み立て → 出荷」の流れを指揮gateways/が実際にDBから部品を確認して、ギフトセットを組み立て、配送通知を送ります
おわりに
今回はクリーンアーキテクチャを おもちゃ工場 にたとえて整理してみました。みなさん、イメージできましたか？
私は難しい概念に出会うたびに、こうやって身近なものに置き換えて勉強しています。「これが工場だったら？」「これがレストランだったら？」みたいに考えると、急に難しかったものが少しずつ馴染んでくる気がするんです。
実はソフトウェアアーキテクチャには、クリーンアーキテクチャ以外にもいろいろあります。
- レイヤードアーキテクチャ（Layered Architecture）：層を上から下に積み重ねる構造
- ヘキサゴナルアーキテクチャ（Hexagonal Architecture）：ポートとアダプタで外部をつなぐ構造
- オニオンアーキテクチャ（Onion Architecture）：クリーンアーキテクチャに近い玉ねぎ構造
この記事でクリーンアーキテクチャに一度触れておくと、別のアーキテクチャに出会っても「これも役割分担の方法のひとつなんだな」と、少し自信が持てると思います。
読んでいただき、ありがとうございました 🌻
参考資料
