ADR を棚に置かず「生きているドキュメント（Living Documentation）」として運用する
こんにちは。Gaji-Labo でフロントエンドエンジニアをしている thkt です。
普段はチームの一員としてプロダクト開発を進めていますが、個人では AI エージェントのために使える小さな CLI ツールを作ったりしています。
先日、そのひとつで ADR（Architecture Decision Record）を書いていたら、思いがけずコードのバグを発見しました。
ADR は、重要な意思決定を背景や理由を含めて残すものです。しかし、運用ルールが曖昧だと、残しただけでそれきり読まれない文書になりがちです。今回は、このバグに気づいた経緯から考えた「ADR を生きているドキュメント（Living Documentation）として運用する」ことの良さについて話をしたいと思います。
書こうとして分類ミスに気づいた話
作っていた CLI では、外部 API を叩いてエラーが返ってきたとき、呼び出し側のスクリプトが「再試行すべきか、停止すべきか」を判断できるように実装していました。
分岐の基本方針はシンプルで、一時的な失敗なら再試行、使い方の誤り（クライアント側のエラー）なら停止、というものです。ただ、この時点では「API のクォータ枯渇」というケースを見落としていました。401/403 は使い方の誤りとして停止に倒すつもりでしたが、403 は課金上限の枯渇でも返ることがあり、それは時間を置けば回復しうる一時的な失敗です。これに気づけたのは、実装中ではなく ADR を書いている途中でした。
「すでにこう実装されている」という記録として ADR に転記するのではなく、「本当にこの分岐で正しいか」という仮説として捉えながら書いたことが良かったのだと思います。
決定を記録するだけだと、ADR は棚に置かれる
こんなふうに、ADR は書く瞬間に実装を見直すきっかけをくれますが、それで役目を終えてしまうことも少なくありません。
ADR は「決定の文脈と理由を記録する文書」なので、記録だけを主眼に置くと見返されず、数ヶ月後にコードと食い違っていても気づかなかったということが起こりえます。
そうならないためには、書いた内容が実態と合っているかを確かめ続けている必要があります。
AI エージェントを活用して Notes で実態に合わせ続ける
では、どうすれば確かめ続けられるのでしょうか。
ドキュメントは増えれば増えるほど確認のコストが膨らむので、ADR にする内容を絞ることからはじめます。私の場合は、型やテスト、linter などで自動的に気づけない判断だけを ADR に残すようにしています。
残した ADR と実装を照らし合わせる作業は、AI エージェントに任せています。私はレビューを行うスキルに ADR とのギャップがないかを確認するように仕込んで、決定とのズレがないかを確かめさせています。
クライアント名や設定値といった具体的なシンボルで ADR を書いておくことで、それがそのままコードと突き合わせるチェックリストになるというわけです。
ADR の更新は Notes として記録します。ADR 自体は合意した決定の足跡として変更しないのがルールなので、注釈のような形で変更記録を重ねます。根本から切り替わるような決定であれば新たに ADR を起票して、そちらが正であることを Notes に残す運用にしています。
たとえば、あるツールに「エラーの種類をどう分類するか」を決めた ADR があります。最初に実装したときは 8 種類でしたが、その後も機能を足したり監査でズレを見つけたりするたびに増えていき、いまは 13 種類です。それでも ADR 本文の決定は一度も書き換えていません。増えていった経緯は、すべて日付つきで ADR ドキュメント末尾の Notes に積み上げています。
> **Notes (2026-05-13)**: 当初挙げた `ReadmeMissing` は、README が無い場合（404）を意図的に何もしない扱いにしていたため、分類には含めなかった。README まわりは失敗のしかたで 3 つに分割した。人間が決定をまとめ、AI が実装のたびに照らし合わせる。この分担にすると ADR を確かめ続ける負担が小さくて済みます。
まずは書き始めること
ADR を生きているドキュメントにするには、まずは書くことが大事です。書いたあとは AI に比較を任せて Notes を更新していくというのが、決定に即したコードとドキュメントを維持する運用として無理がないのではないかと思っています。
ぜひ AI エージェントを活用して ADR を生きているドキュメントにする運用を試してみてください！
Gaji-Labo は Next.js, React, TypeScript 開発の実績と知見があります
フロントエンド開発の専門家である私たちが御社の開発チームに入ることで、バックエンドも含めた全体の開発効率が上がります。
「既存のサイトを Next.js に移行したい」
「人手が足りず信頼できるエンジニアを探している」
「自分たちで手を付けてみたがいまいち上手くいかない」
フロントエンド開発に関わるお困りごとがあれば、まずは一度お気軽に Gaji-Labo にご相談ください。
オンラインでのヒアリングとフルリモートでのプロセス支援にも対応しています。
Next.js, React, TypeScript の相談をする！Gaji-Labo フロントエンドエンジニア向けご案内資料
Gaji-Labo は新規事業やサービス開発に取り組む、事業会社・スタートアップへの支援を行っています。
弊社では、Next.js を用いた Web アプリケーションのフロントエンド開発をリードするフロントエンドエンジニアを募集しています！さまざまなプロダクトやチームに関わりながら、一緒に成長を体験しませんか？
もちろん、一緒にお仕事をしてくださるパートナーさんも随時募集中です。まずはお気軽に声をかけてください！
