アーカイブ動画

アーキテクチャの決定に必要なのは、設計思想、選択・判断した理由

NECソリューションイノベータ株式会社
プラットフォーム事業ライン 
第二ＰＦソフトウェア事業部 シニアプロフェッショナル　中島 剛氏

NECグループのシステムインテグレーターとして、各種システムの構築やITサービスの開発・提供を手掛けるNECソリューションイノベータ。今回登壇した中島剛氏は、同社のシニアプロフェッショナルとして、NECの強みである生体認証の基盤開発に従事している。

生体認証基盤の開発においては、当初は設計や製造といった領域の業務は北米やインドで行い、アジャイル開発で進めていた。日本のチームが行うのは、できあがったシステムを製品化したり、試験や保守・サポートとなる。

だが、昨年より体制が刷新。海外で行っていた設計・製造業務といった領域も、国内のチームで担うようになった。そこで、現地メンバーの開発環境を引き継ぐことになるが、ADO内のメールやチャットでやり取りを進めていたため、設計の背景やドキュメントが散乱している状況であった。

「このままの状態では移管は難しく、引き受けられないと思いました。一方で私はプロジェクトの責任者でしたから、何とか自分たちがきちんと管理できる体制に刷新しようと考えました」（中島氏）

中島氏はまず、自身が携わったメインフレームOS開発時代の状況を検討する。当時はウォーターフォール型の開発であり、設計書はアナログであった。しかし、ファイルでしっかりと管理されており、バグが生じた際など設計書を確認すれば対応できていた。

一方で開発期間が半年〜1年と長く、高価なメインフレームの稼働に合わせてエンジニアが業務シフトを組んでいたため、膨大な時間とコストがかかっていた。そのため、現在の開発体制に導入するのは難しいという判断をした。

中島氏は改めて、アーキテクチャを開発・決定するアーキテクトに求められること、具体的に決定すべき事項などをまとめた以下スライドを示した。

中島氏は、アーキテクチャ決定を拒む阻害要因も示し、大きくは段階により3つあると語る。それぞれにおける対策も重ねて説明し、設計段階における阻害要因は「資産防御アンチパターン」と表現した。選択しない、設計判断を先延ばしにするというパターンである。

決定がなされた後に何度も議論が繰り返されるのも、アンチパターンだと島田氏は指摘する。最後の段階でアーキテクチャが決定したにも関わらず、メールやチャットでのやり取りであったため、実装がうまくいかないパターンである。

対策としては、単一のドキュメントリポジトリで管理する。本当に関心のあるステークホルダーのみ伝えるといったルールの整備が必要だと続けた。

どれくらいの時間をアーキテクチャ設計にかければよいのか。時間をかければかけるほど、その後の修正コストが減ることは明らかではあるが、闇雲に時間をかければいいわけではない、と中島氏は言う。

適切な時間、スイートスポットがあるからだ。スイートスポットはプロジェクトの規模により変わるものであり、10万行前後のプロジェクトにおけるスイートスポットの参考例を示した。

技術的負債についても改めて解説が行われた。技術的負債とは、将来的に修正にかかるコストのことであり、すべてのソフトウェアに存在するため可視化して返済していくことが重要だと、中島氏は強調する。

そして、現在のソフトウェア開発のほとんどが、ゼロからの開発ではなく再設計であり、技術的負債を返済しているという。同業務においては元々の設計判断が必要となってくると語り、アーキテクチャの重要性を次のようにまとめた。

「このようにアーキテクチャを決定するには、元々の設計思想や選択・判断した理由が必要となってきます。プロジェクトの途中から入ったメンバーはもちろん、最初から携わるメンバーでも次第に不明瞭になっていくため、これらを補完する技術が求められます。それが、ADRです」（中島氏）

近年注目が高まる「ADR」の導入法・作成・運用とは

ADRとは「Architecture Decision Records（アーキテクチャディシジョンレコード）」の頭文字を取った言葉であり、ソフトウェア開発プロジェクトにおいて、意思決定や設計上の判断を文書化、その後の開発や修正時に役立てるための軽量ドキュメントである。

ハイプ・サイクルを調べた結果でも、2022年ではアーリーアダプターであったのが、2023年にはアーリーメジャーに移行していることから、近年注目されている技術でもある。

具体的には1～2ページ程度の軽いテキストファイルであり、基本的な構造（構成）が示された参考フォーマットを紹介。なお、あくまでこちらのフォーマットは参考であり、適宜、カスタマイズして使うものだと補足された。

それぞれの項目も詳しく解説された。「タイトル」はそのまま、アーキテクチャを決定する簡単な説明やフレーズを記載する。タイトルには、連番が割り振られる。

「ステータス」では「提案済み」「承認済み」「破棄」といったまさしくステータス状態を記述する。ここで重要なのは破棄されたADRを削除してはならないことだと、中島氏は強調した。

「新しいADRが発行され、承認されたからといって、過去のADRを破棄するようなことはしません。以前はどのような決定がされていたのか。なぜ変更されたかなど、履歴を後から確認できるからです」（中島氏）

続いては、ボディ部分とも言えるタイトル、コンテキスト、決定、影響についてだ。その決定がなされた理由や、アーキテクチャ決定による全体の影響などを文書としてまとめ、記述する。

なおテキストが長くなる場合は別途ドキュメントを作成し、リンクなどを記載するなどして紐づけておけばよいと補足された。

ADRのテンプレートはすでにいくつもあるので、実際にドキュメントを作成するには、それらを参考にすることができる。その上で、自分たちのプロジェクトにマッチした内容にカスタマイズしていくといいと中島氏は語る。

記述ツールはテキストエディタで構わないそうだが、本イベントではADR-Toolsを使い、実際にADRの作成や保存の手順を紹介した。

ADRを作成すると、新たに番号がレコードされ、これまで作成したADRのリストも一覧表示されていることがわかる。そしてここでも島田氏は、先述したポイントを繰り返した。

「新しいADRを作成した場合には、必ず過去のADRのステータスを変えることが重要です。そして、この作業を確実に注意深くやることがポイントです」（島田氏）

中島氏は、テキストエディタでも作成できるが、やはりADR-Toolsのような専用ツールを使うのがベストだと言う。ソースコードと同じようにリポジトリで管理できるため、バージョン管理が容易であるからだ。

ソースコードと紐付けられるため、設計書とソースコードの食い違いの防止につながるなど、理由を説明した。実際、中島氏のプロジェクトでもADR-Toolsを使っているという。

運用においては、明確なルールがあるわけではないと前置きしつつ、参考となる流れを紹介した。以下スライドのように、ADRの利用合意から始まり、作成、議論、承認、採択/却下といったサイクルを、ADRを起票する度にまわしていく。関係者でしっかりと議論した上で、ステータスを決めることが重要だ。

AWSでもADRの利用を推進しており、すでに規範となるガイダンスもある。中島氏は同ガイダンスの内容を引用して紹介した。ガイダンスによれば、導入プロセスにおいては、まずADRの内容の管理や伝達を担う所有者を定義し、プロセスの範囲を明確化する。

作成フローにおいては、同じ議論が繰り返されないよう、拒否の理由を追加する。そして繰り返しになるが、ステータスを変更することを示す。

「検証プロセスでは、コードレビューを行う際に担当者にADRのリンクを共有するなどして、アーキテクチャの内容が確実にソースコードに反映、実装されているかを確認することが重要です」（中島氏）

【導入事例】ADR-Toolsを使いGitでソースコードと同じように管理する

実際に中島氏のチームにADRを導入した実例も紹介された。まずは動作環境である。

Gitで管理することで、ソースコードの管理と同じような手順とした。アーキテクトチームが作成したADRはJenkinsで自動的にデプロイされ、関係する開発者全メンバーが閲覧できる環境となっている。

修正の対応や承認可否についても、ソースコードと同じ手順で行われている。変更や修正を行いたい場合はプルリクエストを発行。ステークホルダーでレビューを行い、採用の可否を決める。承認されれば、メインのブランチにマージされるという流れだ。

ADR-Toolsを使って、ブラウザで管理しているダッシュボードも紹介された。今回の取り組みでは、あくまでごく一部のプロジェクトのため、階層構造としていないが、プロジェクトが複数動いている場合などは、コンポーネントごとに分けた方がよいというアドバイスも語られた。

実際のADR（ドキュメント）も紹介された。まさしくコンテキストの理由となったチケットをリンクされており、新たなレコードを作成したことで、以前のレコードのステータスが変更されていることなどがわかる。

「Gitで管理することで設計物と製造物の齟齬がなくなったのが、一番大きな導入効果だと捉えています」（中島氏）

また、留意点においてはGitで管理しているために、開発者以外のメンバーがリポジトリにアクセスできない場合がある。そのような場合は、GitではなくWikiなどに配置転換を行ったり、リポジトリへのアクセス権を付与したりといった対応を行う。本プロジェクトでは後者で対応したという。

中島氏は、改めてADR導入のメリット・デメリットをまとめて紹介するとともに、「今後は全体のプロジェクトへの適用も考えています」との展望を述べ、セッションを締めた。

【Q＆A】参加者からの質問に登壇者が回答

質問タイムでは、多くの参加者から実務に即する質問が寄せられた。中島氏はその一つひとつに時間の許す限り、丁寧に答えていった。抜粋して紹介する。

Q．「書いて残す」を定着させるコツを知りたい

NECグループでは書いて残すという流れがグループ全体で定着しているので、それほど大変ではありませんでした。一方で、ソースコードと実際の製造にズレがないこと。追従していることが重要なので、しっかり管理することが重要だと思います。

Q．アーキテクチャ以外の決定事項などにも活用できるのか？

はい。テンプレートはあくまでアーキテクチャにおけるテンプレートであり、 用途を限定するものではありません。

Q．導入によりコストが増えると思うが、メンバーにはどのように納得してもらったのか？

基本的には確実に増えます。ただし、困った状態を改善するとの目的があったので導入には皆前向きであり、必然、総意だと捉えています。その都度、場合に応じた運営が必要だと思います。

Q．アーキテクチャの細かな決め事はどのようにドキュメント管理しているのか？

2番目のアジェンダで説明した内容になりますが、構造や非機能要件は必ず記述するようにしています。その他の要素も今回はインフラ設計に限られていましたが、適宜、プロジェクトの内容により書く必要があるでしょう。

我々もまだ手探り状態ですが、ソースコードを書く時間だけでなく、このような規則の記述も工数に加える必要があるのでは。そのようなことも考えています。

Q．ソースコードはドキュメントのどの箇所に関連しているのか、どのように見つければよいのか？

今回のプロジェクトでは、インフラ設計の場合は数が少なく非機能要件ばかりであったこともあり、コンテンツから辿りつくことができます。ソースコードも同じです。チケット管理の場合はチケットから、または相互リンクなどからADRの該当箇所を辿ります。

Q．フロント、バック、インフラなどは、システムにおける全決定事項を記載するのか？

全部書くこと、そして階層化するといいと思います。まずは取り組みやすい領域からでよいと思います。

Q．サブディレクトリの作成など、階層管理はされているか？

今回のケースでは管理していませんでしたが、反省点でもありました。サブディレクトリでの管理が必要だと思います。

Q．OneNoteやWordへの記載からADRに移行するためのポイントは？

図なども含め、WordやPowerPointなどに設計条件などを記述する人もいますが、そのような業務はこれまでと変わらず行います。ADRの導入はゼロイチの話ではなく、あくまで従来のドキュメントに付随して行います。

Q．アーキテクチャ以外の決定事項はどのようなかたちで残しているのか？

決定事項は議事録的にADRに起票します。その上で、例えば役員にプレゼンテーションする場合は、PowerPointを作って説明するといった対応をしています。

Q．リポジトリで管理するのは重要なポイントなのか？

リポジトリでなくても構いません。テキストベースだと気軽に記述できます。今回のプロジェクトではしっかりと運用したかったので、起票と同時にメールで連絡が飛ぶGitを選びました。運用がしっかりと行えるのであれば、Wikiなど他の手法でもよいと思います。

NECソリューションイノベータ株式会社
https://www.nec-solutioninnovators.co.jp/

NECソリューションイノベータ株式会社の採用情報
https://www.nec-solutioninnovators.co.jp/career/