ツール

AI Agentがコードを書く、その判断材料をどう残すか

ADRs for AIは、Agentの選択肢、推薦理由、確信度、証偽条件をGitに記録し、コードdiffだけでは読み取れない意思決定の背景を補完する。チームはこの仕組みを形骸化させず、実行可能な検証或有意味なレビューにつなげなければならない。

文字サイズ

AI Agentは一度に数十個のファイルを変更できる一方、その成果物として残るのは 通常、commit messageとdiffだけになる。そこには「何を変えたか」は記載されているが、「なぜこの案を選んだのか」「モデルのどの部分に不安があったのか」「同じ条件で再実行すれば、同じ結果が得られるのか」は看不懂。

Gitはコードの事実を記録するが、意思決定のすべてを記録するわけではない。ADRs for AIは、この空白を埋めることを試している。モデルの判断根拠をGitに書き込み、ORRCFを通じてAgentに疑虑を明示させる。

不足しているのはコードではなく、意思決定の記録

たとえば、Agentに同期処理を非同期キューへ変更させる場合の diff は、数行しかないこともある。producer、consumer、retry policyを追加し、元のblocking callを削除する程度だ。

コードレビューではrace condition、message loss、duplicate consumptionを検証できる。しかし、レビュー担当者には意思決定の全体像が示されない。

  • なぜRedis StreamsではなくKafkaなのか
  • なぜ既存のdatabaseをsource of truthとして残すのか
  • task latencyと運用複雑度は評価されたのか
  • どのような現象が証拠となり、この選択が誤りだったと示すのか

Agentがshopping sillersistすると、こうした問いは「best practiceに従って最適化済み」という一文に要約されやすくなる。

通常のADRは、まさにこの種の問いを扱うために作られたlightweightな意思決定記録である。Nygardの古典的な形式は通常、Context、Options、Decision、Consequencesからなる。チームがこの技術路线を選んだ理由を残すことで、後日その議論に参加しなかった统统Siblingも、コードが現在の形になった理由を理解できる。

ADRs for AIは、ADRを2点調整している。

第1に、ADRをhuman-AI collaboration的场景へ拡張する。AI Agentが意思決定提案のauthor)或、後続の意思決定記録を読む模式下、利用できる。

第2に、これらのArchitectural Deliberation RecordsをGitで保存する。記録はchat windowとともに消えるのではなく、version controlに入り、コードと同じreview、commit、rollbackの対象になる。

自然言語での説明がchat windowにだけ残るなら、それは.logに過ぎない。Gitに入れることで、協働可能なengineering contextになる。

ORRCF:モデルに先に5つの homeworkを出す

ADRs for AIは、ORRCFを使ってモデルが提示した意思決定提案を構成する。

  1. Options:現行維持を含む、実行可能な選択肢
  2. Recommendation:モデルが推薦する案
  3. Rationale:その案を推薦し、他の案を見送った理由
  4. Confidence:モデルが推薦結果に持つ確信度
  5. Falsifier:推薦が成立しないと示す証拠

単なるexplanation templateに見えるが、出力を整えるためだけの仕組みではない。

ORRCFはモデルに疑虑を明示させ、提案をhumanの承認またはoverrideに委ねる。Agentがコードをcommitし、丁寧なsummaryを添えるだけでは足りない。先に、review可能な意思決定提案を提出する必要がある。

たとえば、非同期キュー化のタスクでは、次のように記述できる。

## Options

1. 保留同步调用
2. 使用 Redis Streams
3. 使用 Kafka

## Recommendation

使用 Redis Streams。

## Rationale

当前吞吐量不需要 Kafka 的分区和运维成本。
Redis Streams 已提供 consumer group、确认机制和消息保留。

## Confidence

中高。主要不确定性是现有重试逻辑迁移后的幂等性。

## Falsifier

如果压测中 consumer lag 持续增长,或重投导致重复处理,
则当前方案不成立,应重新评估 Kafka。

humanは提案を承認,也可以overrideできる。overrideした理由もADRへ記録できる。次のAgentはコードだけでなく、チームがdesktopで行ったtrade-offも参照できる。

これにより、持続可能なAI programming scaffoldが形成される。モデルが提示した提案と、humanが提示内容を修正した内容がどちらも保存される。後続のtaskでは、承認済み、却下済み、条件付きの案をcontextとして利用できる。

すべてのcommitに長い文章を書くことを要求するわけではない。riskが高く、costが大きく、diffだけでは理解しにくい変更にだけdecision checkを追加するのが適した運用になる。

ADRをGitに置けば、協働可能なcontextになる

多くのAgent toolはcode retrievalには長けている。関連ファイルを見つけ、symbol definitionを読み、callerを検索してからimplementationを修正する。

ADRが補うのは別のlayerのretrievalである。どの選択肢がすでに議論され、どのboundary conditionですでに失敗したかを参照できる。

たとえば、最初のdatabase migrationでは、低いtrafficを理由にSQLiteを選んだ。その後、trafficが変わりPostgreSQLへ移行することになったとする。ADRには2回のdecisionが残っているべきだ。

  • 最初にSQLiteを選んだ理由
  • その後PostgreSQLへmigratedした理由
  • すでに失効したassumption
  • 今も残っているconstraint

現在のコードだけを読むと、後続のAgentは旧案を偶然のimplementationと誤解する可能性がある。ADRを読めば、少なくとも当時のconstraintを知る機会が得られる。

Gitはさらに3つのcollaboration featureをもたらす。

第1に、decisionとimplementationを一緒にreviewできる。reviewerはコードをlichに照合し、モデルの約束が実装で兑现されたかを確認できる。

第2に、decisionをrollbackできる。コードに誤りがあればdiffを戻せる。architectureの選択が誤っていた場合も,新的ADRで置き換えを明示でき、historyを消す必要はない。

第3に、責任の境界が明確になる。humanが承認またはoverrideするのは明示的な提案であり、曖昧な「モデルが処理済み」という結果を引き受けるわけではない。

ただし、ADRはtest、code review、architecture discussionを置き換えるものではない。既存のengineering activityに、共通の参照点を追加する仕組みである。

反consensus:記録を増やしてもsupervisionが増えるとは限らない

構造化されたformatをAgent workflowに組み込むと、minutesMinutesにOptions、Rationale、Confidence、Falsifierが加わる、見栄えのよい結果にziaれる。

しかし、それは形式主義に過ぎない可能性もある。

Confidenceは信頼できない。モデルが「0.8」と提示しても、その結果が80%の確率で正しいことを意味しない。training dataの言い回し、prompt template,甚至task difficultyが数値を変える可能性がある。少なくとも、説明が必要なsignalにすぎない。

Falsifierもtestそのものではない。

モデルが「consumer lagが持続的に増加すれば方案は失敗する」と記しただけでは、load testを実装したことや、チームがgrowth thresholdを知っていることは意味しない。実行されることのないfalsification conditionは、不確実性をより形式的な言語へ書き換えるだけだ。

したがって、ADRのqualityはengineering evidenceへ戻す必要がある。

  • Rationaleは実際のconstraintを参照しているか、それとも曖昧なbest practiceだけか
  • Recommendationは実際のcode changeと一致しているか
  • Falsifierは実行可能なtestまたはmonitoring metricに対応しているか
  • humanがモデルの案をoverrideした際、その理由が記録されているか
  • 後続のAgentが過去のADRを実際に読み、活用しているか

さらに見えにくい問題がある。記録がsupervision illusionを生む可能性だ。

文書が完全수록、reviewerはdecisionが適切に処理されたと考えてしまう。しかし、ORRCFがtask終了時に自動生成されるtemplateなら、コードを説明するのではなく再述しているだけかもしれない。

本当に役立つADRは、humanが不一致を発見できるようにする。

たとえば、モデルはRedisを推薦し、database lock競合を回避するためだと説明した。しかし実際のコードではtransaction内でstatus tableを更新している。人は提案と実装の乖離を即座に把握できる。

これは「モデルが自信満々にtask完了を報告する」よりも価値がある。

したがって、ADRs for AIはquality assurance interfaceではなくaudit interfaceと考えるのがよい。AIの提案を検査しやすくするが、提案そのものを自動的に正しくはしない。

元のproject descriptionは、ADRs for AI project websiteとHacker Newsでの議論に基づく。projectではArchitectural Deliberation Records、ORRCFの5項目format、humanによる承認・override mechanism、Gitベースで持続するAI programming scaffoldが紹介されている。

編集者の視点

ADRs for AIの価値は「AIを記録すること」にあるのではない。モデルの提案をaudit可能なengineering objectへ変換することにある。コードは現在のシステムが何であるかに答え、ADRはなぜその形になったかに答える。両者が同じGit historyへ入り、後日のengineerとAgentがdecision contextを継承できる状態になる。

ORRCFのshort-term valueは、autonomyではなくreview interfaceに主にあると考える。Agentがsmartになるとは限らないが、乖離を早く露出できる。推薦とコードが一致しない、falsification conditionに対応するtestがない、human overrideの理由が残っていないといった問題を早期に発見できる。

チームがこの仕組みを単なる自動meeting minutesとして扱うなら、やがてdocument burdenとなる。過去のAI programming toolとは異なる点がある。以前は主にcode completionとtest生成を補完していた。現在はAgentが複数ファイルにまたがる変更を行うため、decisionのspanがさらに広がっている。production environmentでの効果、project規模、error rateの変化を示すmaterialは提示されておらず、maturityは検証を要する。測るべきはADRの美しさではなく、半年後に新しいAgentが古い失敗を1回でも避けられるかどうかだ。

出典: https://adrs.systems