Claude Codeから信頼できるアウトプットを得ている開発者と、エージェントが作ったものを元に戻すのに1日の半分を費やしている開発者の間には、広がるギャップがある。その差は才能でも経験でも、秘密のプロンプトエンジニアリングテクニックでもない。方法論の問題だ。AIエージェントでプロダクションソフトウェアを出荷している開発者たちは、それをそう呼ぶかどうかに関わらず、あるパターンに収束している:エージェントがコードを書き始める前に、何が欲しいかを定義する。
この記事はそのパターンに名前を付ける。Spec-first開発はAI支援ソフトウェアエンジニアリングのための方法論だ。曖昧な「ベストプラクティス」ではない。定義されたフェーズ、明確なチェックポイント、各ステップでの具体的な成果物を持つ、構造化された再現可能なライフサイクルだ。Claude Codeのアウトプットをリリーススケジュールを賭けられるほど予測可能にする方法を探していたなら、これがそのフレームワークだ。
Vibe Codingの天井
「Vibe coding」は2025年初頭に語彙に入った。売り文句:自然言語で欲しいものを記述し、AIに書かせ、正しく見えるまでイテレーションする。プロトタイプ、週末プロジェクト、ワンオフスクリプトにはvibe codingは有効だ。素早く機能するものが手に入り、後で壊れてもリスクは低い。
プロダクションソフトウェアは異なる制約下で動作する。コードは既存のコードベースに統合され、特定の要件を満たし、それをメンテナンスする他の人々との接触を生き延びなければならない。Vibe codingがこれらの制約に出会うと、失敗モードは予測可能だ。
最初の失敗はドリフトだ。機能を曖昧に記述し、エージェントがその解釈を実装し、調整し、エージェントが調整された解釈を再実装する。3回のイテレーション後、各イテレーションがターゲットをシフトしたため、元の要件を一つも満たさない動作するコードができている。エージェントがあなたの欲しいと思うものに収束しているのであって、実際に必要なものにではない。
2番目の失敗は不可視の意思決定だ。記述の各ギャップは、エージェントが黙って下す意思決定だ。データベーススキーマ、エラーハンドリング戦略、APIの形状、バリデーションルール、ライブラリの選択。これらの意思決定をコードレビュー中に、あるいはもっと悪いことに本番で発見する。エージェントは悪い決定を下したのではない。指示されていない決定を下したのであり、それらが実装に組み込まれる前にキャッチするメカニズムがなかった。
3番目の失敗はレビュー麻痺だ。エージェントがアーキテクチャ、データモデル、エラーコード、エッジケース処理を選択した600行のdiffは、従来の意味でレビュー可能ではない。specに対してコードをレビューしているのではない。コードからspecを再構築し、それに同意するかどうかを判断している。これはspecを書くよりも時間がかかる。
Vibe codingが天井に達するのは、2つの異なる活動を混同するからだ:何を構築するかを決めることと、それを構築すること。Spec-first開発はそれらを分離する。
方法論としてのSpec-First
Spec-first開発は4フェーズのライフサイクルだ。各フェーズは具体的な成果物を生成する。各遷移には明確なゲート条件がある。この方法論はどのAIコーディングエージェントでも機能するが、この記事の例はClaude Codeを使用する。コミュニティが最も速くイテレーションしている場所だからだ。
フェーズ1:ブレインストーム
あなたとエージェント(またはあなただけ)が問題空間を探索する。制約は何か？どんなアプローチが存在するか？トレードオフは何か？これは会話的だ。何にもコミットしていない。領域をマッピングしている。
ゲート条件:望ましいアプローチがあり、なぜ代替案ではなくこのアプローチかを説明できる。
Claude Codeとのブレインストーミングは、エージェントがパターンとライブラリの幅広い知識を持っているため価値がある。間違いはブレインストームから直接コードに飛ぶことだ。ブレインストームはオプションを表面化する。それらの間で選択はしない。それはあなたがする。
フェーズ2:Spec
決定を書き下す。これはエージェントが実装する契約だ。specはユーザーストーリーではなく、Jiraチケットではなく、散文の段落ではない。以下を含む構造化されたドキュメントだ:
- 問題の記述:何が壊れているか欠けているか、具体的な用語で
- 提案するアプローチ:ブレインストームフェーズから選択された解決策
- 影響するファイル:エージェントがどのファイルに触れるべきか(暗黙的に、どれに触れるべきでないか)
- 受け入れ基準:「完了」を定義するテスト可能な条件
- スコープ外:エージェントが明示的に避けるべきこと
受け入れ基準が最も重要な要素だ。各基準は観察可能な結果を伴う具体的なアクションでなければならない。「認証が機能するべき」は基準ではない。「有効な認証情報を送信すると200とセッショントークンが返る。無効な認証情報を送信すると401でトークンなしが返る」が基準だ。
スコープ外セクションはゴールドプレーティングを防ぐ。これがないと、エージェントは隣接するコードを「改善」したり、乱雑に見えたファイルをリファクタリングしたり、関連しそうな機能を追加したりする。エージェントが要求されていない作業に費やす毎分は、あなたが要求されていない作業をレビューする毎分だ。
ゲート条件:ブレインストームにいなかった人がこのspecを読んで正しいものを構築できる。
フェーズ3:実装
エージェントはspecに対して実行する。会話に対してではない。議論した記憶に対してではない。テスト可能な基準を持つ具体的なドキュメントに対してだ。
コードを書く前に、エージェントはプランを作成する:行う予定の変更のナンバーリスト、どのファイルを修正するか、結果をどう検証するか。このプランは2分のチェックポイントだ。読んで、意図と一致することを確認し、実装にゴーサインを出す。または誤解をキャッチして修正する。どちらにしても、20分ではなく2分を投資した。
plan-before-codeパターンは官僚主義ではない。ワークフロー全体で最もレバレッジの高い単一の介入だ。実装ミスのほとんどはコーディングエラーではない。理解エラーだ:エージェントがspecを誤解した。プランで理解エラーをキャッチするコストは2分。400行のdiffでキャッチするコストは20分。本番でキャッチするコストは1日。
ゲート条件:エージェントが何を構築し、どう検証したかについて具体的な主張を含む完了レポートを投稿した。
フェーズ4:検証
あなたまたはQAプロセスが、実装をspecに対して確認する。「正しそうに見えるか？」ではなく「各受け入れ基準を満たしているか？」
検証は機械的だ。specから各基準を取り、テストを実行し(コマンドを実行、ブラウザを開く、イベントをトリガー)、結果を記録する:パスまたはフェイル。フェイルした基準はフェーズ3に戻る。検証は実装と並んで文書化されるため、6ヶ月後にタスクを読む誰もが何がテストされたかを正確に確認できる。
ゲート条件:すべての受け入れ基準に記録されたパス/フェイル結果がある。
これが完全なライフサイクルだ。4フェーズ、4つの成果物(アプローチの根拠、spec、実装プラン、検証記録)、4つのゲート条件。フェーズは逐次的だが軽量だ。中規模の機能では、フェーズ1と2に15-20分。フェーズ3は実装にかかる時間。フェーズ4に5-10分。
なぜエージェントでは人間より重要なのか
specを書くためのあらゆる議論はAI以前からある。「コードの前に要件を書け」は我々のほとんどが生まれる前からのアドバイスだ。ではなぜこれをAI支援開発に特有のものとしてフレーミングするのか？
エージェントがコスト関数を変えるからだ。
曖昧な要件を受け取った人間の開発者は立ち止まって質問する。「パスワード認証のこと？SSO？」「モバイルで動く必要がある？」「トークンが期限切れになったらどうなる？」各質問は実装を正しいターゲットに向ける小さなチェックポイントだ。人間の開発者に対する曖昧なspecのコストは数本のSlackスレッドとせいぜい午後のリワークだ。
曖昧な要件を受け取ったエージェントは立ち止まらない。あらゆる曖昧な決定を黙って下し、アプローチにコミットし、完成した実装を提示する。エージェントに対する曖昧なspecのコストは、完全に間違っているかもしれない完成した実装、それが間違っていると発見する時間、やり直す時間だ。
非対称性は鮮明だ。エージェントは人間の開発者より実行は速いが判断力は劣る。specの各曖昧さは判断の呼びかけであり、エージェントがガイダンスなしに下す各判断はは、結果が意図と一致するかどうかのコイントスだ。specはコイントスを排除する。
2つ目の、より微妙な理由がある。エージェントは反論しない。悪いspecを受け取ったシニアエンジニアは「Xのせいでこれは意味をなさない」と言う。エージェントは悪いspecを忠実に実装し、忠実に間違ったアウトプットを生成する。Spec-first開発は、質問なしに実行するエンティティに渡す前に、自分自身の思考を検証することを強制する。specはエージェントのためだけではない。あなた自身のためだ。
Beadbox はこの問題を解決します。
エージェントフリート全体が今何をしているか、リアルタイムで把握できます。
ベータ期間中は無料でお試し →
Plan-before-codeチェックポイント
この記事から一つのプラクティスだけ取って残りを無視するなら、これを取れ。
エージェントがコードを書く前に、実装プランの投稿を要求せよ。コードではない。diffではない。何をするつもりかの構造化されたアウトラインだ。
プランはこのようなものだ:実行順のナンバーステップ、修正するファイル、各ファイルのロジック変更、検証アプローチ。エージェントはこれを約30秒で作成する。あなたは約2分で読む。その2分で以下をキャッチできる:
- スコープ違反:エージェントがspecにリストされていないファイルの修正を計画している
- アーキテクチャの不一致:エージェントが既存のパターンと矛盾するアプローチを選択した
- 欠落ステップ:プランが受け入れ基準に対応していない
- オーバーエンジニアリング:エージェントが正当化されない抽象化の構築を計画している
2分のプランレビューは、これらの問題がすでに構築された後に発見する20分のdiffレビューに取って代わる。ソフトウェアエンジニアリングで最も安価なクオリティゲートだ。
plan-before-codeパターンの詳細なウォークスルーをClaude Codeによるスペック駆動開発に書いた。specテンプレートと完了レポートフォーマットを含む。この記事はパターンがなぜ機能するかに焦点を当て、あちらはどのように実装するかに焦点を当てている。
ファーストクラスのステップとしての検証
ほとんどの開発者のワークフローで最も投資不足のフェーズは検証だ。エージェントが「完了」と言う。開発者がdiffをざっと見る。マージが行われる。ユーザーが受け入れ基準のエッジケース3番に当たった2日後にバグが浮上する。
Spec-first開発は検証を独自の成果物を持つ正式なステップとして扱う。完了レポートは各受け入れ基準を具体的なチェックにマッピングする:
- 基準:「ワークスペースの切り替えで保存されたフィルター状態が復元される。」
- チェック:アプリを開き、ワークスペースAでフィルターを設定し、ワークスペースBに切り替え、ワークスペースAに戻り、フィルターが復元されていることを確認する。
- 結果:パス。
これはオーバーヘッドではない。実装が実際にspecを満たしているかどうかを判断するステップだ。これがなければ、specはウィッシュリストであり受け入れ基準は願望的だ。
検証記録は下流の問題も解決する:コードレビュー。レビュアーがプルリクエストを開くとき、specを読み、検証記録を読み、完全なコンテキストでdiffをレビューする。レビュアーは調査を行うのではなく検証済みの主張を確認しているため、レビュー時間は短縮される。
複数のエージェントを並行して実行し、それぞれが異なるspecを実装しているとき、検証の規律は制御されたパイプラインと「おそらく動く」コードの山の違いだ。各specには基準がある。各実装には完了レポートがある。各完了レポートは基準をチェックにマッピングする。記録された検証なしには何も出荷されない。
異論と正直なトレードオフ
Spec-first開発は無料ではない。異論は現実的であり、正面から対処する価値がある。
「specを書くと遅くなる。」 単独では、はい。機能のspecを書くのに15-20分かかる。しかし実装とレビューフェーズでその時間(以上)を回収する。明確なspecを持つエージェントは曖昧なプロンプトのエージェントより頻繁に正しい実装を生成する。イテレーション減、リワーク減、レビュー短縮。実質のある機能への純効果は、遅い配信ではなく速い配信だ。
些細な変更(変数のリネーム、タイポの修正、バージョンのバンプ)には、specは不要なオーバーヘッドだ。Spec-firstは実装が判断を必要とする作業のためにある。変更が機械的で曖昧でなければ、specをスキップせよ。
「私のエージェントはspecなしで十分優秀だ。」 一部のタスクではおそらく正しい。Claude Codeは簡潔な記述から意図を推測する能力が非常に高い。問題はエージェントが曖昧な指示から良いアウトプットを生成できるかどうかではない。確実にそうするかどうかだ。時折のリワークと予測不可能なレビュー時間に満足しているなら、vibe codingはあなたのユースケースに十分かもしれない。Spec-firstは一貫性と予測可能性が重要なときに効果を発揮する:機能が複雑なとき、コードが本番に行くとき、他の誰かがメンテナンスするとき。
「specは陳腐化する。」 妥当な懸念だ。ブレインストーム中に書かれたspecは現実との接触を生き延びないかもしれない。修正策はspecをスキップすることではない。プランが新しい情報を明らかにしたときにspecを更新することだ。エージェントのプランがspecのアプローチが機能しないことを示したら、進める前にspecを修正せよ。specは実装の期間中は生きたドキュメントだ。検証後に歴史的記録になる。
「これはただのウォーターフォールだ。」 いいえ。ウォーターフォールの失敗は、長いフィードバックサイクルの大きなプロジェクトに対する大きなspecだった。Spec-first開発はタスクレベルで動作する:機能やフィックスごとに1つのspec、15-20分で書かれ、数時間で実装され、同じ日に検証される。フィードバックループはタイトだ。spec当たりの投資は小さい。specが間違っていれば、6ヶ月後ではなくプランレビュー中に判明する。
Spec-Firstライフサイクルのツーリング
この方法論はどのタスクシステムでも機能する:GitHub Issues、Linear、Notion、プレーンテキストファイル。重要なのは、spec、プラン、実装ノート、検証結果がすべて一箇所に、一つのタスクに紐づいて存在することだ。
このワークフロー向けに設計されたシステムを探しているなら、beadsはオープンソースのGitネイティブissue trackerで、完全なライフサイクルを保持する。各「bead」はdescription(あなたのspec)、コメントスレッド(プランと完了レポート)、ステータス(open、in_progress、ready_for_qa、done)、依存関係や優先度などのメタデータを持つ。bd CLIはターミナルから操作するため、エージェントは作業環境を離れることなくspecを読み、プランを投稿し、完了を報告できる。
bd create --title "Persist filter state across workspaces" \
--description "## Problem ..." --type feature --priority p2
bd update bb-a1b2 --claim --actor eng1
bd comments add bb-a1b2 --author eng1 "PLAN: ..."
# After implementation:
bd comments add bb-a1b2 --author eng1 "DONE: ... Commit: a1b2c3d"
bd update bb-a1b2 --status ready_for_qa
ライフサイクル全体がCLIで行われる。6ヶ月後、bd show bb-a1b2は何が仕様化され、計画され、構築され、検証されたかの完全な履歴を返す。
1つのエージェントをこのライフサイクルで実行するなら、CLIで十分だ。5つや10を並行して、各々がspec-implement-verifyパイプラインの異なるステージにいるとき、パイプラインの状態を一目で把握する必要がある。Beadboxはリアルタイムダッシュボードで、どのspecがオープンか、どのプランがレビュー待ちか、何が進行中か、何がブロックされているか、何が検証準備完了かを表示する。エージェントが書き込む同じbeadsデータベースを監視し、ステータスが変わるとライブで更新される。
Spec-first開発を実践するのにBeadboxは必要ない。方法論はツールに依存しない。しかし並行ワークストリームがパイプラインを記憶だけでは追跡できないタスクのキューに変えるとき、ビジュアルレイヤーはレビュー、アンブロック、出荷の速度を変える。
より広い変化
Spec-first開発はAIコーディングエージェントが悪いことへの反応ではない。ガイダンスなしには間違ったことに優れているという認識だ。エージェントは非常に有能な実行者だ。正しい構文を書き、パターンに従い、ボイラープレートを処理し、人間が匹敵できないボリュームを生成する。欠けているのは、何を構築するかについて良い判断を下すコンテキストだ。そのコンテキストはあなたから来る。specがその媒体だ。
AI支援エンジニアリングで成功する開発者は、最良のプロンプトを書く人ではない。最良のspecを書く人だ。プロンプトは一時的だ。Specは持続する。プロンプトは単一のインタラクションに最適化する。Specはライフサイクルに最適化する:ブレインストーム、定義、実装、検証。
これはエージェントが賢くなるまでの一時的な回避策ではない。モデルが改善されても、根本的な非対称性は残る:人間はビジネスが何を必要としているかを知り、エージェントはコードの書き方を知っている。Specは両者を橋渡しする。より良いモデルはspecをより速く実行するが、spec自体の必要性は消えない。スケールするほど重要になる。より多くのエージェントが曖昧な指示に対して実行すると、より発散したアウトプットを生成するからだ。
Claude Codeエージェントを実行して結果が一貫しない、レビューに時間がかかりすぎる、並行ワークストリームの調整に苦労しているなら、これを試せ:次の機能の前に、テスト可能な受け入れ基準を持つspecを書くのに15分かけ、エージェントにコーディング前のプラン投稿を要求し、アウトプットを基準ごとに検証する。1サイクルで違いがわかる。
このようなワークフローを構築しているなら、BeadboxにGitHubでスターを。
Like what you read?
Beadbox is a real-time dashboard for AI agent coordination. Free during the beta.
