ADRで防ぐ、AIコーディングの仕様ドリフト

AIコーディングによる実装が、意図した仕様といつの間にかズレている。
その課題を解決するための手法として、ADRのハーネス実装による運用を紹介します。

Transcript

1. HARNESS ENGINEERING ハーネスエンジニアリングを実務で活かす ADRで防ぐ、AIコーディングの仕様ドリフト ZOE合同会社
2. HARNESS ENGINEERING ADR Harness Engineeringの対象領域 AIエージェントの素の能力と、実務で要求される信頼可能な振る舞いとのギャップ AI AGENT 適切に能力を 発揮させ、安全に 1 環境理解 Context 2 問題 必要な文脈・知識を持っていない 問題 適切な行動・手順を安定して実行できない 技法 AGENTS.md / ADR / RAG / Memory 技法 Tools / MCP / Workflow / Agent orchestration 4 実行ガード Control 実行させるには？ 3 この課題に、 4つの領域で対応する 実行支援 Execution 妥当性検証 Verification 問題 成果物が正しいとは限らない 問題 できることと、やってよいことが一致しない 技法 Test / Type / Lint / Eval / Review 技法 Sandbox / Permission / Approval / Retry limit Harness Engineering ＝ AIエージェントの能力を、信頼して利用できる状態にするための技術的問題解決 02 / 13
3. HARNESS ENGINEERING ADR Engineeringとは「技術による問題解決」である 設計・実装は目的ではなく、問題を解くために選択・組み合わせる手段 PROBLEM ENGINEERING SOLUTION 特定の問題 技術的な 知識・技法を適用 問題が 解決された状態 「望む状態」と 「現状」のギャップ 選択 / 組合せ / 判断 / 検証 実用上、目的を満たす成果へ 制約がある場合も、 問題定義の中に含めて考えられる。 Design と Implementation も、 ここで利用する技術的手段の一部。 Problem → Engineering → Solution 03 / 13
4. HARNESS ENGINEERING ADR 前提 違和感 「ハーネスエンジニアリング」という単語に対する違和感 「何に対するエンジニアリング」なのか？ 解釈 AIコーディングエージェントを、意図通りに動かすためのエンジニアリング 前提 AIコーディングエージェントは、意図通りに動作しない この事が、ハーネスエンジニアリングの前提になっている ※ 本資料の内容は、発表者個人の見解によるものです 04 / 13
5. WHY ADR なぜ ADR か？ Architecture Decision Record 01 大体の問題は、既存ツール（ハーネス）が解決してくれるから 02 かつ、仕様ドリフトの防止に有効だから この後の流れ 01 02 03 04 05 ドリフトはなぜ起きる？ ADRが「なぜ」を戻す 実務：Agentに使わせる 実例：PRのdiffで気付く まとめ
6. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 1. 仕様ドリフトはなぜ起きる？ Agentは「現在のコード」と「目の前の依頼」から、もっともらしい実装を補完する。しかし、そこに判断の「なぜ」は無い。 しくみ 例1 Retry 例2 責務境界 本質 STEP 1 STEP 2 STEP 3 STEP 4 意図・制約を決める Contextの欠落 局所最適な補完 仕様ドリフト 設計判断と、 その理由（なぜ） コードに残るのは結果だけ。 理由はAgentに渡らない 既存コードと依頼から、 妥当そうな実装を推論する 一見正しいが、少しずつ 本来の意図からズレる 「リトライは2回まで」 と決める → 残るのは MAX_RETRY = 2 だけ → 「失敗を減らして」 → 10回に増やす → テストは通る。 でも「2回」の意図は消える 「UI層からDBを 直接触らない」と決める → 残るのは 層の分割だけ → 「急ぎで対応して」 → 便利だから層を跨ぐ → 動く。 でも責務境界が崩れていく Drift ＝ 意図（なぜ）の欠落 Agentによる合理的な補完 コードは残る。しかし「なぜ」は消える。 06 / 13
7. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 2. ADRは「なぜ」をAgentのContextに戻す ADR（Architecture Decision Record）＝ 設計上の意思決定を、理由とともに1件ずつ残す短い文書 docs/adr/0012-retry-limit.md 同じ依頼 「タイムアウトによる失敗を減らして」 ADR-0012 外部APIのリトライ上限 コードだけを見るAgent Context 何が問題か Decision 何を選んだか Rationale なぜか Trade-off 何を捨てたか 外部APIの一時的な失敗をどう扱うか 実装（WHAT）と変更方法（HOW）は分かるが、理由（WHY）が無い → 「回数を増やせばいい」 MAX_RETRY = 10 別解へ流れる リトライは最大2回とする 下流サービスへの負荷集中を避けるため ADRを参照するAgent 一部の失敗は利用者に返る（10回案は却下） ADR-0012から「上限2回」は意図的な決定だと分かる → 回数以外で解決する／ 変えるならADRの再決定を提案 Status 今も有効か Accepted ※ ADRの内容は説明用の例 ポイント ADRの価値は「記録」ではなく、将来の変更時に意思決定のコンテキストを再利用できること ＝ Context Engineering として ADR を扱う 07 / 13
8. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 3. 実務：ADRを「書く」だけでなく、Agentに「使わせる」 Passive document（書いて終わり） → Executable context（Agentが毎回 参照・準拠・検査する） マージされたADRが、次の変更のDiscover対象になる 01 Discover 探す 02 Constrain 縛る 03 Record 記録する 04 Verify 検査する いつ 変更に着手する前 Planを立てる時 決定が変わった時だけ PR・レビュー時 やること 関連するADRを 探して読む 根拠となるADRを示す （またはADR不要と判断） 新しいADRを作り、 旧ADRをsupersede 変更の根拠とADRの 整合性を検査する プロンプト送信時に hookが関連ADRを提示 Skill：accepted ADRを 実装の根拠にさせる CLI supersede で置き換え （結論の上書きは禁止） CI check：根拠の申告が ないPRを失敗させる 仕組みの例 adr-governance Harness領域 AGENTS.md（例 ） 1 環境理解 4 実行ガード 1 環境理解 3 妥当性検証 変更前に関連ADRを確認する。異なる実装を選ぶ場合は、勝手に上書きせず「ADRを変更すべき理由」を提示する。 08 / 13
9. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 4. 実例①：ADRのdiffで「決定の変更」に気付く タイムアウト対策で、リトライ上限を 2回 → 5回 に変えるPR（Files changed） タイムアウト時の失敗を減らす #142 Open main ← feat/retry-limit-5 Conversation Commits Checks Files changed 3 docs/adr/0012-retry-limit.md 2 - status: accepted 3 - date: 2026-03-02 2 + status: superseded 3 + date: 2026-09-14 5 + superseded_by: ADR-0027 docs/adr/0027-retry-limit-5.md 2 + status: accepted 5 + supersedes: ADR-0012 8 + # リトライ上限を5回に変更 10 + レート上限の引き上げで負荷集中の懸念が解消したため、最大5回とする（障害時の負荷増は許容） +3 New file +10 - export const MAX_RETRY = 2; 12 1 1 既存の決定が「置き換わった」 status と superseded̲by の diff で ADR-0012が無効になったと分かる src/api/paymentClient.ts 12 −2 −0 2 2 新しい決定の「理由」が読める 論点が「数値の妥当性」から 「理由とトレードオフの是非」へ +1 −1 3 3 コードだけなら、ただの定数調整 このdiff単体では仕様変更に気付けない + export const MAX_RETRY = 5; → 仕様変更が「定数の調整」ではなく、「決定の変更」としてレビューに載る ※ ADRは adr-governance の frontmatter 形式（抜粋）。supersede コマンドが書き換え、CIが相互参照を検証する 09 / 13
10. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 4. 実例②：ADRと矛盾する変更を「根拠の申告」で見抜く Agentが MAX_RETRY を 2 → 10 に変更。ADRは更新せず、根拠に ADR-0012 を申告した タイムアウト時の失敗を減らす #143 Open A main ← agent/reduce-timeout-errors Conversation Commits Checks Files changed 1 1 agent opened this pull request 1 申告のないPRは通さない ```adr-governance コード変更には「根拠のADR」か 「ADR不要の理由」の申告が必須。 無ければCIが失敗する {"schemaVersion":2,"baseCommit":"9f3c…","decisionCorpusHash":"sha256:…", decision-evidence-required タイムアウト時の失敗を減らすため、リトライ上限を引き上げました。 "outcome":{"kind":"accepted-adr","refs":[{"id":"ADR-0012","contentHash":"sha256:…"}]}, …} ``` src/api/paymentClient.ts 10 10 +1 −1 2 export const RETRY_BACKOFF_MS = 200; 11 根拠とdiffを突き合わせる 根拠はADR-0012なのに上限は10回 → レビューで矛盾に気付ける - export const MAX_RETRY = 2; 11 + export const MAX_RETRY = 10; 3 ✓ 2 All checks have passed ✓ adr-governance / decision-gate (pull̲request) Successful ※ adr-governance（changeGate: enforce）の挙動に基づくイメージ。申告ブロックは attest コマンドで生成する 3 意味の矛盾はCIでは見ない CIが見るのは申告の有無と鮮度まで。 矛盾の判断はレビューが担う 10 / 13
11. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 4. 実例③：ハーネス全体構成 作業の段階ごとに、エージェントhook・Skill・Git hook / CI が役割を分担して効く 1 実装 ｜ エージェントhook 2 実装 ｜ Skill 3 PR作成 ADR・用語集を更新 （supersede） 関連ADRを提示 ｜ PR本文 4 CI（PR） ｜ CI ADR check （申告の検証） ADRの根拠を申告 いつ いつ いつ いつ プロンプト送信時（毎ターン） 設計判断をした時／決定が変わる時 PR作成時（コード変更を含むPR） PRのCI実行時 何をする 何をする 何をする 何をする 依頼文に設計に関わる語（認証・DB・ 境界など）があれば、関連しそうな ADRと、ADR手順書を読む指示を Agentに注入する 3条件（戻しにくい・理由なしだと誤解 される・実際のトレードオフ）を満た す判断だけADR化。結論が変わるなら 新ADRを作り、旧ADRをsupersedeす る 「根拠となる承認済みADR」か「ADR 不要の理由」を、申告ブロックとして PR本文に書く。基点コミット・差分・ ADR内容のハッシュを含めて生成する 申告の有無・形式と、ハッシュが現在 の差分・ADRと一致するか（鮮度）を 検証。ADRの状態遷移やsupersedeの 相互参照も確認し、不備があればCIを 失敗させる 効果 どの決定に基づく変更かがPRに残り、 diffと突き合わせてレビューできる 効果 実装前に、Agentが既存の決定と「な ぜ」を読む 注意 関連ADRはタイトルとの単語一致で選 ぶため、依頼の書き方によっては当た らない 決定の変更が「置き換え」として履歴 とPRのdiffに残る 注意 「結論が変わったか」の判断はAgent 任せ。直接の書き換えは機械的には検 出されない 効果 効果 注意 根拠のない変更や、古い根拠のままの マージを止める 申告の中身が正しいかは人が確認する 注意 diffがADRの決定と矛盾するかまでは 判定しない（実例②） 11 / 13
12. HARNESS ENGINEERING ADR 1 なぜ起きる 2 ADRの役割 3 実務 4 実例 5 まとめ 5. まとめ：ADRは、Agent時代の「仕様のアンカー」になる 同じAgentでも、渡すContextによって「変更を積み重ねた先」が変わる ADRなし ADRをHarnessに組み込む 入力 Prompt + Code 入力 Prompt + Code + Decision Context 1 不足情報をAgentが補完する 1 過去の意図を踏まえて推論する 2 局所的には正しい実装になる 2 逸脱を検知し、再決定する 変更のたびに、意図が漂流する 仕様の連続性を維持できる 仕様ドリフトを防ぐ鍵は、Agentを賢くすることではない。 結論 「なぜ」を、変更のたびに参照・検証できるHarnessを作ること。 12 / 13
13. Thank you! モニター募集中 AI駆動開発を支援するアルファ版のプロダクトのレビュワーを募集しています QRコードからご応募ください