---
title: AIが設計書を歴史書にする前に
tags: 
author: [Kazuki Ota](https://docswell.com/user/okazuki)
site: [Docswell](https://www.docswell.com/)
thumbnail: https://bcdn.docswell.com/page/LELMDWXM7R.jpg?width=480
description: プロダクト開発、AIに丸ごと任せられるのか？Meetup Spec/Issue駆動知見を語り尽くす！の登壇資料です。
published: July 29, 26
canonical: https://docswell.com/s/okazuki/K1QW7R-2026-07-29-095529
---
# Page. 1

![Page Image](https://bcdn.docswell.com/page/LELMDWXM7R.jpg)

ARCHITECTURE DECISION RECORD
AIが設計書を歴史書にする前に
現在の仕様と判断履歴を分けるコンテキスト設計
AIが設計書を歴史書にする前に
1 / 22


# Page. 2

![Page Image](https://bcdn.docswell.com/page/4JMYP9L6JW.jpg)

PROFILE
自己紹介
大田 一希 (Kazuki Ota)
Microsoft ／ Cloud Solution Architect & Evangelist
X: @okazuki
zenn: https://zenn.dev/okazuki
AIが設計書を歴史書にする前に
2 / 22


# Page. 3

![Page Image](https://bcdn.docswell.com/page/PJR91GKN79.jpg)

WHY DOCUMENTATION
ドキュメントは大事
全体の設計方針
レイヤー分割方針
テストの方針
etc...
細かい詳細設計よりも、全体方針を決めるドキュメントを重視。
AIが設計書を歴史書にする前に
3 / 22


# Page. 4

![Page Image](https://bcdn.docswell.com/page/PEXQYXL8JX.jpg)

THE PROBLEM
AI が書くドキュメントあるある
ドキュメントが過去の経緯で埋まる
XXXXX は YYYYY をしていたが、ZZZZZ の理由により現在は AAAAA を使用している。
XXXXX の時には BBBBBB をしていて（以下最新の状態には関係ない説明が続く…）
AIが設計書を歴史書にする前に
4 / 22


# Page. 5

![Page Image](https://bcdn.docswell.com/page/3EK93WLLED.jpg)

THE PROBLEM
AI が書くドキュメントあるある
コードのドキュメントコメントにまで！？
/// <summary>
/// 何かをするメソッド。
/// 従来は XXXXX でやっていたが大規模なデータを扱えないため YYYYY で
/// 実装することになった。
/// </summary>
public Task DoSomethingAsync()
{
...
}
AIが設計書を歴史書にする前に
5 / 22


# Page. 6

![Page Image](https://bcdn.docswell.com/page/L73WG13675.jpg)

FIRST ATTEMPT
読むのが辛い！！最新情報だけでいい！！
ドキュメンテーションルールを定義
SKILL.md にルールを追記
ドキュメントには過去の経緯を含めず最新のスナップショットだけを
含めるようにしてください。
AIが設計書を歴史書にする前に
6 / 22


# Page. 7

![Page Image](https://bcdn.docswell.com/page/87DK1X4MJG.jpg)

FIRST ATTEMPT
🎉問題解決🎉
ドキュメントはスッキリして読みやすくなった
XXXXX は AAAAA を使用している。
/// <summary>
/// 何かをするメソッド。
/// </summary>
public Task DoSomethingAsync()
{
...
}
AIが設計書を歴史書にする前に
7 / 22


# Page. 8

![Page Image](https://bcdn.docswell.com/page/VJPKQPMQE8.jpg)

THE NEXT PROBLEM
AI が同じ間違いをするようになった
素直に考えれば正しい実装を選ぶ
しかし制約で使えない方法を選択してしまう
エラーが発生し、迷走して解決することが多発
トークンも無駄に消費し、毎回の指摘に疲れる
AIが設計書を歴史書にする前に
8 / 22


# Page. 9

![Page Image](https://bcdn.docswell.com/page/2EVV529PEQ.jpg)

RESPONSE
対応策
ADR を導入してみた
AIが設計書を歴史書にする前に
9 / 22


# Page. 10

![Page Image](https://bcdn.docswell.com/page/57GL6RZQEL.jpg)

ARCHITECTURE DECISION RECORD
ADR
Architecture Decision Record
新しいものではなく、昔からあるやり方
Microsoft、AWS、Google の公式ドキュメントでも紹介
AIが設計書を歴史書にする前に
10 / 22


# Page. 11

![Page Image](https://bcdn.docswell.com/page/4EQY4VLWJP.jpg)

ARCHITECTURE DECISION RECORD
ADR
アーキテクチャ決定レコード (ADR) は、ソリューション アーキテクトの最も重要な成果物の 1 つです。
引用: アーキテクチャデシジョン レコード (ADR) を維持する
AIが設計書を歴史書にする前に
11 / 22


# Page. 12

![Page Image](https://bcdn.docswell.com/page/KJ4WQMD171.jpg)

DEFINITION
ADR とは
重要な設計判断を決まった形で残す
AIが設計書を歴史書にする前に
12 / 22


# Page. 13

![Page Image](https://bcdn.docswell.com/page/LE1YP8Z57G.jpg)

WHAT TO RECORD
ADRに残すもの
判断したこと
そのときの状況と理由
却下した代替案
影響やトレードオフ
AIが設計書を歴史書にする前に
13 / 22


# Page. 14

![Page Image](https://bcdn.docswell.com/page/GEWG2Z9WJ2.jpg)

DECISION CRITERIA
ADRを書く判断基準
次のどれかに当てはまる決定
全体の構造に影響 — アーキテクチャ・プロジェクト構成
開発全体に影響 — 開発プロセス・主要ツール
戻すコストが高い — データ永続化・外部連携
変数名や private メソッド分割など、些細な実装詳細は ADR 化しない。
AIが設計書を歴史書にする前に
14 / 22


# Page. 15

![Page Image](https://bcdn.docswell.com/page/47ZLD192J3.jpg)

TEMPLATE
実際の ADR テンプレート
## Status
Proposed / Accepted / Superseded / Deprecated
## Context
背景・制約・代替案と却下理由
## Decision
決定内容と適用範囲
## Consequences
メリット・トレードオフ・影響
AIが設計書を歴史書にする前に
15 / 22


# Page. 16

![Page Image](https://bcdn.docswell.com/page/YJ6W1LD6JV.jpg)

EXAMPLE
実際の ADR 1
AIが設計書を歴史書にする前に
16 / 22


# Page. 17

![Page Image](https://bcdn.docswell.com/page/GJ5M4135J4.jpg)

EXAMPLE
実際の ADR 2
AIが設計書を歴史書にする前に
17 / 22


# Page. 18

![Page Image](https://bcdn.docswell.com/page/9E29V1ZG7R.jpg)

IMPACT
ADR の効果
AI が同じ間違いをしなくなった
ドキュメントが見やすくなった
ADR がある Pull Request は注意して見るべき指標になった
AIが設計書を歴史書にする前に
18 / 22


# Page. 19

![Page Image](https://bcdn.docswell.com/page/D7Y43ZRGEM.jpg)

TEAM DEVELOPMENT
チーム開発では…？
ADR の追加判断をもう少し明確化する必要がある
矛盾する ADR が入ることがある
全体監督をするアーキテクトがやはり必要そう
AIが設計書を歴史書にする前に
19 / 22


# Page. 20

![Page Image](https://bcdn.docswell.com/page/VENYV3D8J8.jpg)

SCALE
ADR が増えすぎると…
ADR を効率よく探す仕組みが必要になるかも？
CLI / MCP Server / etc...
AIが設計書を歴史書にする前に
20 / 22


# Page. 21

![Page Image](https://bcdn.docswell.com/page/Y79P69GXE3.jpg)

TAKEAWAYS
まとめ
ADR を入れて設計判断と最新の設計スナップショットを分離
AI が書いてくれるなら ADR の継続も可能
ADR が多くなったときの対応は何か必要そう
AIが設計書を歴史書にする前に
21 / 22


# Page. 22

![Page Image](https://bcdn.docswell.com/page/G78DZ9V97D.jpg)

THANK YOU
ご清聴ありがとうございました
AIが設計書を歴史書にする前に
22 / 22