2025年11月16日·2 分
リライトを減らすための、クリーンなソフトウェアアーキテクチャ向けプロンプトパターン
AIを要件の明確化、モジュール化された設計、テスト可能なコードへ導く実証済みのプロンプトパターンを学び、リファクタや全面的な書き直しを減らしましょう。
AIを要件の明確化、モジュール化された設計、テスト可能なコードへ導く実証済みのプロンプトパターンを学び、リファクタや全面的な書き直しを減らしましょう。
このポストで言う「クリーンなアーキテクチャ」は特定のフレームワークや完璧な図を指すわけではありません。短い説明でシステムを説明でき、関連のない部分を壊さずに変更でき、煩雑なテストなしに振る舞いを検証できることを意味します。
明確さとは、短い説明でシステムの目的と形が明白であること：何をするか、誰が使うか、どんなデータを扱うか、そして何を絶対にしてはいけないか。AI支援作業では、モデルが要件をあなたが承認できる形で言い直せることも明確さに含まれます。
モジュール性とは、責務にクリーンな境界があること。各モジュールは役割、入力／出力を持ち、他モジュールの内部をできるだけ知らない。AIがコードを生成するとき、モジュール性があればビジネスルールがコントローラー／UI／データアクセスに散らばるのを防げます。
テスト容易性とは、“動くことを証明する”コストが低いこと。ビジネスルールはフルシステムなしにテストでき、統合テストは全経路ではなくいくつかの契約に集中できます。
リライトはたいてい「悪いコード」ではなく、不足する制約、あいまいなスコープ、隠れた仮定が原因です。例：
AIは説得力のある出力を素早く生成するため、この失敗モードを加速できます。つまり、揺らぎのある土台の上に素早く構築してしまいやすいのです。
以下のパターンはそのまま使えるテンプレートであって魔法ではありません。本当に狙っているのは、早期に正しい会話を強制することです：制約を明確にし、選択肢を比較し、仮定を文書化し、契約を定義する。これらを省くと、モデルは喜んで空白を埋めてしまい、その代償を後で払うことになります。
これらはデリバリーサイクル全体で使います：
チャットで生成・反復するようなvibe-codingワークフローなら、これらのチェックポイントはさらに重要です。例えば Koder.ai では、React/Go/PostgreSQLコードを生成する前に“planning mode”ループで要件と契約を固め、スナップショット／ロールバックで仮定変更時に安全に反復できます。こうすれば、すべての変更がリライトにつながることを避けられます。
プロンプトパターンは、意思決定の揺れを減らすときに最も価値があります。コツは短く、繰り返し使えるチェックポイントとして利用すること——コーディング前、設計中、レビュー時に使い、AIが再利用可能な成果物を出すようにすることです。
コーディング前： 目標、ユーザー、制約、成功基準を確認する1回の整合ループを回す。
設計中： 明示的なトレードオフ（代替案、リスク、データ境界）を強制するパターンを使う。
レビュー中： チェックリスト型のプロンプトでギャップ（エッジケース、監視、セキュリティ、性能）を見つける。
小さく一貫した入力バンドルがあれば出力は良くなります：
不明な点があればはっきりそう書き、AIに仮定を列挙させてください。
「設計を説明して」ではなく、ドキュメントやチケットに貼れる成果物を要求します：
10–15分ループ：プロンプト → ざっと確認 → 修正。必ず受け入れ基準（設計が受け入れられるために満たすべきこと）を入れ、AIにそれと照らして自己検証させます。これで無限の設計ループに陥るのを防げ、次で紹介するパターンが素早く使えるようになります。
多くの「アーキテクチャリライト」は図が悪いから起きるのではなく、正しいものを間違った（あるいは不完全な）問題のために作ってしまうことが原因です。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に貼り、利害関係者から即答をもらってからアーキテクチャへ進んでください。これだけで、最も一般的な後工程の手戻り（本当に必要でなかった機能を作ること）を防げます。
「イベントソーシングを使うべきか？」のようにツールから入り始めると、ユーザーではなくアーキテクチャのために設計してしまいがちです。AIにまずユーザージャーニーを平易に描かせ、それをコンポーネント・データ・APIに翻訳する流れが、よりクリーンな構造を生みます。
コピー＆ペースト開始ポイント：
そして次を依頼：
“Describe the step-by-step flow for each action in plain language.”
“Provide a simple state diagram or state list (e.g., Draft → Submitted → Approved → Archived).”
“List non-happy-path scenarios: timeouts, retries, duplicate requests, cancellations, and invalid inputs.”
フローが明確になったら、次のような技術的決定にマッピングします：
その上でアーキテクチャのスケッチ（サービス／モジュール、境界、責務）をフローに紐づけて要求してください。
最後にAIに各ジャーニーをテスト可能な受け入れ基準に変えてもらいます：
このパターンは、アーキテクチャが技術前提ではなくユーザー行動から育つため、リライトを減らします。
多くのアーキテクチャの作り直しは「悪い設計」ではなく、後で誤りとわかる隠れた仮定が原因です。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.”
短く使いやすい形式にしてください：
モデルに転換点を示させる一行を加えてください：
このパターンにより、設計は条件付きの意思決定群になります。単なる図だけでなく、コミット前に確認すべき地図が得られます。
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ではマルチリージョンフェイルオーバーなし」「プラグインシステムなし」「リアルタイム通知なし」。これにより、スコープが気付かないうちに拡大するのを防げます。
多くのリライトは境界が曖昧で起きます：何でもが何でも触る状態だと些細な変更が波及します。このパターンでは、誰が何を所有するかを明確にするプロンプトを使ってください。
AIにモジュールと責務を定義させ、それぞれのモジュールに含まれないことも明記させます。さらにインターフェース（入力／出力）と依存関係ルールを出し、実装詳細やビルド計画は求めないでください。
新機能のスケッチやリファクタ時に使ってください：
List modules with:
For each module, define interfaces only:
Dependency rules:
Future change test: Given these likely changes: <list 3>, show which single module should absorb each change and why.
チームメイトに1分で説明できるモジュールを目指してください。AIが“Utils”のような雑多モジュールを提案したり、コントローラーにビジネスルールを置く場合は「意思決定はドメインモジュールに移してアダプタは薄く保つ」と突っ込みましょう。
境界が明確であれば変更には明確な帰属ができ、依存ルールが偶発的な結合を防ぎます。
統合手戻りは「コードが悪い」よりも「契約が不明確」なことが原因で起きます。データモデルとAPIの形を後回しにするとチームごとに空白を埋め、次スプリントで調整に時間を取られます。
フレームワークやDB、マイクロサービスを議論する前に契約を出してください。明確な契約がUI、バックエンド、データパイプラインを揃えてくれます。
早期にAIアシスタントへ次を要求します：
続けて：
具体的な成果物を求めてください。例：
Subscription
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。クライアントは不明フィールドを無視する」。これだけで静かに壊れる変更と、それに伴う大きなリライトを防げます。
「ハッピーパスだけ」の設計は実トラフィックや不安定な依存と出会うと崩れます。信頼性を明示的な設計出力に含めれば、ローンチ後の後手対応を減らせます。
選んだアーキテクチャ記述とともに次を依頼します：
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、キュー、認証プロバイダ、バックグラウンドジョブ。
具体的に決める項目：
最後に「2分でレビューできる簡単なチェックリスト」を返すようにしてください。良いチェックリスト項目例：依存のタイムアウト設定、再試行の上限、作成／課金系の冪等性、バックプレッシャ／レート制御、グレースフルディグレード経路の定義。
システム内部だけでなくユーザーの主要イベント（例：user_signed_up, checkout_submitted, payment_confirmed, report_generated）に関するイベントを要求し、それぞれについて：
これで信頼性がコード以前の設計アーティファクトになります。
AI支援の設計がリライトを生む一つの要因は、早期に“完全”なアーキテクチャを作ってしまうことです。解決は単純で、最小の有用スライス（価値を出し、設計を検証できるもの）から始めます。
解が広がりすぎていると感じたら：
Template: “Propose the smallest usable slice; define success metrics; list follow-ups.”
AIに返してもらう内容：
さらに「MVP → v1 → v2 の段階別ロードマップを出し、各フェーズが減らすリスクを説明せよ」と指示してください。こうすれば後続のアイデアを見える化しつつ初期実装に押し込みません。
最も強力な一行は「MVPで明示的に除外するものを列挙せよ」です。例：
最後に「MVPをチケットに分割し、受け入れ基準と依存関係を付与せよ」と指示してください。典型的なチケット分割：
必要ならチームのフォーマット（Jira風フィールドなど）で出力させてバックログと紐付けてください。
設計のぶれを止める簡単な方法は、最初に受け入れテストを書かせることです。LLMに先にテストを書かせれば、振る舞い、入力、出力、エッジケースを名指しする必要があり、自然と責務が分離されます。
コンポーネント設計の直前に次を必須にしてください：
続けて：「テストをモジュール責務ごとにグループ化せよ（API層、ドメインロジック、永続化、外部連携）。各グループで何をモックし、何を実依存にするかを明記せよ」と指示してください。
これにより、統合テストの境界が明確でないなら設計が不十分だとわかります。
要求："テストデータ計画を提案せよ：フィクスチャ vs ファクトリ、エッジケース生成法、決定性の維持。どの依存はインメモリフェイクで良く、CIで実サービスを使うべきかを列挙せよ。"
こうしておけば、簡単なはずの機能が実は契約やシードデータ、安定IDを必要としていることを早く発見できます。
軽量チェックリストで終わらせます：
設計レビューはコードの後だけにするべきではありません。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」を出させてください：最小変更で目標設計に到達するには何を残し、何を変えるか、破壊的影響は何か。これにより設計が小さな可逆ステップで進化するようになります。
このパックを毎機能で繰り返せる軽量ワークフローとして使ってください。アイデアはプロンプトを連鎖させ、各ステップが次のステップで再利用できる成果物を生むことです。そうすれば文脈が失われず、驚きのリライトが減ります。
実務では、このチェーンを「フィーチャーレシピ」として実装することが多いです。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 を実務的な次の一手として参照してください。
「クリーンなアーキテクチャ」とは、次のことを意味します：
AI支援の作業では、モデルが要件をあなたが承認できる形で言い直せることも含みます。
AIは説得力のあるコードや設計を素早く生成できるため、不足している制約や隠れた仮定の上に簡単に構築されてしまい、リライトを増幅します。具体的なトリガー例：
対策は「AIを減らす」ことではなく、要件・契約・仮定を早期に露出させるプロンプトを使うことです。
パターンは「決定の揺れ」を減らす短いチェックポイントとして使うのが有効です。出力が再利用可能な成果物になるように設計してください。推奨のタイミング：
反復は10–15分程度：プロンプト → ざっと確認 → 短縮 → 受け入れ基準で自己検証。
最低限持っておくと良い入力バンドル：
不明点は「不明」と明示して、モデルに仮定を列挙させてください。
「設計を説明して」ではなく、次の再利用可能な成果物を要求してください：
こうした出力は実務で貼り付けて使えるため、AI出力が「文量だけ増える」問題を避けられます。
LLMを要件インタビュアーとして使うと効果的です。やること：
その10箇条を利害関係者に貼ってYes/Noをもらってから設計に進むと、後の大半のリファクタを防げます。
まず役割と操作から始め、次に：
フローが明確になってから、どこにバリデーションとビジネスルールがあるか、どこで冪等性が必要か、何を保存すべきかを設計に落としてください。そして各フローをGiven/When/Thenの受け入れ基準に変換します。
LLMはギャップを埋めてしまいがちなので、事実とモデルが推測した仮定を分離するための仮定ログを作ります。項目例：
モデルに**複数案（2–3）**のアーキテクチャを提案させ、評価基準（複雑さ、信頼性、ローンチ時間、スケーラビリティ、コスト）で表にして比較させてください。必ず：
比較を強制すると、状態の所在や同期／非同期の判断など、隠れた仮定が表に出てきます。これがリライトを減らします。
契約優先（contract-first）にすると統合の手戻りを防げます。要求すること：
UI／バックエンド／連携が同じ契約を参照すれば、後で前提が食い違う時間を大幅に減らせます。
「ハッピーパス」で設計すると実トラフィックや不安定な依存に遭遇して改修が必要になります。失敗モードを設計出力に含めることで、後出しの対策を減らせます。必ず出させる項目：
最後に2分でレビューできるチェックリストを返してもらうと実務で使いやすいです。
AIが早期に「完璧な設計」を促すと過剰設計に陥りがちです。最小限の有用なスライス（MVP）から始め、価値を出しつつ設計を検証していきましょう。プロンプトに含めるべき項目：
さらに「MVP → v1 → v2」の段階的ロードマップとMVPで明示的に除外するもの（例：多地域フェイルオーバーなし、プラグインシステムなし）を要求してください。最後にMVPをチケット化して依存関係を明確にすると隠れた結合が見えます。
設計が揺れる原因をテストによって先に固定化します。プロンプトで「最初に受け入れテストを書け」と指示すると、モデルは振る舞い（入力／出力／エッジケース）を明示する必要があり、自然と責務が分離されます。要求例：
テストデータ戦略（フィクスチャ vs ファクトリ、決定性の担保、CIでの実サービス使用可否）も指定させてください。実装前に必要なコントラクトや種データが見つかることが多く、後での書き直しを避けられます。
コードが存在する前でも「プリモーテム」的に設計レビューをAIにさせられます。レビューの核心は具体性です：
さらに優先度付きの修正リスト（Severity, 理由、提案する修正、最小の検証手順）を求めてください。最後にリライトリスクスコア（1–10）と上位3つのドライバー、それを2ポイント下げるための最小の対策を出させると良いです。差分プラン（何を残すか、何を変更するか、破壊的影響）も出させれば、設計変更が大きく膨らむのを防げます。
さらに「回答を変えるトリガー（例：利用量、レイテンシ目標、コンプライアンス、データ保持）」を5つ挙げさせると、設計が条件付きの決定群になります。