AI-first delivery core pattern

AI受託共通コアセット
設計指針パターン

人間エンジニアに「何を作るのか」を説明しやすくするため、既存の設計思想に寄せて整理した図解。結論は、環境変数の分割ではなく 機能契約・境界・adapter・生成テンプレート をひとまとまりで扱う。

全体像: 「生成できる共通コア」と「差し替え可能な外部依存」を分離する

12-Factor × Hexagonal × DDD × Contract-first
Scaffolder 入力から生成 Backstage / CLI / template Capability Contract auth.env.schema / payment.env.schema 12-Factor の粒度を機能別に固定 Generated App Shell Next / Hono / Postgres / Queue 受託ごとの初期値を揃える PR reviewable Modular Monolith Boundary 1 repo / 1 deploy。ただし中身は文脈単位で分け、将来分離できる。 Feature Slice invite-user route.ts usecase.ts schema.ts test.ts Bounded Context identity User Session TenantMember Policy Bounded Context billing Plan Subscription Invoice Ledger Bounded Context audit / ops AuditLog Job WebhookEvent TraceLink Inbound Adapters Web UI / API / Admin / Test harness 同じ usecase を人間・AI・テストが叩く Outbound Adapters Auth / Stripe / Mail / S3 / AI 外部SaaSを app core から隔離 Contracts + Verification OpenAPI / Zod schema / idempotency / outbox / traces / tests AIが安全に生成・変更・検証できる足場
A

12-Factor Capability Contract

envを「dev/stg/prod」だけで束ねず、機能別の設定契約として表現する。

起動時fail-fastenv.schema
B

Ports & Adapters

外部SaaSをadapter化し、業務ロジックからClerk/Stripe/Resend等を隔離する。

差し替えテスト容易
C

Bounded Context Monolith

1 deployのまま、identity/billing/audit等の文脈と言葉を分ける。

DDD将来分離
D

Vertical Slice Capsule

機能ごとにroute/usecase/schema/testを近接配置し、AIにも人間にも読める単位にする。

小PR局所変更
E

Contract-first Scaffolder

テンプレート入力から共通コアを生成し、受託ごとの初期品質を揃える。

OpenAPIBackstage風

候補パターンの評価軸

AIが作る・AIが読む・人間がレビューする前提
パターン
AI開発との相性
実装に落とす形
注意点
Capability Contract
必要設定がschema化され、AIが不足・矛盾を検出しやすい。
`.env.schema`、型生成、起動時検証、secret注入の境界。
envファイルを増やすだけだと油絵化する。
Ports & Adapters
外部依存がmock化でき、AIの変更範囲が安全に狭まる。
`ports/` と `adapters/`、公式sandbox、contract tests。
抽象化しすぎると実装者が読みにくい。
Bounded Context
言葉の衝突を減らし、AIの誤った名寄せ・責務混入を抑える。
module boundary、Postgres schema、context map、public API。
microservices化は急がない。
Vertical Slice
AIが1機能単位で実装・テスト・レビューしやすい。
feature folder、usecase単位、route/schema/test近接。
共通部品の置き場ルールが必要。
Contract-first
API/Schemaが先にあるため、生成・テスト・レビューが安定する。
OpenAPI、Zod、DB migration、client生成、mock server。
契約と実装のdrift検知が必須。

説明の芯

これは「便利なテンプレ集」ではなく、受託開発で毎回ぶれる認証・決済・メール・監査・設定・テストを、機能契約としてattachできる共通コアである。人間は設計思想で理解し、AIは契約と境界を手がかりに実装する。

Implementation checklist
  • 機能ごとの env schema と runtime validator
  • Auth / Payment / Mail / Storage / AI の port 定義
  • 公式sandbox・署名検証・idempotency・outbox
  • OpenAPI / Zod / DB migration の契約同期
  • Scaffolderで生成、CIで契約driftを検出
  • OpenTelemetry的な logs / metrics / traces の最低セット