はじめに
「前のプロジェクトでうまくいったアーキテクチャを使ったのに、今回は失敗した」
こんな経験、ありませんか？
私は2つのプロジェクト（KakeiBonとPromps）を通じて、プロジェクトの規模によって適切なアーキテクチャが変わることを痛感しました。この記事では、その気づきと判断基準を共有します。
よくある失敗パターン
パターン1: 成功体験の盲目的適用
プロジェクトA: レイヤードアーキテクチャで大成功！
↓
プロジェクトB: 同じアーキテクチャを適用
↓
結果: マージコンフリクト頻発、開発速度低下...
パターン2: 「ベストプラクティス」の誤解
書籍: 「レイヤードアーキテクチャが最適」
↓
すべてのプロジェクトに適用
↓
結果: 小規模では過剰、大規模では不足
何が問題だったのか
答えはシンプルでした。
規模が違うのに、同じアーキテクチャを使っていた
これは、軽トラックで高速道路を走ろうとしたり、大型トラックで路地裏を走ろうとするようなものです。
発見: 規模がすべてを決める
2つのプロジェクトを比較して気づいたこと：
Promps（小規模）
目的: 1つ（DSL → 自然言語変換）
機能: 5-10個
レイヤー数: 5-10層
開発者: 1-3人
採用: レイヤードアーキテクチャ ✅
結果: うまくいった
KakeiBon（大規模）
目的: 複数（ユーザー管理、取引記録、暗号化、レポート...）
機能: 20+個
想定レイヤー数: 15-20層
開発者: 1人（将来的に拡大予定）
採用: モジュラーアーキテクチャ ✅
もしレイヤードだったら: 管理不可能 ❌
規模とアーキテクチャの対応表
| 規模 | レイヤー数 | 最適なアーキテクチャ | 例 |
|---|---|---|---|
| 小 | 5-10 | レイヤード | Promps |
| 中 | 10-20 | ハイブリッド | - |
| 大 | 20+ | モジュラー/マイクロサービス | KakeiBon |
レイヤードアーキテクチャが機能する条件
実は、レイヤードアーキテクチャには適用条件があります。
✅ 機能する条件
- 目的が単一
- レイヤー数が10未満
- 依存関係が一方向
- コアレイヤーが安定
❌ 機能しない条件
- 目的が複数
- レイヤー数が15以上
- 循環依存がある
- コアが頻繁に変わる
実例: Prompsでの成功
Prompsは意図的にミニマルな設計にしました。
レイヤー構造
Phase N+1: File I/O（ファイル保存・読み込み）
↓
Phase N: Logic Check（構文検証）
↓
Phase 2: Particle Blocks（助詞ブロック）
↓
Phase 1: GUI（Blockly.js）
↓
Phase 0: Core Parsing（DSL → NL変換）
なぜうまくいったか
- レイヤー数が有限（5-10個）
- 各レイヤーの責務が明確
- 下位レイヤーが上位レイヤーに依存しない
結果、以下が自動的に得られました：
- ✅ 疎結合（モジュール分離が簡単）
- ✅ テストの独立性
- ✅ マージコンフリクトが稀
判断基準: 5つの質問
新しいプロジェクトを始める前に、この5つの質問に答えてみてください。
Q1: 目的はいくつありますか？
- 1つ → レイヤードアーキテクチャを検討
- 複数 → モジュラーアーキテクチャを検討
Q2: レイヤー数を列挙できますか？
- はい、10個未満 → レイヤードが機能するかも
- いいえ、または10個以上 → モジュラーが安全
Q3: 依存関係は一方向ですか？
- ほぼ一方向 → レイヤードが機能するかも
- 循環依存がある → モジュラーが安全
Q4: コアは安定していますか？
- はい → API安定性ポリシーが機能
- いいえ → バージョニングが必要
Q5: 開発者は何人ですか？
- 1-3人 → レイヤードでも管理可能
- 10人以上 → 慎重に検討
Unix哲学との一致
実は、この考え方はUnix哲学と一致しています。
"Do one thing and do it well"
（1つのことをうまくやる）
PrompsはDSL変換という1つのことに集中したから、純粋なレイヤードアーキテクチャが可能になりました。
逆に、KakeiBonは多くのことをする必要があるので、別のアプローチが適切でした。
アーキテクチャは道具であり、絶対法則ではない
最も重要な教訓：
✅ 正しい: 規模に応じてアーキテクチャを選ぶ
❌ 間違い: 1つのアーキテクチャをすべてに適用
レイヤードアーキテクチャは素晴らしいパターンですが、万能ではありません。
プロジェクトの規模、目的、チーム構成に応じて、適切なアーキテクチャを選択することが重要です。
このシリーズで伝えたいこと
この記事では全体像を説明しました。続く記事で、より詳しく掘り下げます：
📝 次回以降の記事（予定）
-
「レイヤードアーキテクチャで疎結合が勝手に生まれた話」
- なぜレイヤードアーキテクチャで疎結合が自動的に得られるのか
- Prompsでの実例
-
「プロジェクト規模でアーキテクチャを変える判断基準」
- 詳細な意思決定フレームワーク
- よくある設計ミスとその対策
-
「ブランチを削除しない Git 戦略を試してみた」
- Persistent Feature Branch戦略
- レイヤーとブランチの完璧な一致
参考資料
この記事の内容は、OSSプロジェクト「Promps」の開発ドキュメントから抽出しています。
- GitHub: https://github.com/BonoJovi/Promps
- 詳細ドキュメント: .ai-context/core/SCALE_AND_ARCHITECTURE.md
- ライセンス: MIT License (2025 Yoshihiro NAKAHARA)
完全なドキュメントには、AI向けとコントリビューター向けの両方の視点から、より詳しい解説が含まれています。
まとめ
- ✅ プロジェクトの規模がアーキテクチャを決定する
- ✅ レイヤードアーキテクチャは小規模（5-10レイヤー）に最適
- ✅ 大規模（15-20+レイヤー）ではモジュラーアーキテクチャが適切
- ✅ 成功パターンを盲目的に適用しない
- ✅ プロジェクト開始前に5つの質問で判断する
次回の記事では、レイヤードアーキテクチャでなぜ疎結合が自動的に生まれるのか、その仕組みを詳しく解説します。
お楽しみに！
執筆について
この記事は、著者（Yoshihiro NAKAHARA）の設計思想と実践経験をAI（Claude）とのセッションを通じて言語化し、原稿に書き起こしたものです。
- 思考の整理: 複数プロジェクト（KakeiBon、Promps）での実践を通じて得た暗黙知を、対話を通じて明文化
- 原稿執筆: Claudeが構成・執筆を担当
- 内容検証: 著者が技術的正確性とニュアンスを確認
- 文責: Yoshihiro NAKAHARA
すべての設計判断と技術的洞察は著者の実務経験に基づいています。