開発チームの意思決定を記録しよう！LLMとADRで実現する設計知識の継続的な管理

この記事はLLMによるADRの自動更新：設計知識の継続的な記録と活用の内容を再構築したものです。より詳しい技術的な解説や研究的な内容については、元記事をご参照ください。

GitHub Copilotなどのコード生成AI（LLM）は、コードの理解力が飛躍的に向上し、開発現場での活用が広がっています。しかし、実際にコーディングを任せてみると、思わぬ困難に直面することが多いのではないでしょうか。

例えば：

• プロジェクト固有のアーキテクチャを理解できない
• チーム独自の命名規則やコーディング規約に従えない
• 一度説明した設計方針をすぐに「忘れて」しまう
• 生成されたコードが既存システムと整合性を欠く

これらの問題の多くは、LLMが「プロジェクトの文脈」を十分に理解できていないことに起因します。では、どうすればLLMにプロジェクトの設計意図を効果的に伝えられるのでしょうか？

この記事では、LLMとの効果的な協業を実現するために、ADR（Architecture Decision Records）を活用する方法を紹介します。

TL;DR

• LLMは高性能化しましたが、プロジェクト固有の設計意図の理解は依然として課題です
• ADRを使ってプロジェクトの文脈をLLMに伝えることで、より適切なコード生成が可能になります
• 結果として、チームの設計方針に沿った一貫性のある開発支援を実現できます

LLMの課題：なぜコンテキストを忘れるのか

最近のLLMは非常に優秀で、コード生成やレビュー、バグ修正などで大きな支援になります。しかし、研究によれば、LLMの長期的な対話能力は非常に限定的だとされています。

実際の開発でこんな経験はありませんか？

• 「さっきまで理解していた設計方針を、LLMが急に忘れる」
• 「チームの別のメンバーが使うと、違う方針のコードを提案される」
• 「プロジェクト特有の制約を何度も説明する必要がある」

これらの問題は、LLMが本質的にステートレス（状態を持たない）であることに起因します。では、どうすれば解決できるのでしょうか？

解決策：ADRでLLMに文脈を与える

ここで注目したいのが、ADR（Architecture Decision Records）です。ADRは2011年にMichael Nygardによって提案された、設計上の意思決定を記録する手法です。

ADRの特徴

1. 一つの決定に一つのドキュメント

   • プロジェクトの重要な決定を個別のファイルに記録
   • LLMが必要な情報にピンポイントでアクセス可能

2. 不変性

   • 一度作成したADRは変更せず、新しいADRで上書き
   • LLMが決定の変遷を正確に理解できる

3. バージョン管理との統合

   • GitHubなどで管理
   • コードの変更とADRの更新を紐付け可能

4. 簡潔性

   • 1-2ページに収める
   • LLMのコンテキストウィンドウに収まりやすい

具体的な活用方法

1. ADRで設計文脈を記録

基本的なADRテンプレートはこんな感じです：

# ADR-0001: ［決定のタイトル］

## ステータス
［提案済み/承認済み/破棄/更新済み］

## 背景
［この決定が必要になった背景・課題］

## 決定
［具体的に何を決定したか］

## 結果
［この決定による影響・期待される効果］

## 注意点
［実装時の注意点・制約事項］

2. LLMへの文脈提供

ADRをLLMに提供する方法：

1. 関連ADRの参照

   ここからはADR-0001で定義した認証フローに従って
   実装を進めていきます：
   [ADRの内容をペースト]
   

2. 制約条件の説明

   このプロジェクトでは以下のADRで定義された
   技術スタックを使用します：
   [ADRの内容をペースト]
   

3. 設計方針の共有

   ADR-0003で決定したように、このマイクロサービスは
   以下の責務を持ちます：
   [ADRの内容をペースト]
   

3. LLMとの協業プロセス

1. ADRの作成・更新支援

   • LLMに既存のADRを提供し、更新案を生成
   • 変更による影響範囲の分析を依頼

2. レビュー支援

   • ADRの内容に基づいたコードレビュー
   • 設計方針との整合性チェック

3. 実装支援

   • ADRを参照しながらのコード生成
   • 設計意図に沿ったリファクタリング

実践のポイント

1. 適切な粒度でADRを作成

   • 多すぎると管理が大変
   • 少なすぎるとLLMが文脈を理解できない

2. 定期的なメンテナンス

   • 陳腐化したADRは混乱の元
   • 四半期に1回程度は見直しを

3. チームでの合意形成

   • LLMは支援ツール
   • 最終判断は人間が行う

まとめ

LLMとの協業において、ADRは「プロジェクトの記憶装置」として機能します。適切に管理されたADRがあれば、LLMはプロジェクトの文脈を理解し、一貫性のある支援を提供できます。

まずは小さく始めて、チームに合った活用方法を見つけていくことをお勧めします。

参考リンク

• LLMによるADRの自動更新：設計知識の継続的な記録と活用（元記事）
• adr.github.io - ADRの公式サイト
• GitHub - ADRツールとテンプレート集