【要約】AI Readyな設計書を目指して。人もAIも読みやすい設計書管理 [Qiita_Trend] | Summary by TechDistill
> Source: Qiita_Trend
Execute Primary Source
// Problem
開発チームがConfluenceで設計書を管理する中で、AI活用やレビュー効率に課題を感じた。従来の管理手法では、以下の問題に直面していた。
- ・AI（MCP経由等）による設計書の取得や更新コストが高い。
- ・設計書の本文と図をまとめて扱うのが困難である。
- ・コードレビューの流れの中で、設計書の差分を視覚的に確認しづらい。
// Approach
Markdownベースの管理と、GitHub Actionsによる自動ビルド・公開の仕組みを構築した。人間とAIの両方に最適化するため、以下の手法を採用している。
- ・MkDocs Materialを用い、Markdownを検索性の高いHTMLサイトへ変換する。
- ・Mermaidを採用し、GitHub上での図解表示と差分管理を両立させる。
- ・GitHub Actionsにより、Mainへのマージで本番公開、PR作成時にプレビューURLを自動生成する。
// Result
人間とAIの両方に最適化された設計書管理環境を実現した。具体的な成果は以下の通りである。
- ・AIがテキストベースの設計書を容易に読み取れる環境を構築した。
- ・PRごとにプレビューサイトを生成し、図や表の表示崩れをレビュー前に確認可能にした。
- ・設計書の変更を、コードと同様のPull Requestフローで管理できるようになった。
Senior Engineer Insight
> 設計書を「コードと同等の資産」と定義する思想は、開発体験（DX）の観点から極めて合理的だ。特にPRプレビューの自動生成は、図解を含む設計書のレビュー品質を担保する上で非常に実戦的である。ただし、ドキュメントの肥大化に伴うビルド時間の増大や、GitHub Pagesの容量制限には留意が必要だ。AI Readyな構成は、今後の開発プロセスにおいて標準的な要件となるだろう。