📆
アーキテクチャ設計書を時間軸で整理する
アーキテクチャ設計書の章立てについて、時間軸で整理すると良いよ、という提案です。
こんな記事↓を書いたばかりだけど、「アーキテクチャ」設計書について書きます。
章立て例
説明より例示がわかりやすいと思うので、いきなり例を置きます（ありがとう、gemini）
(1) 概要
システムの目的と背景、システムの全体像、などなど
(2) システムコア設計（長期安定）
- 変更頻度: 3年以上 / ほとんど変更なし
- 目的: 変更コストが非常に高く、システムの根幹をなす要素を定義する。
- 内容(例):
- 技術スタックのコア: 主要なプログラミング言語、フレームワーク、データベース。
- アーキテクチャパターン: モノリス、マイクロサービス、レイヤードアーキテクチャなど。
- 認証・認可基盤: ユーザー認証の仕組み、権限管理。
- セキュリティポリシー: データ暗号化、アクセス制御などの全体方針
(3) サービス基盤設計（中期進化）
- 変更頻度: 1〜3年
- 目的: ビジネスや技術の進化に合わせて計画的にアップデートしていく要素を定義する。
- 内容(例):
- CI/CDパイプライン: ビルド、テスト、デプロイメントの自動化戦略。
- 監視・ロギング基盤: 使用するツール、ログの収集・分析方法。
- テスト戦略: 自動テストの種類、カバレッジの目標。
- データ連携基盤: ETL（データ抽出・変換・格納）パイプライン、メッセージキュー。
(4) 運用・改善設計（短期変動）
- 変更頻度: 数週間〜数ヶ月 / 継続的なチューニング
- 目的: 実際の運用データやフィードバックに基づいて、随時調整・最適化する要素を定義する。
- 内容(例):
- リソースのサイジング: 各サービスのインスタンスタイプ、CPU/メモリの具体的な割り当て。
- 監視・アラート設定: アラートのしきい値、通知先。
- コスト最適化: 予約インスタンスの導入、不要なリソースの削除など。
- デプロイメントパラメータ: デプロイ時のローリングアップデート設定、トラフィックの割合など。
このアプローチのメリット
この構成により、アーキテクチャ設計書は静的なスナップショットから動的な計画書へと進化します。
- 役割の明確化: 各セクションの変更頻度を明示することで、誰がどの情報を担当し、どのくらいの頻度で更新すべきかが明確になります。
- 無駄な更新の排除: 長期的に変わらない部分は頻繁な更新から解放され、短期的に変わる部分だけを集中して管理できます。
- コンテキストの提供: なぜその設計が「短期」なのか、「長期」なのかという時間的なコンテキストが加わることで、将来のエンジニアが意思決定の背景をより深く理解できます。
この分類は、ADR（Architecture Decision Record）の利用とも相性が良いです。特に「長期安定」や「中期進化」に関する重要な意思決定は、ADRとして記録することで、その変更の背景を永続的に残すことができます。
ポイント
- 便宜上の分類であることを明記する
- 何が長期で何が短期か正しく分類するのは難しい
- 作った人の主観で便宜的にならべてあるだけだよ、ということがわかるようにしておく
- 作る時もあんまり長く考えない
- 読んだ開発者に"長期"においてあるものは、長期間触っちゃいけないんだ、と思われてしまう
- そうではなく、決定したときの想定として長期間変わらないだろうと見込んでただけで、変える必要があれば変えていいんだよ、をメンバーに伝える
- 何が長期で何が短期か正しく分類するのは難しい
- だいたい依存関係順に並んでくれて、何から決定すべきか、何に影響するかが読んでてわかりやすい
- 長期のものが短期のものに依存することはない（当然といえば当然）ため
Discussion