AI時代のアドバイス設計書（ADR）運用：文章の完成度と設計の妥当性を見極めるレビューの重要性
本記事は、AIを活用して技術的な意思決定記録（ADR）を作成・運用する過程で発見された、開発プロセスにおける重要な落とし穴について詳述しています。筆者は、認証トークンのセキュリティ強化のため、ブラウザストレージへの保存を避け、トークンの取得・保持をサーバー側（BFF）に寄せ、ブラウザからはHttpOnly Cookieとしてのみ扱うという設計を検討しました。このADRは、単なるログとしてではなく、「AIが実装に落とし込める」レベルまで具体化することを目的として作成されました。
AIによる文章の整形は、意思決定の過程を明確に記録し、後からの手戻りを減らす点で非常に効果的であり、実際にADRをIssue化してAIに実装を任せることで、高い完成度まで一気に進める手応えを感じました。しかし、レビューの過程で重大な問題点に気づきます。初期案では、実装コストの低い「公式SDKの機能」を利用する案が有力候補として提示され、AIが整えた文章はこれを非常に説得力のあるものに仕上げていました。しかし、筆者はここで立ち止まり、一次情報である公式ドキュメントまで遡って確認した結果、常時安定稼働が求められるシステムにおいて、実験的な機能に依存することはリスクが高すぎると判断し、当初の案を破棄しました。
この経験から、AIが生成した文章の「読みやすさ」や「説得力」は、設計の「妥当性」を保証するものではないという結論に至っています。筆者は、ADRのレビューにおいては、①前提条件そのものの妥当性、②一次情報への到達（公式ドキュメントの確認）、③コンポーネント間の食い違いの明示的な調整という、人間による深い検証が不可欠であると警鐘を鳴らしています。これは、単に文章を整えるだけでなく、「なぜその設計にしたか」という背景と、その技術的制約を深く掘り下げて確認するプロセスこそが、AI時代における開発の品質保証の鍵であると提言しています。
背景
本記事は、現代のソフトウェア開発における「意思決定の記録（ADR）」の重要性と、AIツールが開発プロセスに与える影響を扱っています。特に、認証トークンのセキュリティ確保（XSS対策）という具体的な技術課題を背景に、AIによる効率化が進む中で、人間が持つべき「一次情報検証」という批判的思考の必要性を訴えています。
重要用語解説
- ADR: Architecture Decision Recordの略。システム設計における重要な意思決定の背景、検討過程、および結論を記録するドキュメント。後から設計の経緯を追跡するために用いられる。
- XSS: Cross-Site Scriptingの略。ウェブアプリケーションの脆弱性の一つで、悪意のあるスクリプトをウェブページに埋め込み、ユーザーのブラウザ上で実行させることで情報窃取などを引き起こす攻撃手法。
- HttpOnly Cookie: ブラウザのCookieの一種で、JavaScriptからのアクセスを制限する属性が付与されている。これにより、XSS攻撃によるトークン盗難のリスクを大幅に軽減できる。
今後の影響
本ニュースは、開発チームのレビュープロセスに大きな影響を与えます。AIによる効率的なドキュメント作成は加速する一方、レビュー担当者は「文章の完成度」に騙されず、必ず公式ドキュメントや一次情報まで遡って技術的な妥当性を検証する習慣が求められます。これにより、開発の品質保証の基準が「記述の美しさ」から「根拠の確実性」へとシフトすることが予想されます。