株式会社インフォメーション・ディベロプメント
🗒️

将来の保守を楽にする ADR × GitHub Copilot で設計意図を残す

KSAN
に公開
AI
GitHub
VS Code
prompt
ADR
tech

こんにちは。システム開発の経験をもとに、現場で使える AI 活用を発信している KSAN です。

この記事は、機能追加やバグ修正のたびに「なぜこの仕様にしたのか」がわからず、調査に時間を取られている現場エンジニア向けです。

システム開発の現場では、コードや仕様書があっても、当時の判断理由まで残っているとは限りません。
この記事では、そんな課題を解消するために ADR と GitHub Copilot（以降、Copilot）を組み合わせた ADR 運用を紹介します。
将来の保守を楽にするための方法として参考にしてください。

この記事を読むと、次の3点が得られます。

  • そもそもADRが何なのかが、わかります。
  • Copilot を使って ADR の運用を省力化する仕組みが作れます。
  • 数か月後の改修時や担当者交代時でも、調査時間を短縮できるようになります。

設計意図が残らないと、何がつらいのか

このような経験はないでしょうか？

  • 設計書に上限値や制約が記載されていたが、なぜその値なのかわからない
  • 以前、見送った案があるらしいが、理由が見つからない
  • 影響調査をしたいのに、当時の実装方針がわからない

具体的な例をあげてみます。
CSVインポート機能に「上限は500件」と設計書に記載されていたとします。
しかし、これだとなぜ500件なのかはわかりません。
運用上の制約なのか、同期処理の都合なのか、あるいは深い意図は無く決まったかもしれません。

この状態だと「上限を拡張したい」と要求されても、単純に500→1000件に変更することはできません。変更前に実装されているコードを解読したり、昔の議事録やメモを探したりと調査に時間を取られます。

最近だとコードから「何をしているか」、「どのように直せばよいか」をAIに依頼することができます。ただ、AIでも当時「なぜそうしたか」までは知ることはできないので、判断を誤る可能性があります。
この「なぜ」を補うのがADRの役割です。

ADRとは何か

ADRは Architecture Decision Record の略で、重要な判断の背景と結論を残すための文書です。文書と書くと、重いアーキテクチャ書をイメージするかもしれませんが、本記事では「あとで設計意図が取り出せるメモ」くらいで捉えてください。
ADRについて詳細が知りたい方は、AWSのADR プロセスを参照。

ADR自体は新しい考え方ではありません。
ただADRの運用をしようとすると、フォーマットに従って書くのが手間で続けづらいという側面があります。
そこで使うのがCopilotです。

ここからは「人が頑張って運用する」から「AIに協力してもらいながら運用する」の仕組みを作っていきたいと思います。

ADRの運用構成

今回作る仕組みは、ADRを完璧に整備する運用ではありません。
まずはADRを導入し、「書く」「読む」の2つを回せる状態を作ります。

この運用で人がやること

  1. Copilotチャットで/create-adrを使って、ADRのたたき台を作成する
  2. たたき台を確認し、補足や誤りを訂正する
  3. コードを改修する際は /search-adrを使って、関連するADRを確認する

前提環境

2026年4月に手元で確認した環境は次のとおりです。

  • OS: Windows
  • VS Code 1.116.0
  • GitHub Copilot Chat 0.44.2
  • Claude Sonnet 4.6

導入Step 1: サンプルファイルをプロジェクト内に配置する

フォルダ構成

プロジェクトルート/
├── .github/
│   └── prompts/
│       ├── create-adr.prompt.md   # ADR作成用プロンプト
│       └── search-adr.prompt.md   # ADR参照用プロンプト
│
└── docs/
    └── adr/
        ├── ADR-0000-template.md   # テンプレート
        ├── ADR-0001-xxxx.md       # 実際のADR(自動生成)
        ├── ADR-0002-xxxx.md       # 実際のADR(自動生成)
        └── ...

ファイルの関係図

サンプルファイルとしてこちらを使ってください。

.github/prompts/create-adr.prompt.md のサンプル
---
description: 議事録・メモ・会話の文字起こしからADR（Architecture Decision Record）の下書きを作成し、docs/adr/ に保存します。
argument-hint: ADRのインプットとなる議事録・メモ・会話の文字起こしを貼り付けるか、ファイルパスを指定してください（例: #file:docs/minutes/20260328-meeting.txt）
---
# ADR作成プロンプト
## 役割
あなたはADR（Architecture Decision Record）作成の専門家です。
提供されたインプット（議事録・メモ・会話の文字起こし・ファイル）を読み取り、
ADRの下書きを作成してください。

## インプットについて
以下のいずれかの形式でインプットが提供されます。
- テキスト（議事録・メモ・会話の文字起こしを貼り付けたもの）
- ファイルパス（例: #file:docs/minutes/20260328-meeting.txt）
- 添付ファイル（テキスト形式のファイル）

複数のインプットが提供された場合は、すべてを統合して読み取ってください。

## 出力ルール
- 必ず以下のテンプレートに従ってMarkdown形式で出力すること
- インプットから読み取れた情報のみを記載すること
- 推測や補完は行わないこと
- `docs/adr/` にファイル保存すること
- テーマが複数ある場合は、1ファイル1テーマにすること

## 日付の記入
- インプットの内容から日付を記入すること
- インプットに日付が無い場合は、本ファイルの作成日を記入すること

## ステータスの選択肢
- 有効：固定(将来拡張予定)

## 保存するファイル名
ファイル名は、以下の命名規則に従うこと。
```
ADR-[4桁連番]-[タイトル].md
```

- 4桁連番は0001から始める（0002, 0003と続ける）
- タイトルはインプットの内容から簡潔に日本語で命名する
- 体言止めにしない

例: 
  `ADR-0001-ファイルインポート機能の追加にあたり設計方針を定める.md`
  `ADR-0002-ロギング出力フォーマットを標準化する.md`
  `ADR-0003-環境変数管理にdotenvを統一する.md`

## 出力テンプレート
`docs/adr/ADR-0000-template.md` をテンプレートとして使用すること（`#file:docs/adr/ADR-0000-template.md`）。

- テンプレート内のコメント（`<!-- -->`）は出力に含めないこと
- 情報が不足している項目は空欄にせず `【要確認】` と明記すること

## 出力後のアクション
- 出力後に【確認をお願いします】のメッセージを必ず表示すること。
- 【要確認】の行は、ファイル内に【要確認】が1件以上ある場合のみ表示すること。

---
【確認をお願いします】

- `【要確認】` の箇所は内容を補完してください
- 内容に事実と異なる部分があれば修正してください
---
.github/prompts/search-adr.prompt.md のサンプル
---
description: ADR（Architecture Decision Record）を検索し、関連するADRを要約して返します。
argument-hint: 検索したいキーワードや質問を入力してください（例：「認証」「インポート」「削除処理を変更したいがADRはあるか」）
--- 
# ADR検索プロンプト
## 役割
あなたはADR（Architecture Decision Record）の検索・要約の専門家です。
提供されたキーワードや質問をもとに `docs/adr/` 配下のADRを検索し、
関連するADRを簡潔に要約して返してください。

## インプットについて
以下のいずれかの形式でインプットが提供されます。
- キーワード（例：「認証」「削除処理」「インポート」）
- 質問文（例：「削除処理を変更したいがADRはあるか」）
- 作業内容（例：「ファイルインポート機能を改修したい」）

## 検索ルール
- `docs/adr/` 配下の全ADRファイルを対象とする
- ステータスが「有効」のADRのみ結果に含める
- 関連度の高いものから順に返す
- 該当するADRが存在しない場合は「該当するADRは見つかりませんでした」と返す

## 出力ルール
- 該当するADRを全て返す
- 各ADRは以下のフォーマットで要約する
- 推測や補完は行わないこと
- ADRに記載のない情報は含めないこと

## 出力フォーマット
```
## 該当ADR：[件数]件
---

### [ファイル名]
**日付**：[日付]

**決定内容**
[Decisionセクションの要点を2〜3文で要約]

---
[複数件ある場合は同じフォーマットで続ける]
```

## 出力後のアクション
出力後に以下のようなメッセージを提案すること。

---
ADRをもとに続けて指示できます。
例：「ADR-xxxxをもとに〇〇の影響範囲を調査して」
　　「ADR-xxxxの内容を考慮して〇〇の実装方針を提案して」
---
docs/adr/ADR-0000-template.md のサンプル
# [タイトル]
## メタ情報
| 項目       | 内容            |
|------------|-----------------|
| 日付       | YYYY-MM-DD      |
| ステータス | 有効            |
| 関係者     | 氏名, 氏名, ... |

## Context（背景・状況）
<!-- なぜこの検討が必要になったか。どんな問題・制約があったか -->

## 決定
<!-- 何を選んだか。なぜその選択肢にしたかも一緒に書く -->

## 結果
### ポジティブ
<!-- この決定によって良くなること -->

### ネガティブ
<!-- トレードオフ・注意点・将来変更する際のリスク -->

## 備考
<!-- 選択肢の比較・関連資料・補足事項など自由に記載 -->

サンプルの内容は現場に合わせてアレンジして構いません。

導入Step 2: create-adr でたたき台を作る

スラッシュコマンドの/create-adrにADRのネタを指定して、実行するとCopilotがたたき台を作ってくれます。

呼び出し方は次のとおりです。

/create-adr
[ADRのネタ]

ADRのネタは、テキストやファイルパスを指定します。
今回は、架空のオンライン会議(文字起こし)ファイルを指定しました。

/create-adr
c:\temp\202604xx_検討会.txt

以下の内容でdocs\adr\ADR-0001-CSVインポート機能の件数上限を1ファイル500件にする.mdファイルが自動生成されました。

# CSVインポート機能の件数上限を1ファイル500件にする
## メタ情報
| 項目       | 内容            |
|------------|-----------------|
| 日付       | 2026-04-xx      |
| ステータス | 有効            |
| 関係者     | 山田, 鈴木, 佐藤 |

## Context（背景・状況）
CSV一括登録を同期処理で実装するため、1ファイルあたりの登録件数が多すぎると
タイムアウトが発生するリスクがある。上限を設けずに運用すると、
ユーザーが大量データを投入してタイムアウトが連発する事態が懸念された。

## 決定
1ファイルあたりの上限を500件とする。500件を超えるファイルは受付時点でエラーとし、
登録処理には進まない。
将来的に実運用で問題がなければ上限の引き上げ（最大1000件程度）を検討する。

## 結果
### ポジティブ
- 同期処理でのタイムアウトリスクを限定できる
- ファイル受付時点でエラーにするため、無駄な処理の実行を防げる

### ネガティブ
- 500件を超えるデータは複数ファイルに分割して登録する必要があり、
  ユーザーの操作コストが増える

## 備考
- 現行の1件登録処理時間から計算すると、500件でも十数秒以内に収まる見込み（要検証）
- まず500件でスタートし、実運用で問題がなければ将来的に1000件まで引き上げることを
  メンバー間で合意した

ADRのネタからフォーマットに従って埋めるのは大変ですが、Copilotを使えば短時間でたたき台を作成してくれます。
今回は出力されませんでしたが、該当する情報が無い時は【要確認】が表示されます。
【要確認】の箇所は補ったり、不要であれば項目自体を削除してください。

導入Step 3: search-adr で関連するADRを探す

スラッシュコマンドの/search-adrは改修の前に使います。
/search-adrにキーワードや質問を指定することで、Copilotが過去のADRから該当する情報を探してくれます。

呼び出し方は次のとおりです。

/search-adr
[キーワードや質問を入力する]

入力例です。

/search-adr
CSVインポートの上限件数に関する判断理由が知りたい

するとCopilotから以下のような回答が返ってきます。

## 該当ADR：1件
---

### ADR-0001-CSVインポート機能の件数上限を1ファイル500件にする.md
**日付**：2026-04-xx

**決定内容**
1ファイルあたりの上限を500件とし、超過した場合は受付時点でエラーとして
登録処理を開始しない。
件数上限を設ける理由は、同期処理で実装しているためタイムアウトリスクを
限定するためである。
現行の1件登録処理時間から試算すると500件でも十数秒以内に収まる見込みで、
実運用で問題がなければ将来的に1000件程度まで引き上げを検討する。

該当のファイルがあれば、参照元のファイル名と決定内容を記載するようにしています。
参照元のファイルを確認すれば、さらに詳細な情報を確認することができます。

ADRの運用ポイント

ここまでADRの導入ステップを記載しましたが、これなら「議事録をそのまま残せば良いのでは？」と思った方がいるかもしれません。

確かに、今ではオンライン会議の内容を文字起こしして、さらに議事録を残すことが容易になりました。
ただ議事録で管理すると、複数の話題が混在していて、背景などの欲しい情報を見つけづらくなったり、別な情報の決定内容を誤って参照してしまうことがあります。

そこでADRのポイントはこちらです。

まとめ

コードや仕様書から実装内容は追えても、判断理由まではたどれないことがあります。

ADRは、そうした重要な判断とその背景を、1テーマずつ残していく記録です。完璧な設計文書を目指すよりも、あとから判断理由がたどれるよう状態にしておくことが大切です。

こうした記録を積み重ねておくと、数か月後の改修や担当者交代の際にも、調査にかかる時間を減らしやすくなります。Copilotを使えば、ADRの作成や参照の負担を下げながら、運用も続けやすくなります。

最初からすべてを整える必要はないので、まずは直近の検討会メモをもとに、最初のADRを作ってみてください。

株式会社インフォメーション・ディベロプメント
株式会社インフォメーション・ディベロプメント

株式会社インフォメーション・ディベロプメントは、システム構築・運用実績を持つ独立系ITサービス企業です。「Waku-Wakuする未来創りに参加する」というグループミッションのもと、ビジネス基盤となるAIに関する技術情報や、現場で役立つ実践的な活用ノウハウを発信していきます。

Discussion