Uploaded via Gist Uploader - 2026-05-21T07:06:18.664Z

README.md

AIエージェント駆動開発（dev-loop & ハーネスエンジニアリング）一問一答

Q1. AIエージェント運用における「dev-loop（開発ループ）」とは具体的に何を指しますか？

A1.
ここでの「dev-loop」とは、単にコードを書いて手動でテストする従来の内輪のループではなく、**「AIコーディングエージェントが人間の最小限の監督下で、自律的かつ連続的にタスクを遂行し続けるための外部運用プロセス全体」**を指します。

具体的には、以下の4つの要素で構成されるサイクルです。

1. タスクの構造化された受け渡し: プロンプトだけでなく、ファイルやGitを介したコンテキスト管理。
2. タスクの完了判定: テストやLinterなどの機械的な検証を用いた厳格な完了定義（DoD）。
3. 自己修正ループ: エラー発生時に自律的に修正を試みる機構。
4. 知見の収集・蓄積: 失敗や意思決定を記録し、次のタスク実行時に同じミスを繰り返さないための仕組み。

新規プロジェクトの立ち上げ時に、CI（継続的インテグレーション）を組むのが当たり前になったように、現在ではこの「エージェント向けのdev-loop基盤」をはじめから組み込む動きが広がりつつあります。ただし、最初から豪華すぎるテンプレートや運用基盤を導入すると、開発の機動力を損なう（オーバーエンジニアリングになる）懸念もあります。

---

Q2. 「ハーネスエンジニアリング」と「dev-loop」にはどのような関係や違いがありますか？

A2.
両者は「AIモデルの外側を制御・補強する」という目的において地続きですが、「静的な基盤設計」か「動的な運用プロセス」かという点で役割が異なります。

• 外部ハーネス / ハーネスエンジニアリング（静的・基盤）
  • 定義: AIエージェントの能力を最大限に引き出し、かつ安全に動作させるための「モデル以外の周辺インフラ全体」を設計・構築する活動（Agent = Model + Harness）。
  • 具体例: AGENTS.mdやCLAUDE.mdなどのルールファイルの設置、実行環境のサンドボックス化、ツールの実行権限管理、CIでの静的解析。
• dev-loop（動的・運用）
  • 定義: 整備されたハーネスの上で、日々のタスクをどのように流し、エージェントをどう回すかという「実践的な運用プロセス」。
  • 具体例: handoff.md（セッション間状態管理）を用いたタスクの受け渡し、lessons.md（失敗ログ）の自動適用、成果物の最終検証（Verify）の実行方法。

結論として：
ハーネスエンジニアリングは「土台（線路）を作る活動」であり、dev-loopはその上で「安全かつ高速に列車（タスク）を走らせ、知見を持ち帰るための運行規則」にあたります。

---

Q3. /grill-me や「SDD（仕様駆動開発）」などのアプローチと、今回の「dev-loop」はどう異なりますか？

A3.
それぞれ開発プロセスの異なるフェーズを対象としており、相互に補完関係にあります。

• /grill-me（計画前処理ツール）
  • 役割: 開発開始前にエージェントが人間に執拗な質問（インタビュー）を行い、曖昧な要件を深掘りして共通理解を作るための手法。
  • dev-loopとの違い: /grill-meは「設計開始時の単発の対話」に特化しています。dev-loopは、その決定事項をベースに「実際のコーディングと検証を繰り返し回すプロセス全体」をカバーします。
• SDD（Spec-Driven Development：仕様駆動開発）
  • 役割: 実装前に詳細な仕様書（Spec）を定義し、エージェントに「仕様書通りに書くこと」を強制するドキュメント駆動の手法。
  • dev-loopとの違い: SDDは「入力する情報の質（仕様）」を重視します。一方、dev-loopは仕様の有無に関わらず、「タスクの引き継ぎ、テストでの判定、失敗時の修正追跡、知見蓄積」といった運用そのものの仕組みに焦点を当てています。

---

Q4. 人間向けの「スクラム開発」と、エージェント向けの「dev-loop」の決定的な違いは何ですか？

A4.
どちらも「短い反復（イテレーション）で検証を繰り返し、成果を積み上げる」という思想は共通していますが、「失敗への対処」と「記憶・再現性」の扱い方に決定的な違いがあります。

比較軸	人間向けスクラム	AI向けdev-loop（ハーネス）
失敗へのアプローチ	振り返り（レトロスペクティブ）を通じて人間が意識や習慣を改善する（属人化・忘却のリスクがある）。	失敗パターンを lessons.md に即時記録し、次回からプロンプトやルールとして機械的に強制・自動インポートする。
意思決定の整合性	朝会やミーティングなどの対話を通じて、メンバー間でコンセンサスを維持する。	decisions.md（決定ログ）を毎回エージェントに読み込ませ、同じ設計論争の繰り返し（迷い）を防止する。
品質・速度の制御	メンバーのモチベーションや疲労に依存し、コントロールが難しい。	プロンプト内の指示（努力レベル）や検証の厳しさのノブを切り替えることで、動的にコントロールできる。
タスクの粒度	数日〜スプリント単位（数日〜数週間規模）。	15〜60分程度の極めて小さな粒度（AIの文脈散漫を防ぐため）。

人間は「忘れやすいが自律的に修正できる」のに対し、AIは「指示に従うがセッションごとに状態がリセットされ、同じミスを繰り返しやすい」という特性があります。そのため、dev-loopでは、対話による合意ではなく**「ファイルやシステムによる機械的な制約とフィードバック」**を最重視します。

---

Q5. エージェントが不完全（生焼け）な状態で完了報告をするのを防ぎ、精度と速度をコントロールする手法はありますか？

A5.
エージェントは楽観的に「できました」と報告しがちです。これを防ぐには、**「判定基準（DoD: Definition of Done）の客観化」と「努力レベル（品質・速度）の動的な調整」**の2つを仕組み化します。

1. 機械的なDoD（完了定義）とPEVループの適用

エージェントの主観に任せず、以下のPEV（Plan-Execute-Verify）ループをハーネス側で強制します。

• Plan（計画）: タスク開始時に必要なチェックリスト（機能要件、テスト、型チェック、エラーハンドリング等）を自動提示させる。
• Execute（実行）: 実装を行う。
• Verify（検証）: エージェント自身または外部スクリプトが、実際にLinterやテスト（Vitest, Pytest等）を実行し、その結果の「パス」のみを完了の証拠とする。

2. 品質・速度をコントロールする「努力レベルノブ」の設計

プロンプトの指示強度やコンテキストの制限によって、実行モードを意図的に切り替えます。

• 「スピード優先」モード: タスク粒度を大きめにとり、検証は最小限のハッピーパス（正常系）の確認のみ。コンテキストには最小限の handoff.md のみを渡す。
• 「最高品質」モード: タスクを極限まで小さく分解し、テスト、静的解析、セキュリティチェックを必須条件にする。過去の失敗ログ（lessons.md）とアーキテクチャ定義（AGENTS.md）をすべてコンテキストに注入し、エッジケースの考慮を徹底させる。

---

Q6. この文脈における「CI（継続的インテグレーション）」の役割はどう変わりますか？

A6.
従来のCI（人間が書いたコードの検証）と異なり、エージェント駆動開発におけるCIは、**「エージェントの嘘や見落としを完全に遮断し、自動修正を促すための『最終防御壁（Quality Gate）』」**として機能します。

1. 客観的な最終検証: エージェントがローカル環境（dev-loop）で「テストが通った」と誤認・虚偽報告した場合でも、クリーンなCI環境で強制的に再検証を行い、生焼けのコードが本番環境（あるいは人間がレビューするPR）に混入するのを物理的に防ぎます。
2. 自動修正ループ（Self-Healing）の起点: CIがテストや静的解析で落ちた場合、そのエラーログを自動的にエージェントに再投入（フィードバック）し、人間が介入することなく「CIが通るまでエージェント自身に自動で再修正・コミットさせる」という、外側の自動ループを形成します。
3. ハーネス（ルール）の強制: AGENTS.md に書かれた「依存レイヤーの規則」や「セキュリティルール」が本当に守られているかを、静的解析や自動脆弱性スキャンによってCI上で厳密に検査・強制執行します。

---

Q7. この文脈における「ITS（チケットシステム）」はどのように機能しますか？

A7.
エージェント駆動開発におけるITS（Jira、GitHub Issues、Linearなど）は、単なる進捗管理のカンバンではなく、**「AIエージェントに対する『タスク供給・配分キュー』であり、人間とAIが非同期で協調するための『コントロールパネル（制御盤）』」**へと進化します。

1. 仕様のダイレクトな入力（構造化プロンプト）: 人間が起票するチケットの「受け入れ条件」が、そのままエージェントのローカルな完了定義（DoD）にマッピングされます。そのため、チケットはエージェントが直接実行可能な仕様書として厳密に構造化して書かれます。
2. 進捗と状態の自動同期: エージェントがチケットを検知すると、ステータスを自動で In Progress に変更し、作業ブランチを作成してdev-loopを起動します。PRが作成されれば In Review になり、CIが落ちれば Blocked になるといった、ステータス遷移がAPIを介して完全に自動化されます。
3. エージェント間の協調（マルチエージェント）: 司令塔となるエージェント（Coordinator）が大きなタスクを分解し、ITS上に子チケットを自律的に起票。それを複数の実装用エージェント（Worker）が自分のキューとして並列で取得して処理する、という自律的なタスク管理が実現します。
4. Human-in-the-Loop（人間の介入）の接点: エージェントが仕様の矛盾などで立ち止まった際、ITSのチケット上に「質問」をコメントし、人間からの回答（追加コンテキスト）があるまで待機する、という協調プロセスのハブになります。

---

Q8. この文脈における「ドキュメント」はどのような存在ですか？

A8.
従来の「人間向けの読み物」から、**「AIエージェントの思考と行動を制限し、その学習成果を永続化するための、コードと並ぶ『第一級システム構成要素（First-class Artifact）』」**へと定義が変わります。読者も書き手も「エージェント」が主役となります。

ドキュメントは、その役割に応じて以下の3つに整理され、すべてGitリポジトリ内でコードと同じく一元管理（Docs-as-Code）されます。

1. 静的ガードレール（Feedforward：事前制約）:
   • AGENTS.md / ARCHITECTURE.md など。エージェントがプロジェクトのルール、使用技術、ディレクトリ構成ルールを破らないよう、起動時に強制的にコンテキストに注入される「憲法」です。
2. 動的な状態管理（Context：現在地の同期）:
   • tasks.md / handoff.md など。セッションが変わるエージェントに対して、「現在どのタスクを、何の前提知識に基づいて進めているか」を引き継ぎ、余計なトークン消費を抑えながらタスクをバトンタッチするためのドキュメントです。
3. 自己学習と記憶（Feedback：知見蓄積）:
   • lessons.md（失敗ログ） / decisions.md（決定ログ）など。エージェントがdev-loopの中で「ビルドエラーになった原因」や「採用した設計方針の理由」を自動的に追記し、セッションをまたいで同じミスや不毛な設計論争を繰り返さないための「外部記憶装置」です。エージェントによって常に自動更新され、陳腐化しません。

---

Q9. 「PRをガチャとして回し、多くの試作品を作り捨てる（使い捨てる）」という運用は、どのような合理性に基づいているのでしょうか？

A9.
このアプローチは、AIエージェントの**「コード生成コスト（限界費用）がほぼゼロである」**という経済的強みと、LLMの持つ非決定性を利用した、きわめて合理的なサンプリング戦略です。

• 人間のサンクコストバイアスの排除: 人間が書く場合、一度書いたコード（試作品）を捨てるのは時間的・精神的コストが大きすぎます。しかし、エージェントにとってコードは「書いては捨てるもの」です。「大量に作り、より良い方だけを残して容赦なく捨てる」運用によって、人間特有の「不適切なアプローチに固執して手戻りが発生する」リスクを完全にゼロにできます。
• Pass@k（サンプリング確率）の最大化: 1発で100点満点の完璧なPRを作らせようとする（Pass@1）よりも、並列で異なるアプローチの試作品を複数作らせ、最も優れた1本のみを採用して残り（ハズレPR）を捨てる（Pass@k）方が、最終的なマージクオリティは圧倒的に高くなります。
• 破棄プロセス自体による記憶（Retro）の進化: 不採用になり、破棄されたハズレPRの失敗パターン（例：「この書き方はCIでテストエラーになった」）は、そのまま lessons.md に蓄積されます。捨てる行為自体が「次回以降のガチャの当たり確率を上げるためのデータ」になります。

---

Q10. ガチャの入力に「Jitter（ゆらぎ・分散）」を与えるとは、具体的にどのような仕組みですか？また、どう「当たり」を選択するのですか？

A10.
ただ同一プロンプトで乱数を変えて実行するのではなく、**「解決に向けた仮説（方針）そのものを意図的に複数にばらつかせて、並列実行させる仕組み」**です。

1. Jitter（入力の分散）の実装方法

• 仮説の分散: ひとつの課題に対して、Coordinator（または人間）が異なる解決方針を与えます。
  • Jitter A: 「既存コードを徹底的に共通化・リファクタリングして解決するアプローチ」
  • Jitter B: 「実績のある外部ライブラリを新たに導入して簡潔に解決するアプローチ」
  • Jitter C: 「最も記述がシンプルで、既存部分を破壊しないワークアラウンド」
• モデルパラメーターのゆらぎ: モデルの温度（Temperature）や、プロンプトの記述スタイル（「厳格さ」重視 vs 「独創性」重視）を意図的に少しずつ変化させて、生成されるコードの記述パターンを分散させます。

2. 当たりPRの選択フィルター（淘汰システム）

多様なJitterから生まれた試作品群は、以下の多層フィルターを通じて「ベストの1本」へと絞り込まれます。

1. 第1層：CIによる自動スクリーニング: コンパイル、静的解析、単体テストをパスしない「ハズレPR」を機械的に脱落させます。
2. 第2層：評価エージェント（Evaluator）による比較: CIを通った複数の生き残りPRに対し、第3のエージェント（Evaluator）が、コードのシンプルさ（LOCの少なさ）、計算複雑度、読みやすさ（可読性）などの観点から採点・比較を行い、ベストな1本を推薦します。
3. 第3層：人間によるマージ: 人間は、評価エージェントが選んだ「最も品質が高いPR」のみを目視確認し、マージを実行します。

これにより、完璧な計画（静的思考）を立てて一歩も間違えずに歩くよりも、**「分散した仮説（Jitter）を大量に走らせ、テスト環境に適応できなかったものを淘汰し、適応した最も優秀なPRだけを記憶に固定する」**という、AI時代に最も最適化された進化論的開発プロセスが成立します。

続き

---

AIエージェント駆動開発（Evolutionary Dev-Loop）の概念体系図

┌────────────────────────────────────────────────────────────────────────┐
│                        【 人間（メタ・設計者） 】                      │
│   ・DoD（完了定義）の設計   ・Jitter（仮説）の定義   ・最終マージ判断   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ (Jitterの注入)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             【 運行レイヤー：Jittered Parallel Execution 】            │
│  ※限界費用ゼロを活かし、多様なアプローチ（Jitter）のPRを並列で生成・実行  │
│                                                                        │
│   ┌───────────────┐        ┌───────────────┐        ┌───────────────┐  │
│   │ 仮説A (Worker)│        │ 仮説B (Worker)│        │ 仮説C (Worker)│  │
│   └───────┬───────┘        └───────┬───────┘        └───────┬───────┘  │
└───────────┼────────────────────────┼────────────────────────┼──────────┘
            │                        │                        │
            ▼                        ▼                        ▼
┌────────────────────────────────────────────────────────────────────────┐
│              【 淘汰レイヤー：Multi-layered Quality Gate 】            │
│                                                                        │
│   [第1フィルター：CI] ──> テスト・静的解析による機械的足切り            │
│            │                                                           │
│            ▼                                                           │
│   [第2フィルター：Evaluator] ──> エージェントによる可読性・複雑度の静的比較   │
│            │                                                           │
│            ▼                                                           │
│   [第3フィルター：Human] ──> 人間による目視確認と最終マージ             │
└────────────┬───────────────────────────────────────────────────────────┘
             │ (不採用コードの破棄 ＆ 失敗の分析)
             ▼
┌────────────────────────────────────────────────────────────────────────┐
│                【 記憶・進化レイヤー：Harness Feedback 】              │
│  ※失敗を「二度と繰り返さない静的ルール」へ昇格させ、次回ガチャの精度を向上  │
│                                                                        │
│   ・lessons.md (失敗ログ)  ──>  ・AGENTS.md / CLAUDE.md (静的ルール)    │
│   ・decisions.md (決定ログ)                                            │
└────────────────────────────────────────────────────────────────────────┘

---

1. 開発パラダイムの移行（静的計画から動的淘汰へ）

AIエージェントを前提としたプロセスは、従来の人間中心の開発モデルとは根本的な設計思想が異なります。

評価軸	従来の開発プロセス (スクラム / SDD)	新たな開発プロセス (Evolutionary Dev-Loop)
開発の基本思想	「一歩も間違えずに進む」 事前の綿密な仕様設計と計画（Plan）を重視する。	「変異と淘汰を高速で繰り返す」 試作・破棄（Execute）と事後学習（Retro）を重視する。
エラーの捉え方	手戻り、時間的・精神的損失。	ハーネス（制約）を強化するための**「学習データ」**。
コードのサンクコスト	高い（人間の時間と労力が注がれているため、捨てにくい）。	ゼロ（エージェントのコード生成費用は極めて安価であるため、使い捨て可能）。
品質の担保方法	人間のレビューと、リリース前の集中テスト。	段階的な自動検証フィルター（CI ── Evaluator ── Human）。

---

2. 3つの抽象レイヤー（システム構造）

dev-loop環境は、役割の異なる3つのレイヤーが相互にフィードバックを送り合う「動的制御システム」として構成されます。

① 運行レイヤー（Execution & Jitter）

限界費用がほぼゼロであるAIの特性を活かし、仮説を分散（Jitter）させて複数のPRを同時に生成・実行するレイヤー。

• Jitter（分散）: 同一プロンプトでの単純な乱数実行ではなく、アプローチ（リファクタ vs 外部モジュール導入など）や温度設定にゆらぎを与え、多様な試作品を並列作成する。
• 自律実行: ITS（チケットシステム）から要件を自動で取得し、ブランチ作成から実装までを自律的に行う。

② 淘汰レイヤー（Verification & Gate）

生焼けのコードを本番環境に入れないための、機械的かつ多層的な選択フィルターのレイヤー。

• CI（継続的インテグレーション）: クリーンな環境でビルド、テスト、Linterを強制実行する絶対的な足切りライン。
• Evaluator: 生き残った複数のPRを客観的指標（LOC、計算量、可読性）で比較・評価する別エージェント。
• Human-in-the-Loop: 最終的な「SSR（当たり）PR」の目視レビューとマージ判断のみを人間が担当する。

③ 記憶・進化レイヤー（Memory & Harness）

セッションごとに記憶がリセットされるエージェントに「持続的な学習」を与えるための外部永続化のレイヤー。

• lessons.md（失敗の構造化）: 淘汰レイヤーで弾かれた原因を、次回以降「二度と繰り返さないルール」として保存する。
• decisions.md（意思決定の固定）: 採用したアーキテクチャ方針を明文化し、不毛な設計論争のループを避ける。
• ルールへの昇格: 蓄積された知見を AGENTS.md などの静的システムプロンプト（ハーネス）に統合し、次回以降の「ガチャ（生成）の当たり確率」を底上げする。

---

3. 人間とAIの役割分担（メタ・プロセスエンジニアリング）

このプロセスにおいて、人間の仕事は「コードを書くこと」から**「プロセスと制約を設計すること」**へと完全にシフトします。

• 人間の役割:
  1. DoD（完了定義）の設計: エージェントが検証をパスしたと判断できる「テストケース」や「Linterルール」を厳格に定義する。
  2. Jitterの方向づけ: 解決したい課題に対して、どのようなアプローチ（Jitter）で探索させるかの方向性を提示する。
  3. レトロスペクティブの監督: 失敗ログから、どのルールを永続ハーネス（AGENTS.md）に昇格させるべきかを判断・整備する。
• AI（エージェント）の役割:
  1. 並列試作: 提示されたJitterに基づいて、複数のコード差分（PR）を自律的に作成する。
  2. 自己修正（Self-Healing）: CIの失敗ログを読み込み、ローカルでPEVループを回して自律的にバグを修正する。
  3. 知見の一次記録: 試作・破棄の過程で得られた学びを lessons.md に自動起票する。

---

4. 総括

この体系は、「LLMの非決定性（不確実性）」を、事前の「計画」によって抑え込むのではなく、事後の「淘汰（検証）」と「学習（レトロスペクティブ）」によって利用可能なエネルギーに変換するシステムです。

1. Jitter（分散） によって可能性を広げ、
2. CI ＆ DoD（淘汰） によって品質を保証し、
3. Lessons ＆ Harness（記憶） によってシステムを進化させる。

これが、本対話において定義された「AIエージェント駆動開発（dev-loop）」の本質的な構造です。