最近、Vibe Codingにおける様々なSDD開発手法を試しています。OpenSpec、SpecKit、oh-my-openagentのPrometheusなどです。

Andrej Karpathyは2025年2月にVibe Codingという概念を提唱しました——自然言語で意図を記述し、LLMにコードを生成させ、「Accept All」でdiffを確認せず、エラーが出たらそのままエラー情報をコピーしてAIに修正させる。

しかし、実際に始めてみると、致命的な問題を発見しました：AIが勝手に振る舞いすぎる。

特に既存プロジェクトの保守時、要件を与えると3つの異なる実装案を出してくる。それぞれ「妥当に見える」が、どれが本当に望んでいるものなのか？

Spec-Driven Development (SDD)とは

仕様駆動開発（Spec-Driven Development、SDD）、または「契約優先開発」（Contract-First Development）の核心は単純です：

先に仕様を定義し、その後AIに実行させる。

これは従来の「先にコードを書き、ドキュメントは足場」ではなく、仕様を唯一の真実の源泉（Single Source of Truth）として扱うことです。

GitHub Spec Kitは6段階のワークフローを提案しています：

• /constitution - プロジェクトレベルの原則を定義（品質標準、アーキテクチャ制約）
• /specify - 「何をするか」を記述、「どうやるか」には触れない
• /clarify - 曖昧性を排除、境界条件を識別
• /plan - 技術選定、アーキテクチャ決定
• /tasks - 実行可能な単位に分解
• /implement - 仕様に従ってコードを記述

このワークフローから気づきました：Vibe Codingの究極の目標はモデルの創造性を最大化することではなく、意図が100%理解され実装されることを確保することです。

Harness Engineering：モデルに手綱を付ける

Anthropicには古典的な比喻があります：

1
2

LLM =強力な馬、強大な力、しかし方向感がない、境界を理解しない
Harness =手綱 +鞍、力を導き、境界を設定、暴走を防止

Harness EngineeringはAI Agentインフラを設計、構築、運用する学問——本番環境でのAIを制約、誘導、検証、修正することです。

これはPrompt Engineeringとは根本的に異なります：

ある実例が印象に残りました：某金融会社のAgentが深夜3時に暴走し、失敗したAPIを11分間連続で再試行——合計847回の再試行、2200ドルのAPI費用を消費し、同一顧客に14通の重複メールを送信。

事後分析で判明：Modelは正常に動作し、Promptも慎重に設計されていましたが、問題はインフラレベル——3つの硬性制御が不足：再試行上限、実行タイムアウト、サーキットブレーカー。

この事件からHarnessの核心価値を真に理解しました：Promptに書く「10回以上再試行しないでください」は単なる提案——AIは無視でき、他の指示で上書き可能。しかしHarness層で強制実行される再試行上限は真のガバナンス——Agentは回避不可能、遵守必須です。

工学パラダイムが完全に変化した

対話型インタラクションから厳格な制約へ

過去、我々は：

• AIと対話型にやり取りを続けた
• より良いpromptを書いた
• より強力な単一モデルを使用（GPT-4 → GPT-4o → Claude Opus）

現在のHarness Engineering：

• 厳格な制約：何をするか、何をしないか
• 人間の意図理解：面接式質問、曖昧性排除
• 全プロセス制御：仕様 →計画 →実行 →検証
• 多Agent多モデル協調（oh-my-openagentプラグイン）：Sisyphus + Prometheus + Metis + Momus

核心コンポーネント

Harness Engineeringには5つの核心コンポーネントがあります：

1. Context Engineering - Agentが各ステップで見る情報を決定
2. Tool Orchestration -ツール選択、パラメータ検証、実行サンドボックス
3. Verification Loops - 各ステップで出力を検証（83% → 96%タスク完了率）
4. Cost Envelope Management - タスク単位の予算上限（中央値 × 3）
5. Observability -構造化実行追跡、因果関係記録

##私のHarness Engineering実践：DDD + gRPCプロジェクト

第1歩：gRPC入出力仕様を定義

DDDアーキテクチャのプロジェクトでは、先に人工でgRPCの入出力仕様を定義必須。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

service UserService {
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
}

message CreateUserRequest {
  string name = 1;      // 2-100文字
  string email = 2;     // 有効なメール形式必須
  string role = 3;      // "admin", "user", "guest"のみ許可
}

message CreateUserResponse {
  string user_id = 1;   // UUID形式
  int64 created_at = 2;
}

この .protoファイルは契約——AIはこの範囲を超えて勝手に振る舞えません。

第2歩：AIにプロジェクトを全量探索させる

プロジェクトにはrepo層に多くの再利用可能なリソースがある。AIにグローバル探索（読み取り専用）を行い、プロジェクト概要markdownを产出させる。

oh-my-openagentの /init-deepを使用、複数Agentを並行起動：

• 既存データモデルを検索
• repo層インターフェースを分析
• 再利用可能コンポーネントを抽出

第3歩：業務詳細markdownを記述

切记：大量の業務詳細を1つのドキュメントにまとめようとしない。

小粒度に分割：

1
2
3
4
5
6
7
8

specs/
├── 001-user-auth/
│   ├── spec.md         #ユーザーシナリオ、受入基準
│   ├── data-model.md   #データモデル定義
│   ├── contracts/      # API契約
│   └── tasks.md        #実行可能タスク
├── 002-payment-flow/
│   └── ...

原則：主Agentが各タスクで過多のコンテキストを占用しないようにする。コンテキスト圧縮しても、情報精度の損失です。

第4歩：調査段階——絶対に直接コードを書かせない

これが最も重要なステップ：AIに最初からコードを書かせないことを必ず伝える。

特にコンテキストが蓄積して長くなる時、モデルは幻覚を起こしやすく、勝手に実行を開始します。単一AIセッションのコンテキスト空間を利用し、先にAIに厳格な調査を行わせ、疑問を提起させ、共に以前に記述した仕様規範を完善します。

シミュレートされた対話シーン：

1
2
3
4
5
6
7
8

AI: 「プロジェクトにUserRepositoryが存在しますが、OAuthToken実体が不足しています。
     新テーブルを作成するか、既存のuser_tokensテーブルを再利用しますか？」
     
私: 「user_tokensテーブルを再利用、ただしproviderフィールドを追加必要。」

AI: 「providerフィールドにenum制約が必要ですか？サポートするproviderは何ですか？」

私: 「現在はgoogleとgithubのみサポート、enum制約を使用。」

上記の対話シーンは私がシミュレートした例です。このような反復的明確化は、直接AIにコードを書かせるより効果が遥かに高いです。

第5歩：調査終了後、OpenSpecまたはPrometheusでTasks/Plansを構築

私が常用する2つの方法：

OpenSpecの /opsx:propose：

1
2
3
4
5
6

/opsx:propose OAuth 2.0認証サポートを追加、xxx.mdを読んで調査し計画を策定、ただし計画を実行しない
#自動生成：
#   proposal.md - 意図、範囲、方案
#   specs/auth/spec.md - Delta Specs (ADDED/MODIFIED/REMOVED)
#   design.md - 技術アーキテクチャ決定
#   tasks.md -実装チェックリスト

oh-my-openagentの Prometheus：

1
2
3
4
5
6
7
8

xxx.mdを読んで調査し計画を策定、計画を実行しない
#面接式質問：
#   -先にどのエンドポイントを移行？
#   - RESTを保持または廃止？
#   - OAuth provider選択？
#   - TDDテスト駆動開発を使用？
# 
#計画生成 → Oracle調査 → Metis分析 → Momus検証

個人的には、omoプラグインの「面接式」、または「対話式」で多くの詳細を確認することを好みます。

第6歩：Plans/Tasks作成後、新セッションで実行

PlansまたはTasksのmarkdownファイルが作成された後、私は新AIセッションを作成し、専一的にこのタスクを実行させます。

omoの /start-work、またはOpenSpecの /opsx-apply xxxxを使用：

• 検証済み計画を読取
• 専門Agentに委任（コード生成、テスト、統合）
• 独立して結果を検証
• 主Agentが調整

余談：oh-my-openagentの多agent、多category方式は、OpenSpecのskillsを使用する時、正常に動作しないようです——現在の主モデルに実行させるだけです。

##総結：実践後の真実の感想

2ヶ月以上Harness Engineering方式でVibe Codingを行い、最大の感想はデータ改善ではなく、心境が変わったことです。

以前、AIでコードを書く時、各ステップで不安でした——理解を誤ったか？不要な機能を勝手に追加するか？簡単なことを複雑にするか？

現在、仕様制約があり、これらの問題は基本的に消失しました。より強力なモデルを使用したからではなく、AI実行前に意図を「固定」したからです。

いくつかの明確な変化：

手戻りが減少。以前、機能は平均3-4回の手戻りが必要。現在、大部分は1回で通過。AIが突然聪明になったではなく——仕様が「どうやるか」を事前に明確に定めたからです。

コスト低下。同タスクで、Token消費は約1/3削減。AIが反復試行、反復修正が必要なくなったからです。

モデル要求が低下。以前はClaude Opus必須と感じた。現在、完全な仕様とSonnetで、効果は同様です。

Vibe Codingの本质は「AIを聪明にする」ではなく、「AIに指示に従わせる」です。

指示に従う前提：先に明確に述べること。

これがHarness Engineeringの核心——モデルの強力な能力を発揮させることではなく、意図が正確に理解され、厳格に実行されることを確保することです。

このインフラを構築する确实に時間がかかり、2ヶ月以上探索を反復してようやく使い慣れました。しかし一旦構築すれば、AIコーディングは「推測ゲーム」から「図面施工」に変化——Vibe Codingの楽しみを真に享受でき、常に暴走を監視する必要がなくなります。

仕様駆動開発に興味がある場合、OpenCode での OpenSpec 体験を参照してください。AI agent モデル設定については、oh-my-opencode 最適化歷程を参照してください。