リライトを減らすための、クリーンなソフトウェアアーキテクチャ向けプロンプトパターン

AI支援作業における「クリーンなアーキテクチャ」の姿

このポストで言う「クリーンなアーキテクチャ」は特定のフレームワークや完璧な図を指すわけではありません。短い説明でシステムを説明でき、関連のない部分を壊さずに変更でき、煩雑なテストなしに振る舞いを検証できることを意味します。

実用的な定義：明確さ、モジュール性、テスト容易性

明確さとは、短い説明でシステムの目的と形が明白であること：何をするか、誰が使うか、どんなデータを扱うか、そして何を絶対にしてはいけないか。AI支援作業では、モデルが要件をあなたが承認できる形で言い直せることも明確さに含まれます。

モジュール性とは、責務にクリーンな境界があること。各モジュールは役割、入力／出力を持ち、他モジュールの内部をできるだけ知らない。AIがコードを生成するとき、モジュール性があればビジネスルールがコントローラー／UI／データアクセスに散らばるのを防げます。

テスト容易性とは、“動くことを証明する”コストが低いこと。ビジネスルールはフルシステムなしにテストでき、統合テストは全経路ではなくいくつかの契約に集中できます。

なぜリライトが起きるのか（そしてAIがそれを助長する理由）

リライトはたいてい「悪いコード」ではなく、不足する制約、あいまいなスコープ、隠れた仮定が原因です。例：

• ある機能が一つのユーザータイプ向けに作られたが、後で3種類の役割と異なる権限があると分かる
• パフォーマンスや監査ログ、データ保持ルールが後から出てくる
• 外部APIが予想と違う挙動をして、あちこち修正が必要になる

AIは説得力のある出力を素早く生成するため、この失敗モードを加速できます。つまり、揺らぎのある土台の上に素早く構築してしまいやすいのです。

このガイドのパターンで期待すること

以下のパターンはそのまま使えるテンプレートであって魔法ではありません。本当に狙っているのは、早期に正しい会話を強制することです：制約を明確にし、選択肢を比較し、仮定を文書化し、契約を定義する。これらを省くと、モデルは喜んで空白を埋めてしまい、その代償を後で払うことになります。

これらのパターンがワークフローのどこに入るか

これらはデリバリーサイクル全体で使います：

• 計画： 要件と成功基準を締める
• 設計： 境界、データフロー、契約を決める
• コーディング： 実装が成長しても責務を分離しておく
• レビュー： リスクや不整合をリライトになる前に検出する

チャットで生成・反復するようなvibe-codingワークフローなら、これらのチェックポイントはさらに重要です。例えば Koder.ai では、React/Go/PostgreSQLコードを生成する前に“planning mode”ループで要件と契約を固め、スナップショット／ロールバックで仮定変更時に安全に反復できます。こうすれば、すべての変更がリライトにつながることを避けられます。

余計な作業を増やさないプロンプト活用法

プロンプトパターンは、意思決定の揺れを減らすときに最も価値があります。コツは短く、繰り返し使えるチェックポイントとして利用すること——コーディング前、設計中、レビュー時に使い、AIが再利用可能な成果物を出すようにすることです。

いつ使うか

コーディング前： 目標、ユーザー、制約、成功基準を確認する1回の整合ループを回す。

設計中： 明示的なトレードオフ（代替案、リスク、データ境界）を強制するパターンを使う。

レビュー中： チェックリスト型のプロンプトでギャップ（エッジケース、監視、セキュリティ、性能）を見つける。

まずは入力を集める（軽量に）

小さく一貫した入力バンドルがあれば出力は良くなります：

• ゴール： 「完了」とみなす条件（レイテンシ、UX、コスト上限）
• ユーザー： 役割、主要ワークフロー、トップの痛点
• 制約： 技術スタック、締め切り、コンプライアンス/セキュリティ
• データ＆連携： ソース、オーナーシップ、API、サードパーティ依存

不明な点があればはっきりそう書き、AIに仮定を列挙させてください。

再利用可能な出力フォーマットを要求する

「設計を説明して」ではなく、ドキュメントやチケットに貼れる成果物を要求します：

• 意思決定ログ（選択肢 → 利点/欠点 → 選択 → 理由）
• コンポーネント表（責務・境界）
• 信頼性とテストのチェックリスト
• 図の記述（Mermaidテキストなど）

受け入れ基準を入れて小さなループで反復する

10–15分ループ：プロンプト → ざっと確認 → 修正。必ず受け入れ基準（設計が受け入れられるために満たすべきこと）を入れ、AIにそれと照らして自己検証させます。これで無限の設計ループに陥るのを防げ、次で紹介するパターンが素早く使えるようになります。

パターン1：設計の前に要件を明確化する

多くの「アーキテクチャリライト」は図が悪いから起きるのではなく、正しいものを間違った（あるいは不完全な）問題のために作ってしまうことが原因です。LLMを早期に使うとき、最初にアーキテクチャを求めるのではなく、あいまいさを露出させてください。

プロンプトの手法：不確実性をチェックリストに変える

モデルを要件インタビュアーとして使います。目標は、コンポーネント設計、DB選定、API決定をする前に確認できる短く優先付けされた仕様を得ることです。

以下はコピー＆ペーストで使えるテンプレートです：

You are my requirements analyst. Before proposing any architecture, do this:

1) Ask 10–15 clarifying questions about missing requirements and assumptions.
   - Group questions by: users, workflows, data, integrations, security/compliance, scale, operations.

2) Produce a prioritized scope list:
   - Must-have
   - Nice-to-have
   - Explicitly out-of-scope

3) List constraints I must confirm:
   - Performance (latency/throughput targets)
   - Cost limits
   - Security/privacy
   - Compliance (e.g., SOC2, HIPAA, GDPR)
   - Timeline and team size

4) End with: “Restate the final spec in exactly 10 bullets for confirmation.”

Context:
- Product idea:
- Target users:
- Success metrics:
- Existing systems (if any):

出力で注意すること

重要なのは、決定を迫るような質問（単なる「もっと教えて」ではない）と、計画内で実際に終わらせられるMust-haveのリストです。"10箇条"の再表現は契約として扱ってチケットやPRDに貼り、利害関係者から即答をもらってからアーキテクチャへ進んでください。これだけで、最も一般的な後工程の手戻り（本当に必要でなかった機能を作ること）を防げます。

パターン2：まずユーザージャーニーを書き、それから技術判断

「イベントソーシングを使うべきか？」のようにツールから入り始めると、ユーザーではなくアーキテクチャのために設計してしまいがちです。AIにまずユーザージャーニーを平易に描かせ、それをコンポーネント・データ・APIに翻訳する流れが、よりクリーンな構造を生みます。

ジャーニー優先の簡単なプロンプトテンプレート

コピー＆ペースト開始ポイント：

• Roles: user / admin / system
• Key actions: 各役割が何を達成しようとするか
• Edge cases: 起こりうる失敗（無効入力、権限なし、部分完了）

そして次を依頼：

1. “Describe the step-by-step flow for each action in plain language.”

2. “Provide a simple state diagram or state list (e.g., Draft → Submitted → Approved → Archived).”

3. “List non-happy-path scenarios: timeouts, retries, duplicate requests, cancellations, and invalid inputs.”

ジャーニーを設計判断に変える（先走らないこと）

フローが明確になったら、次のような技術的決定にマッピングします：

• どこにバリデーションが必要で、どこがビジネスルールか？
• どのステップに冪等性が必要か（安全な再試行）？
• どのデータを保存し、どれが導出可能で、どれに監査履歴が必要か？

その上でアーキテクチャのスケッチ（サービス／モジュール、境界、責務）をフローに紐づけて要求してください。

フローをテスト可能な受け入れ基準に変換する

最後にAIに各ジャーニーをテスト可能な受け入れ基準に変えてもらいます：

• 各ステップと失敗ケースのGiven/When/Then
• システムが返すべきもの／表示すべきもの
• ログに何を書くか、何が再試行かユーザー向けエラーか

このパターンは、アーキテクチャが技術前提ではなくユーザー行動から育つため、リライトを減らします。

パターン3：驚きのリライトを防ぐ仮定ログ

多くのアーキテクチャの作り直しは「悪い設計」ではなく、後で誤りとわかる隠れた仮定が原因です。LLMに設計を尋ねると、穴を埋めるためにもっともらしい推測を挿入してしまいます。仮定ログはその推測を早期に可視化します。

モデルに求めること

目的は、あなたが提供した事実とモデルが推測した仮定をきれいに分けることです。

このプロンプトパターンを使ってください：

Template prompt “Before proposing any solution: list your assumptions. Mark each as validated (explicitly stated by me) or unknown (you inferred it). For each unknown assumption, propose a fast way to validate it (question to ask, metric to check, or quick experiment). Then design based only on validated assumptions, and call out where unknowns could change the design.”

再利用しやすい「仮定ログ」形式

短く使いやすい形式にしてください：

• Assumption: …
• Status: validated / unknown
• Why it matters: どの判断に影響するか
• How to validate: 質問／確認／スパイク
• If wrong, likely change: どこを再設計するか

“何が答えを変えるか？” トリガー

モデルに転換点を示させる一行を加えてください：

• “List 5 triggers: what would change your answer? (e.g., user volume, latency targets, compliance needs, data retention rules).”

このパターンにより、設計は条件付きの意思決定群になります。単なる図だけでなく、コミット前に確認すべき地図が得られます。

パターン4：一つに決める前に複数案を比較する

AIは一つの“最適”設計を出すのが得意ですが、それが最初に見えるもっともらしい案であることが多いです。よりクリーンなアーキテクチャは、早い段階で比較を強制したときに現れます。

コアのプロンプトテンプレート

次のようなプロンプトで複数案と構造化されたトレードオフ表を要求してください：

Propose 2–3 viable architectures for this project.
Compare them in a table with criteria: complexity, reliability, time-to-ship, scalability, cost.
Then recommend one option for our constraints and explain why it wins.
Finally, list “what we are NOT building” in this iteration to keep scope stable.

Context:
- Users and key journeys:
- Constraints (team size, deadlines, budget, compliance):
- Expected load and growth:
- Current systems we must integrate with:

これがリライトを減らす理由

比較は、モデル（とあなた）に隠れた仮定を表に出させます：状態の所在、サービス間通信、同期すべき点、遅延可能な点など。

評価基準の表は「マイクロサービス vs モノリス」の議論を感情論にしないで、あなたが本当に重視するもの（早く出すこと／運用負荷を減らすこと／信頼性を上げること）に決定を紐づけます。

推奨と境界を要求する

「状況による」が答えの終着点になるのを許さないでください。明確な推奨とそれが最適化する具体的な制約を要求します。

また“今回作らないもの”を必須で書かせてください。例：「MVPではマルチリージョンフェイルオーバーなし」「プラグインシステムなし」「リアルタイム通知なし」。これにより、スコープが気付かないうちに拡大するのを防げます。

パターン5：モジュール境界と責務を明確にする

多くのリライトは境界が曖昧で起きます：何でもが何でも触る状態だと些細な変更が波及します。このパターンでは、誰が何を所有するかを明確にするプロンプトを使ってください。

コアの考え方

AIにモジュールと責務を定義させ、それぞれのモジュールに含まれないことも明記させます。さらにインターフェース（入力／出力）と依存関係ルールを出し、実装詳細やビルド計画は求めないでください。

コピー＆ペースト用プロンプトテンプレート

新機能のスケッチやリファクタ時に使ってください：

• Context: <one paragraph about the product/feature>
• Goal: Propose a modular architecture with 4–8 modules.

1. List modules with:

   • Purpose (1 sentence)
   • Responsibilities (3–5 bullets)
   • Non-responsibilities (“does NOT handle…”) (2–3 bullets)

2. For each module, define interfaces only:

   • Inputs (events/requests/data)
   • Outputs (responses/events/side effects)
   • Public API surface (function names or endpoints ok; no internal classes)

3. Dependency rules:

   • Allowed dependencies (A → B)
   • Forbidden dependencies (A ↛ C) with reasoning
   • Where shared types live (and what must never be shared)

4. Future change test: Given these likely changes: <list 3>, show which single module should absorb each change and why.

良い出力の目安

チームメイトに1分で説明できるモジュールを目指してください。AIが“Utils”のような雑多モジュールを提案したり、コントローラーにビジネスルールを置く場合は「意思決定はドメインモジュールに移してアダプタは薄く保つ」と突っ込みましょう。

境界が明確であれば変更には明確な帰属ができ、依存ルールが偶発的な結合を防ぎます。

パターン6：データ＆API契約を先に（統合手戻り回避）

統合手戻りは「コードが悪い」よりも「契約が不明確」なことが原因で起きます。データモデルとAPIの形を後回しにするとチームごとに空白を埋め、次スプリントで調整に時間を取られます。

フレームワークやDB、マイクロサービスを議論する前に契約を出してください。明確な契約がUI、バックエンド、データパイプラインを揃えてくれます。

契約優先のプロンプト

早期にAIアシスタントへ次を要求します：

• Template: “Describe the data model, ownership, and lifecycle for each entity”

続けて：

• 各API契約の例（リクエスト、レスポンス、エラー構造）
• バージョニングと後方互換の期待
• 各フィールドのバリデーションルールとエッジケース

良い出力の例

具体的な成果物を求めてください。例：

• Entity: Subscription
  • Owner: Billing service
  • Lifecycle: created on checkout → active → past_due → canceled (soft-delete after 90 days)
  • Source of truth: billing DB; other services cache read-only copies

APIのスケッチ例：

POST /v1/subscriptions
{
  "customer_id": "cus_123",
  "plan_id": "pro_monthly",
  "start_date": "2026-01-01"
}

201 Created
{
  "id": "sub_456",
  "status": "active",
  "current_period_end": "2026-02-01"
}

422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "start_date must be today or later",
    "fields": {"start_date": "in_past"}
  }
}

バージョニングと互換性ルール

AIには次のようなルールを明示させてください：「追加フィールドはバージョンアップ不要。名前変更は/v2。クライアントは不明フィールドを無視する」。これだけで静かに壊れる変更と、それに伴う大きなリライトを防げます。

パターン7：失敗モードと信頼性チェックリスト

「ハッピーパスだけ」の設計は実トラフィックや不安定な依存と出会うと崩れます。信頼性を明示的な設計出力に含めれば、ローンチ後の後手対応を減らせます。

コピー＆ペースト用プロンプトテンプレート

選んだアーキテクチャ記述とともに次を依頼します：

List failure modes; propose mitigations; define observability signals.

For each failure mode:

• What triggers it?
• User impact (what the user experiences)
• Mitigation (design + operational)
• Retries, idempotency, rate limits, timeouts considerations
• Observability: logs/metrics/traces + alert thresholds

モデルに必ずカバーさせること（非交渉）

失敗しうるインターフェース名を列挙して、それぞれについて具体的に決めさせてください：外部API、DB、キュー、認証プロバイダ、バックグラウンドジョブ。

具体的に決める項目：

• Retries: いつ再試行するか、回数、バックオフ戦略、再試行可能なエラーの定義
• Idempotency: 冪等キー、重複除去窓口、再実行安全性
• Rate limits: ユーザー／IP／サービス別の制限とクライアント向けの文言
• Timeouts: 依存ごとのタイムアウト、全体予算、キャンセル伝播

信頼性チェックリストの出力

最後に「2分でレビューできる簡単なチェックリスト」を返すようにしてください。良いチェックリスト項目例：依存のタイムアウト設定、再試行の上限、作成／課金系の冪等性、バックプレッシャ／レート制御、グレースフルディグレード経路の定義。

ユーザーアクションに紐づく可観測性

システム内部だけでなくユーザーの主要イベント（例：user_signed_up, checkout_submitted, payment_confirmed, report_generated）に関するイベントを要求し、それぞれについて：

• ログ項目（user_id, request_id, idempotency_key）
• メトリクス（成功率、レイテンシ p95/p99、再試行回数）
• トレース（依存呼び出しごとのスパン）

これで信頼性がコード以前の設計アーティファクトになります。

パターン8：過剰構築を避けるMVPスライス計画

AI支援の設計がリライトを生む一つの要因は、早期に“完全”なアーキテクチャを作ってしまうことです。解決は単純で、最小の有用スライス（価値を出し、設計を検証できるもの）から始めます。

プロンプトテンプレート

解が広がりすぎていると感じたら：

Template: “Propose the smallest usable slice; define success metrics; list follow-ups.”

AIに返してもらう内容：

• MVP slice: 出荷するために含めるもの
• Success metrics: 成功を示す定量的／定性的指標
• Follow-ups: 学習を妨げないで後回しにできる項目

段階的ロードマップ（MVP → v1 → v2）を要求する

さらに「MVP → v1 → v2 の段階別ロードマップを出し、各フェーズが減らすリスクを説明せよ」と指示してください。こうすれば後続のアイデアを見える化しつつ初期実装に押し込みません。

範囲外を明示してスコープ膨張を防ぐ

最も強力な一行は「MVPで明示的に除外するものを列挙せよ」です。例：

• "MVPでは多地域フェイルオーバーなし（インシデントはログ → v2で検討）"
• "MVPにプラグインシステムはなし（境界は保つ）"
• "最初は支払いプロバイダは1つのみ。後で抽象化"

計画をチケット化する

最後に「MVPをチケットに分割し、受け入れ基準と依存関係を付与せよ」と指示してください。典型的なチケット分割：

1. 薄いエンドツーエンドのハッピーパス
2. 最小データモデル + API契約
3. 基本的なエラーハンドリングとログ
4. スタブフォールバック付きの1つの統合ポイント

必要ならチームのフォーマット（Jira風フィールドなど）で出力させてバックログと紐付けてください。

パターン9：設計を形作るテストファーストプロンプト

設計のぶれを止める簡単な方法は、最初に受け入れテストを書かせることです。LLMに先にテストを書かせれば、振る舞い、入力、出力、エッジケースを名指しする必要があり、自然と責務が分離されます。

コピー＆ペースト用テンプレート

コンポーネント設計の直前に次を必須にしてください：

• Template: “Write acceptance tests first; then propose implementation. You must: (1) list assumptions, (2) name unit vs integration tests, (3) define test data and mocks vs real dependencies, (4) include a definition of done.”

モジュールに対応したテスト境界を要求する

続けて：「テストをモジュール責務ごとにグループ化せよ（API層、ドメインロジック、永続化、外部連携）。各グループで何をモックし、何を実依存にするかを明記せよ」と指示してください。

これにより、統合テストの境界が明確でないなら設計が不十分だとわかります。

テストデータ戦略：壊れやすいスイートを避ける

要求："テストデータ計画を提案せよ：フィクスチャ vs ファクトリ、エッジケース生成法、決定性の維持。どの依存はインメモリフェイクで良く、CIで実サービスを使うべきかを列挙せよ。"

こうしておけば、簡単なはずの機能が実は契約やシードデータ、安定IDを必要としていることを早く発見できます。

完了の定義（実装が出荷できる状態にする）

軽量チェックリストで終わらせます：

• テスト合格（単体＋統合）と失敗ケースの十分なカバレッジ
• 最小限のドキュメント：使い方、設定、簡易トラブルシュート
• 重要な失敗モード用の監視／アラート
• ロールアウト計画（フィーチャーフラグ、マイグレーション手順、ロールバック）

パターン10：問題を早期に見つける設計レビュー用プロンプト

設計レビューはコードの後だけにするべきではありません。AIに設計草案（短い段落や言葉での図）をレビューさせ、リライトになる前に具体的な弱点を列挙させましょう。

コアのレビュー用テンプレート

強めのレビュアーを想定して具体性を強制します：

Prompt: “Act as a reviewer; list risks, inconsistencies, and missing details in this design. Be concrete. If you can’t evaluate something, say what information is missing.”

設計要約、制約（予算、スケジュール、チームスキル）、非機能要件（レイテンシ、可用性、コンプライアンス）を貼り付けてください。

フィードバックを実行可能なパンチリストに変える

曖昧なフィードバックは失敗の元です。次の形式で出させてください：

Prompt: “Give me a prioritized punch list. For each item: severity (Blocker/High/Medium/Low), why it matters, suggested fix, and the smallest validation step.”

こうして得た出力は議論ではなくタスクになります。

リライトリスクを定量化する

簡易的なスコアを入れると有効です：

Prompt: “Assign a rewrite risk score from 1–10. Explain the top 3 drivers. What would reduce the score by 2 points with minimal effort?”

精度を求めるのではなく、リライトにつながりやすい仮定を表面化させることが目的です。

差分プランで範囲拡大を防ぐ

最後に「diff plan」を出させてください：最小変更で目標設計に到達するには何を残し、何を変えるか、破壊的影響は何か。これにより設計が小さな可逆ステップで進化するようになります。

コピー＆ペースト可能なプロンプトパックと簡単なワークフロー

このパックを毎機能で繰り返せる軽量ワークフローとして使ってください。アイデアはプロンプトを連鎖させ、各ステップが次のステップで再利用できる成果物を生むことです。そうすれば文脈が失われず、驚きのリライトが減ります。

6ステップのワークフロー（これらのパターンをチェーン）

1. 要件（明確化＋制約）
2. アーキテクチャ案（2–3案比較）
3. 境界（モジュール＋責務）
4. 契約（データ＋API）
5. テスト（テストファースト受け入れ＋主要な単体テスト）
6. レビュー（失敗モード＋設計レビュー用チェックリスト）

実務では、このチェーンを「フィーチャーレシピ」として実装することが多いです。Koder.aiのようなチャット駆動のビルドプロセスにマッピングすると、成果物を一箇所に集めて最初の動くスライスを生成し、スナップショットで実験を可逆にしながら反復できます。MVPが準備できたらソースをエクスポートしたりカスタムドメインでデプロイしたりできます—AI支援のスピードを活かしつつ環境に縛られない運用が可能です。

コピー＆ペースト用のプロンプトパック（ガードレール付き）

SYSTEM (optional)
You are a software architecture assistant. Be practical and concise. 
Guardrail: When you make a recommendation, cite the specific lines from *my input* you relied on by quoting them verbatim under “Input citations”. Do not cite external sources or general industry claims.
If something is unknown, ask targeted questions.

1) REQUIREMENTS CLARIFIER
Context: <product/system overview>
Feature: <feature name>
My notes: <paste bullets, tickets, constraints>

Task:
- Produce: (a) clarified requirements, (b) non-goals, (c) constraints, (d) open questions.
- Include “Input citations” quoting the exact parts of my notes you used.

2) ARCHITECTURE OPTIONS
Using the clarified requirements above, propose 3 architecture options.
For each: tradeoffs, complexity, risks, and when to choose it.
End with a recommendation + “Input citations”.

3) MODULAR BOUNDARIES
Chosen option: <option name>
Define modules/components and their responsibilities.
- What each module owns (and does NOT own)
- Key interfaces between modules
- “Input citations”

4) DATA & API CONTRACTS
For each interface, define a contract:
- Request/response schema (or events)
- Validation rules
- Versioning strategy
- Error shapes
- “Input citations”

5) TEST-FIRST ACCEPTANCE
Write:
- Acceptance criteria (Given/When/Then)
- 5–10 critical tests (unit/integration)
- What to mock vs not mock
- “Input citations”

6) RELIABILITY + DESIGN REVIEW
Create:
- Failure modes list (timeouts, partial failure, bad data, retries)
- Observability plan (logs/metrics/traces)
- Review checklist tailored to this feature
- “Input citations”

最後に：深掘りが必要なら /blog/prompting-for-code-reviews を、ツール評価やチーム展開の検討は /pricing を実務的な次の一手として参照してください。