fukurou

karasu の ADR は何に効いていたか

  • #ai
  • #adr
  • #claude-code
  • #karasu
Low の PR を GitHub Actions でマージしたいという依頼に、エージェントが同じ案を却下した ADR-3416 を指摘した流れ。却下理由は、設計の前提、私の判断事項、新しいテスト観点として設計に残った

私が開発しているアーキテクチャ図ツール karasu では、設計判断を ADR（Architecture Decision Record、設計判断の記録）として docs/adr/ に残しています。 2026 年 3 月の初日から書き始めて、8 か月で 495 本になりました。

7 月には「ADR をリポジトリに残す意義と、コーディングエージェントへのコンテキストの効果的な渡し方」という記事を書きました。 却下済みの提案をエージェントにもう一度依頼する対照実験で、ADR が効く条件を確かめた記事です。 今回は実験ではなく、実際の運用に残った痕跡を調べました。 ADR は、どこで、誰に引かれ、何を変えていたのか。

サマリ

  1. エージェントは、新しい依頼の場に過去の却下を持ち出していた。 設計文書を作るスキルを使った 17 セッションのうち 15 で、却下済みか衝突する ADR を引いていた。持ち出された却下理由は、設計の前提と判断事項に残った。
  2. 確認は、スキルの必須手順として入れてあった。 7 月の実験で効いた、設計の前に過去の決定を確かめる一文を、スキルの手順にしていた。実験室で見た効果が、実運用でも同じ形で出ている。
  3. 同じ手順が、上書きしたいときの確認の負担も生んでいる。 過去の決定を変えるつもりで依頼しても、エージェントはそのたびに確認を求める。

調べたもの

karasu の開発では、要件から Design Doc（設計文書）を起こして設計を検討し、決定が下りたら ADR に昇格させて Design Doc を削除します。 採用した決定だけでなく、検討して見送った提案も not_adopted（不採用）のステータスを付けて残しています。 開発の大半は Claude Code に任せていて、ADR を追加したコミットの 8 割（495 本中 395 本）に Claude Code の共著表記があります。

調べたのは次の 3 つです。

  • ADR：495 本（2026-03-12〜11-09）の本文と frontmatter（ファイル冒頭のメタデータ）
  • Issue と PR：1,342 件と 2,397 件の本文、コメント、レビュー
  • Claude Code のセッションログ：直近 1 か月（2026-10-13〜11-10）のメインセッション 149 本と、そこから起動されたサブエージェント 442 本

先に断っておくことがあります。 karasu の ADR は初日からあるので、ADR を入れる前と後を比べることはできません。 ここで書けるのは、ADR が実際に担っている仕事の観察までです。 「ADR があったから良くなった」という因果は主張しません。

新しい依頼に持ち込まれる過去の却下

ADR に助けられたと感じるのは、作りたいものをプロンプトに書いたときです。 過去の経緯で NG にしたアイデアを、エージェントがちゃんと指摘してくれます。 それを受けて考え直すと、より良い仕様と設計にたどり着けます。

ログにも、この場面がそのまま残っていました。

karasu では、PR を変更の中身でリスク段階に分けています。 Low の PR は、人が読まずに auto-merge で入ります。 その auto-merge を有効にするのは Claude Code で、コマンドの実行可否は auto mode の分類器（LLM）が判断していました。 11 月 2 日、私はこれを GitHub Actions に移せないかと相談しています。 10 分ごとに risk: low の PR を見て、CI が通ったらマージする。 そうすれば LLM の分類器を通さずに、確実にマージできるのではないか、という相談です。

エージェントは案に賛成したうえで、これは今のリスク段階を決めた ADR-3286 を置き換える決定になるので、Design Doc から始めるのが筋だと返しました。 Design Doc を書くスキルの手順で過去の決定を確かめると、次のように止まりました。

重要な先行決定が見つかりました。ADR-3416 が「Actions で auto-merge を有効にする案」を却下しています。

ADR-3416 は、ADR の索引を毎日再生成する仕組みを決めた記録です。 そこで退けた案の理由は、マージの名義でした。 Actions がマージすると名義が GITHUB_TOKEN になり、その main への push では deploy などの workflow が起動しません。 私の案も Actions がマージするので、同じ落とし穴を踏みます。 Low の PR でもドキュメントサイトの変更が公開されなくなります。

この却下理由は、できあがった設計に 3 か所で残りました。

  • GITHUB_TOKEN でマージすると push の workflow が起動しないことを、設計の前提に置いた。
  • 起動させるには新しい鍵（GitHub App か個人のアクセストークン）が要る。これは ADR-3416 が利点に挙げた「新しい鍵を足さない」を覆すので、私が判断する事項として切り出された。
  • 「main に入れる経路が、push の workflow を起動する名義を使っているか」というテスト観点を新しく起こし、その根本原因に ADR-3416 を記録した。

実装は、判定結果を出すだけの workflow から始めました。 マージとコメントは、まだしません。 却下理由を知らずに進めていたら、マージは動くのにサイトが更新されない、という壊れ方に本番で初めて気付いた可能性があります。

確認はスキルの手順に入っている

この指摘は偶然ではありませんでした。 7 月の実験では、依頼の前に一文を足しました。 「設計や実装案を書く前に、docs/adr/ を検索し、関連する決定や却下がないか必ず確認すること」。 この一文で、却下済みの ADR への到達が 0/3 から 3/3 に変わりました。 その結果を受けて、私は Claude Code の開発スキル集 hane に手を入れていました。 Design Doc を書くスキルと開発を始めるスキルに、過去の決定（特に却下）との衝突確認を必須の手順として入れたのです（hane の ADR-63、2026-07-09）。

7 月の記事で測ったのは、確認の一文を常設ルールに置く形だけでした。 スキルの手順に書く形は、遵守率を測っていませんでした。 今回のログは、そのスキルの形の実地の記録です。 直近 1 か月で Design Doc のスキルを使った 17 セッションのうち 15 で、エージェントは却下済みか衝突する ADR を引いていました1。 手作業で読んだほかの例でも、エージェントは設計を始める前に止まっています。

重要な先例が見つかりました。ADR-2898 が、「却下した案」の中で auto_incremental_review: false を一度退けています。

ADR-2249 と ADR-2262 に「permalink 面にカウンタを置く案を却下」という記録がありました。

Issue とレビューで引かれる ADR

人の側の経路でも、ADR は引かれていました。 起点の Issue と PR を除き、ADR を書いた日より後の Issue や PR で引かれた ADR は 495 本中 408 本（82%）です。

引かれ方には、却下を理由に提案を閉じる形があります。 マージ後の確認項目を元の Issue で追う、という提案（#2957）は、ADR-3271 の却下した案に挙がっているとして見送りになりました。 usecase に属性ベースの認可を書けるようにする提案（#832）も見送りました。 ADR-834 は、セキュリティや脅威モデリングを karasu の語彙に入れず、外部の文書に委ねると決めています。 その理由が、認可にもそのまま当てはまるからです。

却下が、新しい機能の範囲を決めることもあります。 4 月に、ADR-105 で「PNG エクスポートは実装しない」と決めました。 6 月の PR（#1796）は PNG 出力をサーバー側の 1 か所にだけ置き、CLI とアプリの PNG を見送った ADR-105 は覆さない、と書いて範囲を絞っています。 却下の記録が、作るものの境界線として使われています。

レビューでは、指摘を断る根拠として ADR が出てきます。 AI のコードレビュー（CodeRabbit）の指摘に対し、適用すると ADR-2693 が同じ系列の ADR と食い違うので適用しない、と返す、といった形です。 ただ、私の名義のレビューには Claude Code が書いたものも含まれていて、人とエージェントのどちらが引いたかは区別できていません。

コード注釈に書き写された決定

ADR の決定は、コードにも書き写されています。 テスト以外のコードから引かれている ADR は 167 本、テストから引かれている ADR は 76 本でした。

書き写しは、ADR が置き換えられた後も役目を持っていました。 置き換え済み（superseded）の ADR 25 本のうち 15 本は、まだコードや設定から引かれています。 読んだ範囲では、古い指示の消し忘れではありませんでした。 たとえば、あるファイルの冒頭には次の一文があります（ADR-1990 の決定 2 のうち、生き残った一方向）。

 * The one direction of ADR-1990 decision 2 that survives.

ADR の置き換えは、ADR 単位で記録します。 しかし実際には、決定の一部だけが生き残ることがあります。 その粒度を、コードの注釈が手で補っているように見えます。 エージェントはコードを読むとき、この注釈も目にします。 ADR を開かなくても、決定の一部は届いています。

上書きしたいときの確認

ADR が足かせだと感じるのは、過去の経緯を上書きしたいときです。 変えるつもりで依頼しても、エージェントはそのたびに確認を求めてきます。

ログでは、ADR に触れた確認の質問が 149 セッション中 27 セッションで 29 件ありました。 うち 7 件は、既存の ADR を変えることになるがどうするか、という問いです。

High の PR もマージまで自動にしますか？ 今は ADR-3286 で auto-merge できるのは Low だけです。

これは手順どおりの動きです。 7 月の実験で使ったルールには、「過去の決定を覆す提案になる場合は、黙って進めず、覆すことを明示して確認を取る」と書いていました。 過去の却下を持ち出してくれる手順と、上書きのたびに止まる手順は、同じものの表と裏です。 確認を軽くする手として、どんな条件なら覆してよいかを、ADR に再評価の条件として書いておく方法はあります。 7 月の実験でも、再評価の条件が書いてあると、エージェントは確認の質問をその条件に沿って組み立てていました。 ただ、ADR を残す時点で、覆す条件まで見通せることはあまりありません。 想定できるときには書いておく、くらいが現実的だと考えています。 それ以外の場面では、上書きのたびの確認は残ります。

限界

今回の調査は観察で、因果は示せていません。 エージェントが却下を指摘しなかった場合に何が起きたかは、ログからは分かりません。 セッションログは直近 1 か月分で、ADR の 8 か月のうち最後の 1 か月しか見ていません。

ADR を続けるコストも、今回は数えていません。 ADR の本文は長くなり続けていて、中央値は 3 月の 2,308 字から 11 月の 6,941 字まで伸びました。 1 本の ADR に複数の決定が入り、その一部だけを後の ADR が覆すと、人向けに生成している現役の ADR の一覧には、古い決定が現役のまま載り続けます。 この表し方は、ADR を扱うツールの側で直そうとしています（kompiro/adr-tools#37）。

まとめ

ADR の効果は、書いたときではなく、後で引かれたときに出ていました。 7 月の実験で見つけた、設計の前に過去の決定を確かめる一文はスキルの手順になり、その手順を通った 17 セッションのうち 15 で、エージェントが過去の却下を持ち込んでいました。

却下した案を記録に残しておくと、エージェントがそれを次の依頼の場に持ってきます。 以前に検討して退けた案の記録は、同じ方向の依頼を私が出したときに、設計を組み直すきっかけになりました。

Footnotes

  1. ADR の ID と「却下」「見送り」「衝突」「覆す」などの語が同じ発言にあるものを数えました。発言を 1 件ずつ読んで確かめたのは、本文で挙げた例を含む 6 件です。 ↩