プロンプト、反復、リファクタ：Vibeコーディングで設計書を置き換える

Vibeコーディングワークフローとは何か

「vibeコーディング」は、まず意図と例を提示し、実装を迅速なプロンプト→実行→調整のサイクルで進化させるソフトウェア開発の方法です。大きな計画を最初に書く代わりに、早い段階で何かを動かし、そこから学んでコードを目的に合わせて舵取りします。

平易な定義

vibeコーディングワークフローは次のように進みます：

• 自然言語でゴールを説明する（具体例を数件含めることが多い）
• AIアシスタントにコード、テスト、あるいは小さな機能のスライスを生成させる
• 実行して結果を検査し、プロンプトを洗練する
• 小さな編集とリファクタで実装を引き締め続ける

「vibe」は勘任せではなく、迅速なフィードバックを指します。実行と反復を使って、長い推測の期間を置き換えているのです。

AIがビルドループに入ると何が変わるか

AIは、詳細なドキュメントを書く労力を、明確で実行可能な指示を書くことへと移します：

• ミニ仕様のように振る舞うプロンプトを書く（「Xを行い、Yは避ける。ここにエッジケース」）
• 出力をすぐに評価する（テスト、ログ、UIの挙動）そして軌道修正する
• 数週間に及ぶ議論なしに代替案（別アプローチ、命名、API）を素早く生成する

設計書を置き換えるのが適している場合（およびそうでない場合）

このアプローチは、プロダクトの反復、社内ツール、初期段階の機能、リファクタで最速の学習が期待できる場合に最も適しています。

正式な承認、厳格なコンプライアンス、長期のクロスチームの約束、あるいは取り返しのつかないアーキテクチャ決定が必要な場合は不向きです。そのような場合は、より小さく、より明確な決定記録（Decision Record）が必要になります。

この記事で得られること

プロンプトを軽量な仕様として扱い、反復を計画ツールとして使い、リファクタとテストで明確さを保ちながら、重い設計文書に頼らずに開発を進める方法を学べます。

なぜ従来の設計書は高速開発で失敗しがちなのか

従来の設計書は変更前に明確さを作ることを目的としていますが、高速な開発環境ではしばしば逆効果になります。つまり、遅くて脆いアーティファクトになり、学習についていけません。

よくある失敗パターン

設計書はすぐに陳腐化する傾向があります。実装が始まると、チームはエッジケース、ライブラリのクセ、性能制約、統合の現実に直面します。誰かが継続的にドキュメントを更新しない限り（稀です）、そのドキュメントはガイドではなく歴史的記録になります。

また、書くのに時間がかかり、読むのにも時間がかかるため、スピードが重視される場ではドキュメントは“あればいい”ものになり、読み流され、その後無視されがちです。労力だけが消費され、見返りが少なくなります。

ドキュメント作成が実際に必要な学習を遅らせる

大きな上流のドキュメントは、難しい部分に直面する前に「設計は終わった」と錯覚させることがあります。

しかし、本当の制約は通常、試してみることでしかわかりません：

• 実際のAPIを叩いて返り値を確認する
• 認証を繋いで権限のエッジケースに遭遇する
• 想定ではなく実測でレイテンシを測る
• 単純に見えたUI状態に実は6つのバリアントがあることを発見する

ドキュメントがこれらの実験を遅らせれば、チームが何が可能か学ぶ瞬間が遅れます。

上流での確実性と変化する要件

高速な開発は動く目標によって形作られます：フィードバックは日々到着し、優先度は変わり、プロトタイプを見て初めて最良の解が変わることがあります。従来の設計書は未来を詳細に予測して早期にコミットできることを前提としていますが、そのミスマッチが無駄を生みます—ドキュメントを書き直すか、あるいは古い計画に従わせる形で作業を進めるかのどちらかです。

真の目標を忘れない

目標はペーパーワークではなく共有された理解です：何を作るのか、なぜ重要か、完了の定義は何か、どのリスクに注意を払うのか。残りは道具に過ぎず、高速な開発では重いドキュメントが適切でないことが多いのです。

プロンプトを実行可能な設計スペックにする

従来の設計書は「何を作るか」「どう機能するか」「変化したらどうするか」を予測しようとします。実行可能なプロンプトはこれを逆転させます。実行して観察し、修正できる“生きた仕様”です。

つまり「ドキュメント」は静的なPDFではなく、次の正しい増分を確実に生み出す指示の集合です。

実行可能なプロダクト要件のようにプロンプトを書く

目的は意図をあいまいさなく、検証可能にすることです。良い実行可能プロンプトは以下を含みます：

• ユーザーストーリー：誰が何のために必要か
• 入力/出力：入るものと出るもの（APIペイロード、UI状態、イベント）
• 制約：性能目標、セキュリティルール、使用/非推奨ライブラリ、互換性
• 受け入れ基準：合格すべき具体的チェック

長い文章の代わりに、コード、テスト、チェックリストを直接生成できる形で仕事を記述します。

前提とエッジケースを最初に要求する

多くの想定外の手戻りは前提が暗黙のまま残るために起こります。プロンプトで明示します：

• 「コーディング前に前提を列挙してください」
• 「エッジケースと失敗モードを指摘してください」
• 「要件が衝突したら確認の質問をしてください」

これにより早期に整合が図られ、重いドキュメントのオーバーヘッドなしに決定の可視化が得られます。

完了の定義をプロンプト内に入れる

設計書で最も有用なのは多くの場合“終わり”の部分です：何が完了と見なされるか。これを実行可能なプロンプトに直接入れておけば、作業と一緒に仕様が移動します。

例えば、プロンプトで「ユニットテスト合格、エラーハンドリング更新、アクセシビリティチェック、変更の短い要約を含める」と要求できます。プロンプトが仕様なら、“完了”は議論ではなく、毎回実行できる検証可能な結果の集合になります。

ツーリングについての注意：プロンプトは実行に近く保つ

このワークフローは、プロンプト、実行、レビュー、ロールバックが密接に結びついているときに最も効果的です。Vibeコーディング向けのプラットフォーム（例: Koder.ai）はそのループを中心に設計されています：チャットでウェブ/サーバ/モバイルのスライスを生成し、計画モードでコード変更前のマイクロプランを作り、スナップショットやロールバックで実験が失敗しても戻せるようにします。結果として“プロンプト劇場”ではなく、実際にテスト可能な増分が増えます。

反復が推測に取って代わる

従来の設計書は不確実性を紙上で「解決」しようとします。しかし、作業で最もリスクが高い部分は、エッジケース、性能ボトルネック、混乱するUXフロー、サードパーティのクセ、実際のユーザーが文章をどう解釈するかといった、紙上では論理的に扱いきれないものです。

vibeコーディングワークフローは不確実性を短いサイクルで“燃やし尽くす”ものと見なします。起こりうることを議論する代わりに、証拠を生む最小のバージョンを作り、それから調整するのです。

薄い垂直スライスから始める

実際にエンドツーエンドで動作する最小のスライスを選びます。これにより統合されない“完璧な”モジュールを避けられます。

例："保存された検索"を構築するなら、すべてのフィルタを最初に設計するのではなく、まず1つのフィルタ、1つの保存、1つの取得で始めます。

ループに時間枠を設ける

サイクルを短く明確に保ちます：

• プロンプト → 実装 → テスト → 調整

30〜90分のタイムボックスが有効です。目標は機能完了ではなく、次に最も大きな不明点を排除することです。次のステップを1〜2文で説明できないなら、そのステップは大きすぎます。

不確実な場合は早めにプロトタイプする

実現可能性やUXに不安があるときは、素早いプロトタイプを作ります。プロトタイプは正しくラベル付けし期待値を管理すれば“捨てコード”ではありません：問いに答えるためのものです。

良いプロトタイプの質問例：

• 「データベーススキーマを変えずにこのエンドポイントをページネーションできるか？」
• 「この文言はユーザーに共有内容を正しく伝えるか？」

仮説的な議論より実際のフィードバックを優先する

実際のフィードバックは内部の議論に勝ります。フラグの裏で実装を出荷する、ステークホルダーにデモする、またはテストデータで自分でフローを試すなど、各ループは具体的なアウトプット（合格テスト、動く画面、計測値、あるいは“これは紛らわしい”という明確な所見）を生むべきです。

プロンプトとマイクロプランで作業を分解する

大きな設計書は決定を前倒しにしがちです。vibeコーディングでは、作業をプロンプトしながら分解し、コードベースが吸収でき、レビュワーが検証できるマイクロプランを生成します。

「境界を決めた」プロンプトから始める

「請求システムを作れ」といった曖昧な指示よりも、単一の成果とその制約を明示したプロンプトを書きます。目的は、答えが実装可能でアーキテクチャをその場で発明する必要がないほど小さいタスクにすることです。

有用な構成：

• ゴール：1つのユーザーが見える変更
• スコープ：明示的に含むもの/除外するもの
• 制約：フレームワーク、パターン、命名、性能/セキュリティの注記
• 完了の定義：動作を示す証拠

コードの前に計画を求める

コード生成前にステップバイステップの計画をAIに出させることを必須にします。完璧な予測を期待するのではなく、レビュー可能なルートを得るためです。

その計画を具体的なチェックリストに変換します：

• 触るファイル：特定のパス
• 追加/変更するAPI：要請/応答の形とエラーケース
• 書くテスト：ユニット/統合、主要なエッジケース

これらが名前を列挙できないなら、まだ漠然としています。

変更はレビュー可能なサイズに保つ

マイクロプランは、各変更が短時間でレビューできるほど小さいときに最も機能します。各プロンプトを1つのPRサイズのスライスとして扱います：スキーマ修正 または エンドポイント または UI状態の遷移、そして反復します。

実用ルール：もしレビュワーが変更を理解するためにミーティングが必要なら、さらに分割してください。

チームの一貫性のために、繰り返し使えるプロンプトテンプレートを短い内部ページ（例：/playbook/prompts）に保管して、分解が個人差ではなく習慣になるようにします。

リファクタリングが実際の設計書になる

リファクタリングは「学んだこと」を「意図したこと」に変える段階です。vibeコーディングでは、初期のプロンプトと反復は意図的に探索的で、薄いスライスを出荷して壊れる箇所を見つけ、そこで実際の制約を発見します。リファクタリングは、その学びを構造、名前、境界、テストに落とし込み、将来のチームメンバーが読んで信頼できる形にします。

名前と境界で意図を明示する

分かりやすいコードベースは自分自身を説明します。例えば、漠然とした handleThing() を calculateTrialEndDate() に改名し、BillingRules モジュールに移すといった変更は、実行可能な形で設計書を書いていることになります。

良いリファクタはしばしば次のようになります：

• ドメインに対応したモジュールの導入（Billing, Permissions, Notifications）
• 副作用を端に寄せる（API呼び出し、DB書き込み）ことでコアロジックを純粋に保つ
• システム内の部分間に明確なインタフェースを作り、変更を局所化する

図の代わりにインタフェースとテストを置く

アーキテクチャ図はすぐ古くなります。きれいなインタフェースはテストで裏付けられるとより長持ちします。

ボックスと矢印の図よりも好ましいのは：

• 小さな公開APIサーフェス（他モジュールが呼べるもの）
• 結果を平易な言葉で記述する受け入れテスト
• 統合の契約テスト（保証される入出力）

「これがどう動くか？」と問われたら、回答はスライドではなくコードの境界とそれを守るテストになります。

学習の後にリファクタする

リファクタは十分な証拠を集めてから予定します：同じ領域で繰り返し変更が起きている、所有権が不明瞭、または不明瞭な境界に起因するバグがある等。プロンプトと反復で素早く学び、リファクタでその学びを固定化して次のビルドを明確な状態から始めます。

文脈を保つ軽量な成果物

大きな設計書をやめることは、記憶を断つことではありません。目的は、将来の自分やチームが「なぜ」そのコードがそのようになっているかを理解できるだけの書かれた文脈を保つことです—進行を凍結せずに。

プロンプトログ（決定・制約・結果）を維持する

重要だったプロンプトとその結果の簡単なログを保ちます。これはリポジトリ内のマークダウンファイル（例：/docs/prompt-log.md）やチケットスレッドでも構いません。

記録する内容：

• 取った決定（何を選んだか）
• 制約（性能、API、セキュリティ、締切）
• 結果（何が出荷されたか、ロールバックされたか、まだ問題が残るか）

これにより「AIに色々頼んだ」という曖昧さが監査可能な履歴になり、レビューや後のリファクタを支えます。

半ページのREADMEか /docs/notes.md に「なぜ」を書く

プロジェクトや機能領域ごとに半ページ程度の“なぜ”ドキュメントを目指します。仕様ではなく、次のような項目：

• この機能が解く問題
• 非ゴール（意図的に作らなかったこと）
• 主要なトレードオフ（再検討する条件）

誰かが「なぜこれをしなかったのか？」と聞いたら、その答えが2分で見つかるようにします。

スコープと受け入れ基準を残すIssueテンプレートを使う

軽量なIssueテンプレートは多くの設計書のセクションを置き換えられます。スコープ、リスク、明確な受け入れ基準（「完了とは…」）のフィールドを含めてください。これによりAIにペーストしても境界を保った出力が得られます。

書き直すよりリンクする

関連するものがあれば内容を重複して書くのではなくリンクで参照します。リンクは相対パス（例：/pricing）を保ち、本当に意思決定に役立つ場合にのみ追加します。

大きなドキュメントなしでチームの整合性を保つ

高速な反復は人々が同じゴールに向かっているときにのみ機能します。コツは「誰もが忘れる巨大なドキュメント」を、小さな儀式と成果物に置き換えて、人間が主導権を保てるようにすることです—特にAIがコード生成を助けるときに重要です。

人間がコントロールする（そして明示しておく）

vibeコーディングワークフローは役割を取り払うわけではなく、明確にします。

• Product は なぜ を担当：解くべき問題、成功の定義、受け入れ可能なトレードオフ
• Design は 体験 を担当：UX制約、アクセシビリティ期待、相互作用パターン
• Engineering は どうやるか を担当：技術的制約、アーキテクチャ方向性、安全性、プロンプトから出荷までの反復ループ

プロンプトでソフトウェアを求めるときはこれらのオーナーを可視化してください。例：「Productはスコープ変更を承認する」「Designは相互作用の変更を承認する」「Engineeringはアーキテクチャ変更を承認する」。これによりAI生成の勢いが静かに決定を書き換えることを防げます。

長いドキュメントレビューの代わりに短い整合セッションを行う

10ページのドキュメントを全員に読ませる代わりに、重要なポイントで15–25分の整合を行います：

• 新機能開始時：成果と制約を確認
• 最初の動作スライス後：コードが実際に何をしているかを確認
• リリース前：受け入れ基準とロールバック計画を確認

出力は小さく実行可能な決定群であるべきです：今出荷するもの、今は出荷しないもの、再検討するもの。継続性が必要なら、広がる物語ではなくリポジトリ内の短いノート（例：/docs/decisions.md）に残してください。

プロンプトが従うべき制約リストを共有する

プロンプトやPR説明に簡単にコピーできる、常に更新される“制約リスト”を維持します：

• セキュリティ：認可ルール、データ取り扱い、ログ/マスキング要件
• 性能：レイテンシ予算、クエリ制限、キャッシュルール
• UX：アクセシビリティ目標、空状態、エラーメッセージのスタイル

反復圧力が上がっても、この制約リストがループのブレを防ぐ軽量ドキュメントのアンカーになります。

変更前に承認境界を合意する

誰が何を承認できるか、いつエスカレーションが必要かを定義します。簡単な方針例：「スコープ/UX/セキュリティの変更は明示的な承認が必要」としておくことで、小さなAI支援の編集が未レビューの再設計にならないようにできます。

1つの指針として：ドキュメントが小さいほど承認は厳格に。これで速さを失わずに整合性を保てます。

品質ゲート：テスト、レビュー、受け入れ基準

スピードは信頼できる出荷があってこそ意味があります。vibeコーディングワークフローでは、品質ゲートが長い「承認」ドキュメントに代わって、変更ごとに実行されるチェックになります。

テスト可能な受け入れ基準から始める

プロンプトを書く前に、ユーザーができること、完了の定義、絶対に起きてはならないことを平易に定義してください。レビュワーが数分で検証できる程度に絞ります。

それから、各基準を少なくとも1つの自動チェックに変換します。

早めに自動テストを追加する（退屈でよい）

機能が「動く」ようになったら待たず、実行経路ができ次第テストを追加します：

• ユニットテスト：コアロジックとエッジケース
• 統合テスト：重要な境界（DB、API、認可）
• スモークテスト：アプリが起動し主要フローが500にならないことを確認

受け入れ基準から直接テストケースをAIに生成させ、現実的に手直しするパターンが有効です。目的は意図のカバレッジであり、巨大なスイートを作ることではありません。

コードレビューを主要ゲートにする

コードレビューを設計と安全性のチェックポイントとして扱います：

• 実装は受け入れ基準と一致しているか？
• エラー状態はハンドルされ、観測可能か（ログ/メトリクス）？
• 将来のリファクタが危険でない程度に読みやすいか？

レビュワーはAIに「何が悪くなり得るか」を出してもらうこともできますが、最終判断はチームにあります。

非機能要件を明示的に追跡する

非機能要件はドキュメントなしでは失われがちなので、ゲートの一部にします：

• レイテンシ/性能（例：p95がXms以内）
• アクセシビリティチェック（キーボード操作、コントラスト）
• プライバシー/セキュリティ（データ保持、PIIの扱い）

これらをPR説明や短いチェックリストに明記して検証されるようにします。

よくある失敗モードと回避法

vibeコーディングは非常に速く動けますが、速度は時にコードベースが圧迫されてからしか見えない失敗を招きます。幸い、多くはいくつかの習慣で防げます。

1) プロンプト過多（話すことが多くて作れない）

プロンプトを練りすぎて増分を出さないなら、新しい形式の設計書麻痺を作っています。

実用的な対処はタイムボックス：十分なプロンプトを書いたら最小スライスを作り、そこで検証してから洗練します。プロンプトは実行可能に保ち、入力/出力/簡単な受け入れチェックを含めてすぐに検証できるようにします。

2) 隠れた決定（「なぜ」が消える）

高速な反復は重要な選択—なぜそのアプローチを取ったのか、何を棄却したのか、どんな制約が効いていたのか—を埋もれさせがちです。後で同じ決定を再議論したり、前提を破る変更が入ったりします。

これを避ける方法：

• PR説明に短い「決定」メモを2–4行書く
• 明確でないトレードオフには該当コード近くにコメントを残す
• 重要な選択は /docs/decisions.md に弾丸で追加する

3) リファクタ回避（速さの名の下の汚いコード）

速く出荷することは持続可能に出荷することと同義ではありません。各反復がショートカットを積み重ねると、将来的に変更が危険になりワークフローが鈍化します。

対処：完了の定義にリファクタを含める：機能が動作したら、名前を簡潔にする、関数を抽出する、不要な経路を削除する追加パスを一回は実行します。安全にリファクタできないなら、テストや境界が足りないというシグナルです。

4) AIドリフト（スタイルとアーキテクチャがばらつく）

ガードレールがないと、各反復でコードが別方向に引っ張られ、命名やフォルダ構成が混在します。

ドリフトを防ぐために：

• プロンプトに小さな「プロジェクトルール」（命名、レイヤリング、エラーハンドリング）を入れる
• アシスタントに参照するフォルダ構成を一つに限定して示す
• レビューで「既存のパターンと一致するか？」を必須にする

これらの習慣は、速さを落とさずに明確さと保守性を守ります。

チームへの実践的な導入プラン

導入は全社的に一気に切り替えるよりも、制御された実験として始めるのが最良です。影響を測りやすい小さな領域を選び、素早く調整します。

1) 小さく、測定可能に始める

1つの機能領域（またはサービス）を選び、次のスプリント1〜2回で追える単一の成功指標を定めます。例：チケットからマージまでのリードタイム、レビュー回数、逃したバグ、オンコールの割り込み数など。

始める前に「完了」の一文定義を書き、実験を正直に保ちます。

2) プロンプトの標準化

プロンプトテンプレートを導入して、プロンプトを比較可能で再利用可能にします。シンプルに：

• ゴール（ユーザーが何をできるべきか）
• 制約（技術スタック、性能、セキュリティ、依存）
• 受け入れ基準（観測可能なチェック）
• 非ゴール（明示的に作らないもの）
• 計画（短いステップバイステップのマイクロプラン）

プロンプトはリポジトリ（例：/docs/prompt-log.md）かチケットに保管し、見つけやすくします。

3) 「最小限のドキュメント」要件を設定する

長い設計書の代わりに、各変更に対して3つの軽量成果物を必須にします：

• プロンプトログ：解決に寄与した最新のプロンプト
• テスト：受け入れ基準を証明する新規/更新テスト
• READMEノート：新しい挙動、フラグ、運用上の懸念を短く説明

これで意図の履歴を保ちながら納品を遅らせません。

4) 2–4週間後にレビューする

短いレトロで成果に集中してレビューします：指標は動いたか？レビューがどこで詰まったか？どのプロンプトが混乱を生んだか？テンプレートを更新し、最小要件を調整し、別の領域に拡大するかを決めます。

オプション：ループを終端までサポートするプラットフォームを使う

重い設計書を置き換えるなら、イテレーションを安全にするツールを使うと効果的です：素早いデプロイ、簡単な環境リセット、実験が失敗してもロールバックできることが重要です。

例：Koder.ai はこのvibeコーディングワークフロー向けに作られており、チャットでマイクロプランと実装を進め、Reactベースのウェブアプリ、Go＋PostgreSQLのバックエンド、Flutterモバイルアプリを生成し、探索から従来のリポジトリワークフローへ移行するためにソースコードをエクスポートできます。スナップショットとロールバックは、積極的に試す際に低リスクにするために特に有用です。

まとめ：明確さと速度のための新しいループ

vibeコーディングワークフローでも設計書が消えるわけではなく、小さく、より具体的になり、実作業に近づきます。最初に書く一つの大きなドキュメントの代わりに、継続的に生産されるドキュメントが頼りになります：意図を述べるプロンプト、現実を暴く反復、そして結果を理解しやすく耐久性のあるものにするリファクタリングです。

設計書に替わるループ

プロンプトが意図を定義する。 良いプロンプトは実行可能な設計スペックのように振る舞います：制約、受け入れ基準、破ってはいけないルールを平易に記述します。

反復が真実を見つける。 小さなサイクル（生成 → 実行 → 検査 → 調整）が推測をフィードバックで置き換えます。不明点があれば議論するのではなく試し、測定し、プロンプトかコードを更新します。

リファクタがそれを固定化する。 解が機能したら、名前、境界、テスト、コメントで設計を読みやすくします。これが古いPDFより信頼できる長期的な参照になります。

文脈を失わないための軽量成果物

記憶喪失を防ぐため、いくつかのコンパクトで高信号な成果物を保ちます：

• 短いプロンプトテンプレート（ゴール、制約、エッジケース、完了の定義）
• PR説明のマイクロプラン（何が変わったか、次は何か）
• 受け入れ基準としてのテスト（実行可能）

チームへの次のステップ

一貫したプロンプト/PRテンプレートを導入し、加速する前にテストを強化し、変更をレビューに数分で済む大きさに保ちます。具体的な導入シーケンスが必要なら、/blog/a-practical-rollout-plan-for-your-team を参照してください。