こんにちは。
2週目のテックブログを書かせていただくことになりました、
AI SaaS事業本部VPoEの小田川です。
今回は燈で採用している開発フローの一つ、ADRについて話をさせていただければと思います。
ADR (Architecture Design Record) とは何か
ADR、聞き慣れない方も多いと思います。
何かというとソフトウェアの開発時に予め何をどう設計するかということを決めておく文書になります。
全てのエンジニアはDBやインフラ等に何かしらの変更を加える際には必ず以下のフォーマットで書くようにしています。
特に、同じ機能を実現するのに複数の設計方針が立つことは多いと思っていて、その時にどうしてその中から1つを選ぶことにしたのか、それを議論し、記録しておく文書になります。
なぜ行うのか
主に以下の2点です。
- 実装前にベストな技術選定を行うため
- あとでなぜ今の仕様になっているのか振り返るため
1. 実装前にベストな技術選定を行うため
ADR（Architectural Decision Record）を実装前に作成することは、ベストではない方針での実装が進んでしまうことを防ぐ重要な役割を果たします。特に、Slackなどの非構造的な議論にとどめるのではなく、ADRというフォーマットを用いて文書として記録することで、決定事項を明確にし、チーム全体の理解を統一することが可能になります。
燈では、一定以上の難易度（データベースのマイグレーションを含むタスク以上）の開発に関しては、ADRの作成を必須としています。これにより、すべてのメンバーがアーキテクチャや技術選定に対する意識を高め、より良い設計判断を行えるようにしています。
ADRを事前に作成することで得られるメリットには、以下のようなものがあります。
- 方針の早期レビュー: 実装開始前にレビューを受けることで、非効率的または適切でない設計方針を避けられる。
- 設計の透明性: チーム全体が決定の背景を理解しやすくなり、意思決定のスピードが向上する。
- 議論の構造化: 記録が明確になることで、無駄な議論を減らし、実装者が迷わず作業に集中できる。
2. あとでなぜ今の仕様になっているのか振り返るため
機能拡張や変更の際には「現在の仕様」がどのような背景で決定されたのかを理解することが重要です。ADRを適切に記録しておくことで、過去の検討内容を参照し、意思決定のスピードを向上させることができます。
過去のADRが重要になる理由
- 背景情報の明確化: 仕様決定の背景を記録しておくことで、拡張時の判断基準を明確にする。
- 一貫性の確保: 新しい仕様を追加する際に、既存の仕様と矛盾が生じないようにする。
- リファクタリングの判断材料: もし現在の仕様に問題がある場合、適切にリファクタリングするための情報を提供する。
仕様変更や機能追加時に、過去のADRがあることで、以下のような効果が期待できます。
- コードのみを見てゼロからアーキテクチャを分析する手間が省ける。
- すでに議論された内容を再調査する必要がなくなる。
- 検討の履歴が明確になることで、迅速かつ適切な意思決定が可能になる。
過去にどのような議論が行われ、どのような理由で現在の仕様に決まったのかという情報は、時間が経つとともに忘れ去られがちです。これを防ぐために、ADRという仕組みを活用し、いつでも参照できる状態にしておくことが極めて重要です。
燈では、以下の写真のようにNotionのデータベース機能を用いて一覧できるようにしています。
テンプレート
燈で使っているフォーマットは以下の通りです。このフォーマットは、意思決定のプロセスを明確に記録し、議論の余地や背景を後から振り返りやすくするために設計されています。この中では特に「検討した代替案」のところが重要で毎回notionコメントで活発な議論が行われます。
# コンテキスト （これが必要になった背景．タスクのnotionのリンクを張るなど） ## 決定内容 ## 根拠 ## 結果 （この決定によってもたらされる便益など） ## 実装計画 （実装内容をDB・バックエンド・フロントエンドごとなどに分けて書く） ## 検討した代替案 ## 関連する決定
実際に運用してみて
まず感じているのが、全エンジニアのキャッチアップや技術への解像度がこれによって底上げされているということです。ADRを書くことで、既存実装の知識のあるメンバーにアドバイスされるままに実装するのではなく、入社時期にかかわらず各メンバーが主体性を持ってアーキテクチャを考えることになります。そうすると、必然的に「なぜこの選択をするのか」「何を今やっててこれが正しい方針だと確信できているか」などを考えることになります。このプロセスを通じて、全員が迅速に技術的なキャッチアップを実現できています。
最近ではLLM（大規模言語モデル）の登場で、エンジニアがアーキテクチャの調査にかかる手間が劇的に減っています。LLMで調査してドキュメント化するの一手間で、エンジニアのコーディングの解像度を上げ、意思決定のコミュニケーションを円滑に進め、さらに後から振り返れるADRの仕組みは、便益が大きいと感じています。
We’re Hiring!
燈では、技術力を高めながら成長できる環境を提供しています。ADR文化を通じて、全エンジニアがアーキテクチャ設計や技術選定に主体的に関わり、より本質的な開発経験を積むことができます。 LLMを活用した開発プロセス、オープンな議論文化、そして技術に真剣に向き合うチームと共に、あなたのスキルを次のレベルへ引き上げませんか？
興味がある方は、ぜひカジュアル面談でお話しましょう！ あなたの挑戦を、燈のメンバー一同楽しみにしています🔥
今回の記事を書いた燈メンバー🙌
