scope-appropriate-architecture

スコープに適したアーキテクチャ

すべてのアーキテクチャ上の判断を、プロジェクトの実際のニーズに合わせて適切な規模にします。すべてのプロジェクトにヘキサゴナルアーキテクチャ、CQRS、マイクロサービスが必要なわけではありません。

基本原則： まずプロジェクトのティアを判定し、その後のすべてのパターン選択を、そのティアの複雑さの上限内に制限します。

---

6 つのプロジェクトティア

ティア	LOC 比率	アーキテクチャ	DB	認証	テスト
1. 面接課題／持ち帰り課題	1.0-1.3x	フラットなファイル構成、レイヤーなし	SQLite / JSON	なし、または基本的なもの	要点を絞った 8-15 件
2. ハッカソン／プロトタイプ	0.8-1.0x	可能であれば単一ファイル	SQLite / インメモリ	なし	なし
3. スタートアップ／MVP	1.0-1.5x	MVC モノリス	マネージド Postgres	Clerk/Supabase Auth	正常系 + 重要なケース
4. 成長段階	1.5-2.0x	モジュラーモノリス	Postgres + Redis	認証サービス	単体 + 統合
5. エンタープライズ	2.0-3.0x	ヘキサゴナル／DDD	Postgres + キュー	OAuth2/SAML	完全なピラミッド
6. オープンソース	1.2-1.8x	最小限の API サーフェス	設定可能	任意	公開 API を網羅

LOC 比率 = 総行数 / コアビジネスロジックの行数。比率が高いほど、ビジネス価値に対するインフラコードの割合が高くなります。

---

自動判定シグナル

シグナル	ティアの目安
README に「take-home」、「assignment」、「interview」が含まれる	ティア 1
制限時間が記載されている（例：「4 hours」、「weekend」）	ティア 1-2
ファイル数が 10 未満で、CI も Docker もない	ティア 1-2
.github/workflows/ が存在する	ティア 3 以上
package.json に依存関係が 20 以上ある	ティア 3 以上
Kubernetes/Terraform ファイルが存在する	ティア 4-5
CONTRIBUTING.md、CODE_OF_CONDUCT.md がある	ティア 6
packages/ または apps/ を含むモノレポ	ティア 4-5

確信度が低い場合： AskUserQuestion を使ってユーザーに確認します。

---

パターン適合性マトリクス

パターン	面接課題	ハッカソン	MVP	成長段階	エンタープライズ
リポジトリパターン	過剰	過剰	境界的	適切	必須
イベント駆動アーキテクチャ	過剰	過剰	過剰	選択的	適切
DI コンテナ	過剰	過剰	軽量なもののみ	適切	必須
DTO レイヤーの分離	過剰	過剰	追加 1 層	2 層	全レイヤー
マイクロサービス	決して使わない	決して使わない	決して使わない	抽出のみ	適切
CQRS	過剰	過剰	過剰	過剰	正当な理由がある場合
ヘキサゴナルアーキテクチャ	過剰	過剰	過剰	境界的	適切
DDD（境界づけられたコンテキスト）	過剰	過剰	過剰	選択的	適切
メッセージキュー	過剰	過剰	境界的	適切	必須
API バージョニング	省略	省略	URL プレフィックス	ヘッダーベース	完全な戦略
エラー処理	try/catch	console.log	エラーバウンダリー	エラーサービス	RFC 9457
ロギング	console.log	なし	構造化 JSON	一元管理	OpenTelemetry

経験則： 判定されたティアでパターンが「過剰」となっている場合は、そのパターンを使わないでください。代わりに、よりシンプルな代替案を提案します。

---

ティア別テクノロジークイックリファレンス

選択肢	面接	ハッカソン	MVP	成長期	エンタープライズ
データベース	SQLite / JSON file	インメモリ / SQLite	マネージド Postgres	Postgres + Redis	Postgres + キュー + キャッシュ
認証	ハードコード / なし	なし	Clerk / Supabase Auth	認証サービス	OAuth2 / SAML / SSO
状態管理	useState	useState	Zustand / Context	Zustand + React Query	Redux / カスタム + キャッシュ
CSS	インライン / Tailwind	Tailwind	Tailwind	Tailwind + デザイントークン	デザインシステム
API	Express routes	単一ファイルのハンドラー	Next.js API routes	FastAPI / Express	ゲートウェイ + サービス
デプロイ	localhost	Vercel / Railway	Vercel / Railway	Docker + マネージド	K8s / ECS
CI/CD	なし	なし	GitHub Actions の基本機能	マルチステージパイプライン	フルパイプライン + ゲート
モニタリング	なし	なし	エラー追跡のみ	APM + ログ	フルオブザーバビリティスタック

---

構築するか購入するかの意思決定ツリー（ティア 1～3）

面接、ハッカソン、MVP のティアでは、構築するより購入することを常に優先してください。

機能	購入（SaaS を使用）	構築（次の場合のみ）
認証	Clerk、Supabase Auth、Auth0	中核製品が認証そのものの場合
決済	Stripe	中核製品が決済そのものの場合
メール	Resend、SendGrid	中核製品がメールそのものの場合
ファイルストレージ	S3、Cloudflare R2	コンプライアンス上、オンプレミスが必要な場合
検索	Algolia、Typesense Cloud	1,000 万件を超えるドキュメントがある、または独自のランキングが必要な場合
アナリティクス	PostHog、Mixpanel	独自のデータ要件がある場合

時間の節約： 認証だけでも、構築には 2～4 週間かかりますが、統合なら 2 時間です。

---

アップグレードパス

プロジェクトが現在のティアを超えて成長したら、段階的にアップグレードしてください。

Tier 2 (Prototype) → Tier 3 (MVP)
  Add: Postgres, basic auth, error boundaries, CI

Tier 3 (MVP) → Tier 4 (Growth)
  Add: Redis cache, background jobs, monitoring, module boundaries

Tier 4 (Growth) → Tier 5 (Enterprise)
  Add: DI, bounded contexts, message queues, full observability
  Extract: First microservice (only the proven bottleneck)

重要なポイント： 複雑さはいつでも後から追加できます。簡単に取り除くことはできません。

---

このスキルが有効になるとき

このスキルは、次によって読み込まれます。

• brainstorm のフェーズ 0（コンテキストの検出）
• implement のステップ 0（コンテキストの検出）
• quality-gates の YAGNI チェック
• 推奨内容を適切な規模に調整する必要があるすべてのスキル

検出されたティアは、後続の判断を制約するコンテキストとして渡されます。

---

関連スキル

• ork:brainstorm - フェーズ 0 でティア検出を使用し、アイデアを絞り込みます
• ork:implement - ステップ 0 でティア検出を使用し、アーキテクチャを絞り込みます
• ork:quality-gates - YAGNI ゲートがこのスキルのティアマトリックスを参照します
• ork:architecture-patterns - アーキテクチャの検証（ティアによる制約あり）

---

参考資料

Read("references/<file>") で必要に応じて読み込みます。

ファイル	内容
interview-takehome.md	ティア 1～2 の詳細
startup-mvp.md	ティア 3 のパターンと判断
enterprise.md	ティア 4～5 のパターンと正当化基準
open-source.md	ティア 6 特有の考慮事項