/note/tech

ソフトウェア開発における施策単位ドキュメント設計のメモ

■ 1. 案件・施策単位ドキュメントの構造的問題

• 全体像の喪失: 案件単位の記述は「差分の記録」となり、システムの現在状態を示すドキュメントが存在しない状態に陥る
• 設計の重複・矛盾: 複数案件が同一コンポーネントに言及する場合、記述が相違し「現在の正」が一点に定まらなくなる
• 陳腐化の不可視性: 後続案件でアーキテクチャが変化しても古いドキュメントが残存し、情報の有効性を判断する手がかりがない
• 横断的設計判断の欠落: アーキテクチャ選定の理由やトレードオフは案件単位では記録しにくく埋もれやすい
• 参照コストの増大: 特定機能の設計情報を得るために複数案件ドキュメントを横断検索する必要が生じる

■ 2. 案件単位スタイルが普及する背景

• 書きやすさ: 案件スコープが明確であり着手しやすい
• レビューしやすさ: 変更差分として議論できる
• 慣習との親和性: チケット・PR単位の開発文化と相性がよい
• リソース制約: 包括的ドキュメントを作成する時間的余裕がない

■ 3. 対処アプローチ: 二層構造による管理

• Living Document（常に現在状態を示す）とADR（案件単位の意思決定記録）を分離して運用する二層構造が理想
• Living Document:
  • アーキテクチャ、データモデル、API仕様などをコンポーネント単位で管理
  • 案件完了時に更新するルールを徹底する
• ADR（Architecture Decision Record）:
  • 「なぜその設計にしたか」という意思決定のみを案件単位で記録する
  • 案件ドキュメントは「変更ログ」と位置づける

■ 4. ADR + AI現状調査の組み合わせの合理性と残課題

• 論点: システムの現状調査はAIエージェントに任せることで随時の調査コストは許容可能な水準になる
• 合理性:
  • AIエージェントにより現状調査コストが低下したため、Living Documentのメンテナンスコストの相対的価値が下がっている
  • 意思決定記録（ADR）と都度AI調査の組み合わせは筋が通っている
• 残る問題点:
  • AIが調査できない情報: コードやDBスキーマから読み取れない「なぜそうなっているか」「何を諦めたか」「設計の前提条件」はADRで補完する必要がある
  • AI調査結果の信頼性: 誤読・見落としの検証コスト、複雑な依存関係や暗黙のビジネスルールへの対応が課題として残る

■ 5. 情報散在の問題とSSOT実現のアプローチ

• 問題の実態:
  • 個々人が自由にドキュメントを書き散らすことで情報が分散している
  • Slack、Confluence、Google Doc、PR説明欄、Notionなど複数の場所に情報が散在し、施策の設計情報の所在が不明確になる
• SSOT実現の本質的課題:
  • 「ここに書く」というルールより「ここ以外に書かない」という制約の方が重要
  • ルールだけでは自然発生的な情報分散を防げない
• 現実的アプローチ:
  • 施策ごとにドキュメントの「入口ページ」を先に作る運用にする
  • Slack・PR・議事録は一次情報置き場と割り切り、SSOTへの転記を完了条件とする
  • チケットやレビューのDone定義にSSOT更新を含める
• 残る摩擦:
  • 転記・集約作業自体がコストになる
  • 集約責任の所在が曖昧になりやすい

■ 6. アプリとサーバサイドの同一ファイル化

• 施策単位のSSOTとして、アプリとサーバサイドの情報を章立てを分けて同一ファイルに記載することが適切
• 一体化の理由:
  • 読み手が「施策でシステム全体として何が変わるか」を一箇所で把握できる
  • 別ファイル分割では全体像把握のために複数ファイルを行き来する必要が生じる
  • API変更、影響範囲の前提共有、IF設計の理由などはアプリ・サーバ双方の文脈で参照する必要がある
• 推奨章立て構成:
  • 背景・目的
  • 要件・スコープ
  • 設計概要（全体図）
  • アプリ（画面・UX変更、実装方針）
  • サーバサイド（API変更、DB変更、実装方針）
  • 意思決定記録（ADR的なもの）
  • 残課題・考慮しなかったこと
• 注意点: アプリ専任・サーバ専任がいる場合、「自分に関係ある章だけ見ればよい」という共通認識を形成し、章の独立性を明確にする

■ 7. 同一ファイル化による結合段階の認識ズレ防止効果

• 従来の問題: サーバ・アプリ担当者が別々にドキュメントを書くことで、結合段階に至るまで認識のズレが発覚しない失敗が頻発していた
• 同一ファイル化による解決:
  • 書く段階で強制的に相手の章を目にするため、パラメータの不足やエラーハンドリングの想定外が結合前に発覚する
  • ドキュメントがコミュニケーションのインターフェースとして機能する
• さらに効果を高める方法: アプリ・サーバ間インターフェース（エンドポイント一覧、リクエスト・レスポンス定義、エラーケース）を独立した章として設け、双方が共同レビューする対象と位置づける
• 構造的変化: 事後的な整合（結合時に突き合わせる）から事前の整合（共にドキュメントを育てながら書く）へ移行する

■ 8. デザインドックとの対応関係

• 施策・機能単位でドキュメントを作成するという方向性はGoogleのデザインドックの考え方とほぼ一致する
• Googleのデザインドックとの相違点:
  • Googleのデザインドックは実装前の設計・承認プロセスとして機能することが多く、実装後は更新されないことも多い
  • 今議論している運用は「実装前の設計合意」「意思決定の記録（ADR的役割）」「結合時の認識ズレ防止」の複数目的を持つ
• 位置づけ: デザインドックをベースにADRの要素を加えた形式が適切
• 導入上のメリット: 「デザインドック」という言葉を用いることで「Googleも実施している標準的プラクティス」として説明でき、チームへの納得感を得やすい

(2026/06/12)