AIが設計書を歴史書にする前に

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

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

• https://zenn.dev/okazuki

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

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

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

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

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

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

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

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

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

• https://learn.microsoft.com/ja-jp/azure/well-architected/architect-role/architecture-decision-record

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

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

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

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

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

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

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

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

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

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

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