前回の記事では、ADR（Architecture Decision Record）が「人間の更新速度が追いつかない」という理由で廃れた経緯と、AIコーディング時代にその価値が再び見直されていることをお伝えしました。
本記事では、sqlewが従来のADRの弱点をどう克服し、AIネイティブな設計記憶として再設計しているかをご紹介します。
Markdownで記録することの限界
従来のADRはdocs/adr配下にMarkdownファイルを並べていく方式でした。シンプルで始めやすい一方、AIコーディングの文脈ではいくつかの課題が顕在化します。
まず、検索性の問題です。ADRが数十件に増えると、今のタスクに関連するADRをファイル名だけで特定するのは困難です。次に、トークン効率の問題。全ファイルをLLMのコンテキストに読み込めば、関係のない情報までトークンを消費し、推論精度の劣化を招きます。そして運用の不確実性。AIエージェントがADRを「必ず読む」「必ず更新する」保証はなく、参照も更新も任意になりがちです。
これらはMarkdownというフォーマットの問題ではなく、「ファイルベースの静的な管理」がAIとの協働に適していないという構造的な課題です。
sqlewのアプローチ
sqlewは、ADRの記録先をMarkdownファイルからRDBMSに移しました。設計判断をテーブルに構造化して保存することで、タグやキーワードによる検索が可能になり、必要なADRだけをピンポイントで取得できます。
しかし、保存先を変えただけでは「必ず読まれる」「必ず更新される」問題は解決しません。そこでsqlewは、Claude CodeのHooks機能を活用した2つの仕組みを提供しています。
一つ目は、プランモードでの自動サジェストです。AIエージェントが実装計画を立てる段階で、関連する過去のADRをMCP経由で自動的に提示します。開発者がタスクに取りかかる前に、過去の設計判断とその理由が自然と目に入る仕組みです。
二つ目は、プランファイルからのADR強制作成・更新です。実装計画の中で新たな設計判断が行われた場合、Hooksがそれを検知し、ADRの作成または更新をトリガーします。「書き忘れ」が発生しない運用フローを、ツール側で担保するアプローチです。
AIネイティブで復活するADR
従来のADRは、人間が「書く」「探す」「読む」すべてを担っていたために運用が回りませんでした。sqlewは、この3つのプロセスをAIとツールが引き受けることで、ADRの本来の価値——設計判断の理由を蓄積し、一貫性のあるコード生成を支える——を実現します。
人類には早すぎたADRを、AIネイティブな仕組みとして再定義する。sqlewはその取り組みの第一歩です。
参考文献
- "Documenting Architecture Decisions" — Michael Nygard (2011) — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- "Using architectural decision records to streamline technical decision-making for a software development project" — AWS Prescriptive Guidance (2022) — https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html
