okuzawatsの日記

Android / Kotlin / GitHub Actions Enthusiast 🤖

ADR-Toolsを使ってADR(Architecture Decision Record)を作る

profile

書いている人 モバイルアプリケーションアーキテクト(Android)として働いています。モバイルアプリケーションのアーキテクチャ、自動テスト、CI/CDに興味があります。もっと詳しく

npryce/adr-toolsは、ADR(Architecture Decision Record)を管理するためのCLIです。ADRの作成や置き換えなど、いくつかの機能を提供しています。

macOSであればHomebrewでインストールできます。

% brew install adr-tools

以下のコマンドでADRのディレクトリが作成されます。デフォルトでは、/doc/adr/ となります。

% adr init

ADRとADR-Tools

ADRは、Documenting Architecture Decisionsが初出であるとのこと (Mark, Meal (2022), p.289)。

ADR-Toolsの使い方については、hasCode.com » Blog Archive » Managing Architecture Decision Records with ADR-Toolsが詳しいです。

日本語で読める書籍では、「ソフトウェアアーキテクチャの基礎 エンジニアリングに基づく体系的アプローチ」 (Mark Richards, Neal Ford (2022))、「エンジニアリングマネージャーのしごと チームが必要とするマネージャーになる方法」 (James Stanier (2022)) に記述が見られます。

ADR-Tools

以下のようなコマンドで、ADRの雛形を生成します。“absolutely important architecture decision” の部分は自由に入力します。

% adr new absolutely important architecture decision

0003-absolutely-important-architecture-decision.md というような名前でMarkdownファイルが作成されます。このファイル名の 0003 の部分は連番で作成されます。ファイルの中身は以下のようなものになります。「ADRの基本構造は、タイトル、ステータス、コンテキスト、決定、影響という5つの主要セクションから構成される (Mark, Meal (2022), p.289)」 という説明のとおりです。

# 3. absolutely important architecture decision

Date: 2023-08-11

## Status

Accepted

## Context

The issue motivating this decision, and any context that influences or constrains the decision.

## Decision

The change that we're proposing or have agreed to implement.

## Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

ADR-Toolsを使って嬉しい時

ADR-Toolsを用いる主なメリットとして、ソースコードと同じ(Gitなどの)リポジトリでADRを管理できることが挙げられます。また、例えばGitHubを使っている場合は、ADR作成のPull Requestを作成し、Pull Requestが承認されるまでADRの変更が可能となるでしょう(実際に試したことはないので実効性は不明)。

反対に、この方針が組織やチームのドキュメント管理方針と異なる場合は、ADR-Toolsを用いてソースコードと同じリポジトリでADRを管理するのはやめた方が良さそうです。

Reference

  1. npryce/adr-tools: Command-line tools for working with Architecture Decision Records(最終アクセス日:2023年8月11日)
  2. Documenting Architecture Decisions(最終アクセス日:2023年8月11日)
  3. hasCode.com » Blog Archive » Managing Architecture Decision Records with ADR-Tools(最終アクセス日:2023年8月11日)
  4. Mark Richards, Neal Ford, 島田浩二 (訳), (2022), ソフトウェアアーキテクチャの基礎 エンジニアリングに基づく体系的アプローチ, オライリー・ジャパン
  5. James Stanier, 吉羽龍太郎 (訳), 永瀬美穂 (訳), 原田騎郎 (訳), 竹葉美沙 (訳), (2022), エンジニアリングマネージャーのしごと チームが必要とするマネージャーになる方法, オライリー・ジャパン