マクロな設計とミクロな設計との ギャップを埋める契約駆動開発

2026/07/28、【Coding Agentのハーネスについて考える– W&Bミートアップ #28】にて弊社社員がLT（ライトニングトーク）を発表いたしましたので、こちらに掲載いたします。

Transcript

1. Coding Agentのハーネスについて考える – W&Bミートアップ #28 マクロな設計とミクロな設計との ギャップを埋める契約駆動開発 Yuki Ogura | 燈株式会社 | 2026.07.28
2. 1. サマリー PRは量産できる時代、なのに一気通貫で動かすと壊れる ― 原因は設計の「繋ぎ目」 Ⓒ Akari Inc. l Confidential
3. 2. 背景 ― 契約駆動なしのAI並列開発 AI開発によってアウトプットは4倍超 ― だが手戻りによる再実装も一部存在 Ⓒ Akari Inc. l Confidential 成果 ― 量産はできた 48 → 300超え 年間max Contribution(1日あたりの最大値) 2023年 / SWE専任時代: max 48 現在 / Manager × AI並列: max 300 残った痛み ― 手戻りは消えなかった
4. 2. 背景 ― 契約駆動なしのAI並列開発 これまでの開発方法：人間は「判断」に直列、AIは「実装」で並列 Ⓒ Akari Inc. l Confidential Claude codeでタスクを明確にした上でSlackを通してDevinにタスクを振ること で、ユーザーはブランチのマネジメントコストを抑えて開発が⾏える タスク切り タスク振り・実装 フィードバック 動作確認 Devin 「タスク切り」、 「タスク振り‧実装」、 「フィードバック」のフェーズで ブランチを切り替えずに実装が可 能。 Github issue登録 Claude Code タスク振り Slack タスク内容生成 適宜 フィードバック 確認・ ブラッシュアップ 特に「フィードバック」時は Slackのスレッドをわけてそれぞ れのタスクの進捗を管理できるた め、誤操作による⼿戻りの削減が 可能。 ユーザー
5. 2. 背景 ― 契約駆動なしのAI並列開発 これまでの開発方法：人間は「判断」に直列、AIは「実装」で並列 Ⓒ Akari Inc. l Confidential Claude codeでタスクを明確にした上でSlackを通してDevinにタスクを振ること で、ユーザーはブランチのマネジメントコストを抑えて開発が⾏える タスク切り タスク振り・実装 フィードバック 動作確認 Devin 「タスク切り」、 「タスク振り‧実装」、 「フィードバック」のフェーズで ブランチを切り替えずに実装が可 能。 Github issue登録 Claude Code タスク振り Slack タスク内容生成 特に「フィードバック」時は 適宜 • ブランチの管理から解放 フィードバック Slackのスレッドをわけてそれぞ • レビューしやすい粒度でタスクをきるため、レ れのタスクの進捗を管理できるた ビューコストを削減 め、誤操作による⼿戻りの削減が 確認・ ブラッシュアップ 可能。 ユーザー
6. 2. 背景 ― 契約駆動なしのAI並列開発 残った課題は3つ ― テストが簡易的・実装が仕様とズレる・プランを評価できない。 発覚は常に「実装後」 ① ② ③ テストが簡易的 実装が仕様通りでない CRUDの疎通確認止まり。仕様に 沿っているかの検証になっていな い AIが解釈の余地を自分で埋め、 マージ直前にドリフト発覚 → 再実 装 要件(散文) AI並列実装 Ⓒ Akari Inc. l Confidential 人間レビュー プランをレビューできない 「作るファイル一覧」であって 「振る舞いの定義」ではない 仕様違反が発覚 ❌ 並列化の効果がここで吹き飛ぶ ・3つとも根本原因は同じ ― 仕様が「散文」のままAIに渡っている ・並列で3本回しても、1本差し戻せば人間の直列時間は倍かかる 再実装
7. 3. ミクロな設計とマクロな設計、そしてギャップ 設計、実装には2つの層 ― どちらを丁寧にやっても「一気通貫で動く」は保証されな い マクロな観点 ― 全体を俯瞰する層 フォルダ構成 / モジュール分割 / 依存関係の方向 / エージェントが探索しやすいコード配置 ? 繋ぎ目 ― 「最終的にどう繋ぐか」は、どちらの層でも設計されていない ミクロな観点 ― PR単位でロジックを詰める層 30〜200行の粒度 / 関数のロジック / リーダブルなコード / 単体テスト ミクロ ◎ × マクロ ◎ ≠ 一気通貫 ◎ 2層それぞれを磨いても、層の「間」は誰も設計していない Ⓒ Akari Inc. l Confidential
8. 3. ミクロな設計とマクロな設計、そしてギャップ ロバストなフォルダ構成とエージェントが確認しやすい構造 ― 全体俯瞰でしか守れない品質 Ⓒ Akari Inc. l Confidential
9. 3. ミクロな設計とマクロな設計、そしてギャップ 根本原因は人間レビューの位置 ―「実装後」の検証を「実装前」の契約確定へ前倒 し Ⓒ Akari Inc. l Confidential
10. 4. 提案ハーネス ― 契約駆動フロー TDDを「契約駆動開発」へ拡張 ― テストは目的ではなく、ミクロとマクロを繋ぐ最終チェック Ⓒ Akari Inc. l Confidential
11. 4. 提案ハーネス ― 契約駆動フロー Phase 1.5「認識合わせ」を挿入 ― 人間・Claude・Devin・CIの4層分業 Ⓒ Akari Inc. l Confidential
12. 4. 提案ハーネス ― 契約駆動フロー Phase 1.5「認識合わせ」を挿入 ― 人間・Claude・Devin・CIの4層分業 Ⓒ Akari Inc. l Confidential 上記フローは、 create-issues… コマンドから対応
13. 4. 提案ハーネス ― 契約駆動フロー /define-contract ― 散文の要件から、AIが契約と「解釈の分岐点」を出題 Ⓒ Akari Inc. l Confidential
14. 4. 提案ハーネス ― 契約駆動フロー 人間の入出力はHTML ― 頭を使うのは「ゴールデンケース1件」だけ Ⓒ Akari Inc. l Confidential
15. 4. 提案ハーネス ― 契約駆動フロー テストの主役は must_not ―「〜できる」ではなく「〜が起きたら事故」を書く Ⓒ Akari Inc. l Confidential 契約フォーマットの構成 cases ― 5種別を必須化 なぜ must_not が効くのか CRUD疎通テスト 本質的なテスト normal / boundary / error / permission / invariant 機能の存在証明で終わる ルールが破られないことの検証 大抵通る(落ちない) バグ発見率が高い 壊れても静かにデータが壊れる 事故の芽を先に落とせる must_not ― 重要 起きてはいけないことを列挙する invariants ドメイン全体へ昇格する不変条件 golden_cases 実データに近い入力と正解を1件 ・型・スキーマは OpenAPI が SSOT。契約は OpenAPI に書けない もの(条件・ケース・must_not・不変条件)だけを持つ 例: これがいちばんバグを見つける 「409で失敗したとき、DBにレコードが作られない」を検証する ・要件が「〜できる」で書かれているから、テストも存在証明で終わる
16. 4. 提案ハーネス ― 契約駆動フロー /generate-pr-plan ― PRは実装の論理で切り、契約は後から紐づける Ⓒ Akari Inc. l Confidential ✓ 理想PR粒度: 60-120行 (最小30 / 最大200) — レビュー容易性 を担保 ✓ Vertical Slice優先 ✓ ファイル・ディレクトリまで明記 1機能ごとに Backend → API → Frontend を一気通貫 Devinが迷わないための最大のキモ 各PRで必要な契約をテ スト項目として紐付け (関連するものがある場 合のみ)
17. 4. 提案ハーネス ― 契約駆動フロー /create-issues-from-pr-plan ― テスト設計がそのままDevinへの仕様書 Ⓒ Akari Inc. l Confidential Issueに入れる情報を絞る 契約全文 / プラン全文 Issue一括発行 → 並列稼働 plan.md 担当ケースだけに絞る Issue #1 Devin A Issue #2 Devin B Issue #3 Devin C Issue 並列で同時実装 Issueに載せる3つ ・担当ケースの全文 ・テスト設計(表) ・参考実装のパス ※ 契約全文は渡さない ― 情報過多は精度 を落とす Issue本文テンプレ 📋 概要 / 目的 🔗 別タスクとの依存関係 📁 作成・修正ファイル一覧 ✅ 完了条件チェックリスト 💡 実装詳細(参考コード)
18. 4. 提案ハーネス ― 契約駆動フロー `/test-guide` で動作確認手順を変更差分から自動生成し、人間のテスト負荷を削減 Ⓒ Akari Inc. l Confidential 1. checkout 2. /test-guide 3. 動作確認 git checkout <devin-branch> AIが変更差分を解析 手順を生成 優先順に最小手順で OK判定 → マージ 動作確認の優先順位ツリー (上位で確認できれば下位は不要) ✓ 「動かして、OK判断、マージ」だけに脳を使 1. Frontend UI えばよい ✓ テスト手順を考える認知負荷もAIに肩代わりさ 2. Backend API 3. アルゴリズム 4. Database せる ✓ PR1つずつ直列で判断 ― 高速にサイクルを回 せる
19. 5. 結果 実装後の差し戻しループが消え、並列化の効果が保たれる ― 初期コストは数回目の機能で逆転 Ⓒ Akari Inc. l Confidential Before After 人間: 要件整理・タスク切り 人間: 要件整理 + 契約確定(Phase 1.5) 人間の直列時間 AI: 並列実装 ×3 人間: レビューで1本差し戻し → 再実装 AI: 並列実装 + CIが契約照合 (差し戻しはDevin内) AIの並列時間 人間: UI確認 手戻り(再実装) ・定性的な実感: 実装後の「仕様と違う」差し戻しが減り、並列化の効果が保たれる ・CIの差し戻しは人間の目に触れずDevin内で完結する ― 人間の直列時間を消費しない ※ 帯の長さは定性的なイメージであり、実測値ではない
20. 6. まとめ ミクロとマクロの設計を、テスト駆動(契約)で繋ぐ ― 量産と手戻り削減の両立 Ⓒ Akari Inc. l Confidential ミクロな設計 マクロな設計 契約(テスト)で繋ぐ PR単位のロジック 小さなPRの丁寧なレビュー フォルダ構成と依存方向 エージェントが確認しやすい構造 2層それぞれを丁寧に ― そしてギャップは実装前の契約で埋める ① ② 仕様はデータで持つ in/out をスキーマ+具体例で 固定する ③ 判断は実装前に集約 読むのではなく、選ぶ 判定はCIに任せる テストがあるか、ではなく、 効いているか アウトプットを量産しつつ、手戻りを減らす ― これが次の「型」