仕様書を書く前にハーネスを作る - Agent Native開発は「探索を速く、判定を固く」

AIコーディングAgentに詳細仕様を渡せば、仕様どおりには作ってくれる。けれど、その仕様自体が間違っていたら、全工程が正しく失敗する。
このLTで扱うのは、詳細仕様を書き切る前に「間違いにすぐ気づける小さな検証環境＝ハーネス」を先に作る進め方。薄い仕様で目的・境界・確かめ方を固定し、動く候補を比べ、要求の穴や隠れた設計判断を見つけ、得た証拠を仕様へ戻す。Greenを正しさと取り違えないための見方や、この型をAgent Skillとして再利用する方法まで紹介する。

Transcript

1. 仕様書を書く前にハーネスを作る Agent Native開発は「探索を速く、判定を固く」 2026-07-28 Findy AI+ Meetup「Spec/Issue駆動知見を語り尽くす」 | Gota @gota_bara
2. Gota @gota_bara (X) AI Engineer / アナリティクスエンジニア ▸ 仕事: クラウド型コーディングAgentの開発 ▸ OSS: cc-sdd(仕様駆動開発) / SkillPort(Agent Skills管理) 開発者 ▸ 発信: zenn.dev/gotalab ▸ スプラトゥーン レイダース 裏ボスまでクリア
3. 仕様駆動でぶつかった3つの壁 Agentが仕様書どおりに作ったのに、欲しいものと違った。原因は仕様書側にあった 01 02 03 重い 腐る 邪魔になる 細部まで書き切るのは大変。 コードと乖離した瞬間に モデルが強くなるほど、 AIに書かせると長すぎて 負債になる。直すより 先に固定した細部が レビューが形骸化する 書き直す方が早くなる モデルの判断を縛る 間違っていたのは実装ではなく、人間が先に書き切った細部のほう
4. 詳細を書き込む前に検証環境を立てる Agentで生成コストが逆転した。動く候補を作る方が、詳細仕様を書き切るより安い 薄い仕様 目的・守る境界・確かめ方だけ 小さなハーネス 候補を比較できる検証環境 動く候補で探索 細部は証拠が出てから固定 要求の細部は最初に書くものではなく「発見する」対象になった
5. ハーネス = 間違いにすぐ気づける小さな検証環境 01 02 03 正しく立ち上がる環境 速く正直な検証ループ 観測できる実行結果 依存・接続・認証まで含めて 秒で回り、壊れていれば ログと出力で、候補の外から 一発で再現できる 必ず落ちる 判定できる この3つが揃って初めて、候補を並べて比べられる
6. 設計仮説は文書ではなく動く候補で比べる
7. 動かすと実装の穴より先に「要求の穴」が見つかる
8. 要求の一行に設計判断が4層隠れている 例:「途中で止めて、続きから再開できること」。長時間稼働Agentの回復性要件は、要求としてはこの一行で済んでしまう 会話・プロンプト messages ワークフロー状態 steps / queue / retry どの層まで戻す？ 誰が戻す？ ファイル・成果物 workspace / database 外部への副作用 API / deploy / notification どの層まで戻すかは、実際に止めて・戻してみて初めて決まる
9. Greenは正しさではない 外部接続が死んでいてもテストはGreenになれる。だから判定は生成側から分離して校正する 01 02 判定を生成から分ける 判定を校正する 判定基準は、候補側から書き換えられない わざと壊した例(known-bad)を流し、Redに 場所に置く(別Agent・CI) なることを確認する。接続を切っても Greenなら、そのテストは何も見ていない known-good PASS known-bad FAIL この2つを満たしたGreenだけを信じる。TDDの「まずRedを見る」の拡張
10. 仕様をやめたのではない。固定する順番を変えた 先に固定する 証拠が出てから固定する 動かして比べる 目的 要求の細部 守る境界 構成 成功の判定基準 データモデル 仕様書は薄くなったのではなく、証拠つきになった
11. この型はAgent Skillに固めてある .claude/skills/harness-design/SKILL.md Claude Code / Codex に読ませて使う --name: harness-design description: Design or repair the working setup that lets an agent discover mistakes quickly ... ▸ 再現できる環境と、秒で回る正直な検証ループを先に作 らせる --# Harness Design The harness means the working setup around the ▸ 非決定性を端に寄せるなど、検証しやすさから逆算した 設計指針を含む code: environment, checks, saved test data, project rules, and permission limits. Its job: find out quickly when the work is wrong. ▸ 新規プロジェクトや大きめの機能開発の初手が「仕様 書」から「ハーネス」に変わる
12. まとめ: 探索を速く、判定を固く 今日話したこと 明日からの初手 ▸ 仕様をやめたのではなく、固定する順番を変えた ▸ 次の機能開発は、詳細を書く前に検証環境を30分で立てる ▸ 要求の細部は、動く候補を比べて「発見」する ▸ Agentレビューやrubric評価にknown-bad(わざと壊した例)を流す ▸ 判定は生成から分け、壊してRedを見てから信じる ▸ 迷っている設計は、動く候補を2つ作って比べる 間違いを正直に発見できる環境を仕様書より先に作る