なぜアーキテクチャドキュメントがモダンチームにとって重要なのか
エンジニアキャリアで最悪の四半期の話をさせてください。
2019年のことでした。フィンテックスタートアップのコアプラットフォームチームのテックリードをしていました。美しいマイクロサービスアーキテクチャがありました——23のサービス、イベント駆動、適切に分離。システムは順調に動いていました。すべてがどう動くか正確にわかっていました。
そして3つのことが立て続けに起きました：
- Sarah（プリンシパルエンジニア）が FAANG 企業に転職
- Marcus（決済統合を構築した人）が競合にヘッドハンティングされた
- Lisa（レガシーの照合サービスを唯一理解していた人）が長期の病気休暇に入った
6ヶ月以内に、アーキテクチャに関する組織知識の半分が会社を去りました。そしてドキュメントはほぼ皆無でした。
その後の数ヶ月は、自分たちのシステムのリバースエンジニアリングでした。1週間で終わるはずの機能が1ヶ月かかりました。既存のコードがどう動くかをまず理解しなければならなかったからです。特定の設計決定の微妙な理由を理解していなかったためバグを生み出しました。忘れていた制約と矛盾するアーキテクチャ変更を行いました。
あの経験が、私をドキュメント懐疑論者からドキュメント布教者に変えました。突然ドキュメントを書くのが好きになったわけではありません。ドキュメントがないと何が起こるかを身をもって体験したからです。
ドキュメント不在の本当のコスト
貧弱なドキュメントが何をもたらすか正直に話しましょう。漠然とした「重要です」ではなく、私が目撃した具体的な影響で。
オンボーディング時間
あのフィンテックでは、新しいエンジニアが生産的になるまで4-6ヶ月かかりました。彼らが賢くないからではなく——優秀でした——システムを理解するには、長年の部族知識を浸透により吸収する必要があったからです。
ドキュメントに投資した後、それは6-8週間に短縮されました。同じレベルのエンジニア、同じ複雑さのシステム。唯一の違いは、盲目的にさまようのではなく地図があったことです。
計算はシンプルです。年に5人のエンジニアを雇い、それぞれが立ち上がりに3ヶ月を無駄にすると、年間15人月の損失です。シニアエンジニアの給与で計算すると、毎年25万ドル相当の生産性損失になります。
意思決定の遅延
ドキュメントがなければ、すべてのアーキテクチャ議論がゼロから始まります。
「ここで RabbitMQ の代わりに Kafka を使っているのはなぜ？」
誰も知りません。2時間議論しましょう。
「サービス A からサービス B への同期呼び出しを追加できる？」
存在するかもしれない何かの制約次第です。1日かけて調査しましょう。
「決済サービスがダウンしたら何が起こる？」
良い質問です。1週間かけてコードを追跡しましょう。
アーキテクチャのコンテキストがドキュメント化されていれば、これらの質問には答えがあります。常に即座の答えではないかもしれませんが、少なくともどこを探せばいいかわかります。意思決定サイクルが数週間から数日に縮まります。
インシデント対応
午前2時。ページャーが鳴る。チェックアウトフローが失敗している。あなたはオンコールエンジニアで、入社してまだ2ヶ月。
ドキュメントがなければ、システムが炎上している最中に、必死にコードを grep して理解しようとします。決済フローを知っている人が起きていることを祈りながら Slack チャンネルで ping します。
ドキュメントがあれば、システムアーキテクチャを開き、チェックアウトフローの仕組みを確認し、関与するサービスを特定し、問題の原因を探す場所がわかります。このまさにシナリオ用のトラブルシューティングランブックが見つかるかもしれません。
両方の立場を経験しました。平均復旧時間の差は劇的です。
技術的負債の蓄積
何度も見てきたパターンがあります：
- チームがうまく設計されたシステムを構築する
- ドキュメントが存在しないか古くなる
- 新しいエンジニアが参加し、アーキテクチャを理解しない
- アーキテクチャ原則に違反する機能を追加する
- 技術的負債が蓄積する
- 最終的に誰かがリライトを提案する
リライトが常に必要なわけではありません。多くの場合、元のアーキテクチャは問題なかった——理解されていなかっただけです。ドキュメントがなければ、すべてのアーキテクチャ原則はチームの入れ替わり1回分で忘れ去られる距離にあります。
良いドキュメントとは実際にどのようなものか
ドキュメントのためのドキュメントは無意味です。誰も読まない数百ページのドキュメントを生産するチームを見てきました。鍵は、正しいことを正しい方法でドキュメント化することです。
「何を」だけでなく「なぜ」をドキュメント化する
コードはシステムが何をするかを示します。ドキュメントはなぜそうするのかを説明すべきです。
なぜ MongoDB ではなく PostgreSQL を選んだのか？なぜこれらのサービスは統合されずに分離されているのか？なぜこのエンドポイントはこの特定のフォーマットを受け入れるのか？
これらの「なぜ」の質問には答えがありますが、コードにはありません。決定を下した人々の頭の中にあります。書き留めなければ、その人たちが去ったときに失われます。
発見可能に保つ
最高のドキュメントも誰も見つけられなければ無意味です。私たちのフィンテックには実はドキュメントがありました——どこからもリンクされていない Confluence スペースに埋もれて、検索機能もほとんど機能していませんでした。
ドキュメントは以下であるべきです：
- コードからリンクされている（README ファイル、ドキュメントリンク付きコードコメント）
- 論理的に整理されている（時系列にダンプされただけではなく）
- 検索可能（すべてのドキュメントの全文検索）
最終的にアーキテクチャドキュメントをリポジトリ自体に移しました。今ではコードレビューに表示され、コードとともにバージョン管理され、現実から大きく乖離できなくなりました。
メンテナンス可能にする
更新が苦痛なドキュメントは更新されません。
これが、精巧な UML ダイアグラムに懐疑的な理由です。作成時は美しいのですが、更新に専門的なツールとスキルが必要なため、6ヶ月後には絶望的に古くなっています。
シンプルなフォーマットの方がうまくいきます：
- 誰でも編集できる Markdown
- コードとともに存在するテキストベースのダイアグラム（Mermaid、PlantUML）
- 意図的にメンテナンスが簡単な C4 ダイアグラム
メンテナンスされるドキュメントは、メンテナンスが簡単なドキュメントです。
複数のオーディエンスを対象にする
異なる人々は異なるレベルの詳細を必要とします。
新しいエンジニアにはシステム概要が必要です。プロダクトマネージャーにはサービス境界の理解が必要です。アーキテクトにはコンポーネント関係が見える必要があります。オンコールエンジニアには運用情報が必要です。
C4 モデルはここでうまく機能します。なぜなら、異なるズームレベルを明示的に提供するからです。エグゼクティブにはシステムコンテキスト、アーキテクトにはコンテナダイアグラム、開発者にはコンポーネントダイアグラム。
ドキュメント化を始める実践的ステップ
ゼロから始めるなら、私が効果的だと思うアプローチは以下です：
第1週：システムコンテキスト
数時間かけて以下を示す1つのダイアグラムを作成：
- システムを1つのボックスとして表現
- 誰がそれを使っているか
- どの外部システムに接続しているか
これだけでも価値があります。境界を確立し、新しいチームメンバーに出発点を与えます。
第2週：コンテナダイアグラム
システムをデプロイ可能な部品に分解：
- サービス、アプリケーション、データベース
- どう通信するか
- 何のテクノロジーを使っているか
これがインフラの議論とオンボーディングのリファレンスになります。
第3週：重要な決定
最も重要な3つのアーキテクチャ決定をドキュメント化：
- 何が決定されたか
- なぜそう決定されたか
- どんな代替案が検討されたか
これにより古い議論の蒸し返しを防ぎ、新しいチームメンバーがシステムの形状の背後にある根拠を理解する助けになります。
以降：ワークフローの一部として
初期のドキュメントは簡単な部分です。最新の状態に保つことの方が難しい。
ドキュメントを完了の定義の一部にしてください。PR がアーキテクチャを変更するなら、関連するドキュメントを更新すべきです。これは自動的には起こりません——レビューの規律と文化的なコミットメントが必要です。
自動化チェックを追加するチームもあります：README ファイルの存在を検証する CI ジョブ、「この変更はアーキテクチャを変更しますか？もしそうなら、ドキュメントを更新しましたか？」と尋ねる PR テンプレート。
文化的な課題
正直に言うと、チームにドキュメントを書かせることは多くの場合、文化的な戦いです。
エンジニアは一般的にドキュメントを書くよりコードを書く方を好みます。ドキュメントはアウトプットではなくオーバーヘッドに感じられます。締め切りが迫ると、ドキュメントが最初にカットされます。
私が有効だと思ったこと：
個人的なものにする
新しいエンジニアが参加したら、オンボーディング中に学んだことをドキュメント化するよう頼みましょう。彼らは新鮮な目でシステムを見ており、ベテランが見逃すギャップに気づきます。そして、自分たちが存在してほしかったドキュメントから直接恩恵を受けます。
ドキュメントを称える
スプリントレビューでドキュメントの更新に言及しましょう。良いドキュメントを維持するエンジニアを認めましょう。ドキュメントが単に許容されているのではなく、価値があることを可視化しましょう。
可能な限り自動化
必要な手動ドキュメントが少ないほど、実際に行われる可能性が高くなります。コードからドキュメントを生成するツールを使いましょう。AI で初稿を作成しましょう。自動的に更新されるダイアグラム・アズ・コードを使いましょう。
これが私が Archyl を構築した理由の一部でもあります。アーキテクチャドキュメントの作成とメンテナンスの手動オーバーヘッドは大きな障壁です。AI 支援のディスカバリーとビジュアル編集がその障壁を下げます。
痛みと結びつける
人は痛みを感じたときに行動を変えます。次に誰かがドキュメントがないためにシステムの理解に何日も費やしたら、指摘してください。「ドキュメントがあれば、これは1時間のタスクだったのに。」
結論
ドキュメントはエキサイティングではありません。私たちがソフトウェアエンジニアリングに入った理由ではありません。しかし、それは創造者がいなくなっても生き残るシステムと、メンテナンス不能な混乱になるシステムの違いです。
先ほど述べたフィンテック？あの辛い時期の後、私たちはドキュメントに真剣に投資しました。アーキテクチャダイアグラム、決定記録、ランブック、すべて。約6ヶ月の集中的な取り組みが必要でした。
次に誰かが去ったとき、チームへの混乱はほとんどありませんでした。彼らの知識は頭の中だけでなく、システムの中にあったからです。
ドキュメントとは本当はこういうものです：知識喪失に対する保険。そしてすべての保険と同じように、必要になるまで高く感じるのです。
ドキュメントの旅を続ける：C4 モデル入門 | アーキテクチャ決定記録 | ユーザーフローのドキュメント化