🎉

madr-kit - MADR（Markdown Architectural Decision Records）を簡単に管理するツール

に公開
テーマ「2025年の最も大きなチャレンジ」
AI
アーキテクチャ
ADR
AI駆動開発
madr
tech

madr-kit - MADR を簡単に管理するツール

ソフトウェア開発では、様々なアーキテクチャ上の重要な決定を下します。しかし、その決定に至った背景や理由をきちんと記録しているプロジェクトは意外と少ないかもしれません。そこで登場するのが ADR (Architecture Decision Records) という概念。今回は、MADR 形式での ADR 管理を効率化する madr-kit というツールを開発・公開しましたので、紹介します。

ADR とは

ADR は「アーキテクチャ上重要な設計決定とその根拠を記録するもの」です。単に「何を決めたか」だけでなく「なぜそう決めたのか」「他にどんな選択肢があったのか」「その決定によってどんな影響があるのか」といった情報を構造化して残しておくことで、以下のようなメリットがあります。

  • 知識の共有: チームメンバーや新しく参加した開発者が、過去の判断の背景を理解できる
  • 再検討の根拠: 決定を見直す際の判断材料になる
  • プロジェクト分析: プロジェクトがどのような指針で進んできたかが可視化される

Azure Well-Architected Framework や AWS などの大手クラウドプロバイダーも ADR の採用を推奨しており、その価値は広く認識されています。

MADR とは

MADR (Markdown Architectural Decision Records) は、ADR の概念をシンプルで実装しやすい形にしたものです。主な特徴は：

  • Markdown ベース: テキストファイルで記録できるので、Git などのバージョン管理との相性が良い
  • 構造化テンプレート: 以下の要素を含む統一されたフォーマット
    • Title: 決定の内容を短く示すタイトル
    • Context: 決定が必要だった背景や問題
    • Decision Drivers: 決定に影響を与えた要因
    • Considered Options: 検討した選択肢
    • Decision: 最終的に選択した内容
    • Consequences: その決定による結果・影響
  • ファイル命名規約: NNNN-title-with-dashes.md の形式で管理

既存のツール: spec-kit

JavaScript/TypeScript の仕様書管理には、すでに spec-kit というユーティリティが存在し、仕様書を効率的に管理できるようになっています。

しかし MADR の管理に関しては、同等レベルの公式ツールが存在しませんでした。

madr-kit を作った理由

MADR は非常に有用なフレームワークですが、以下のような課題がありました：

  • 初期セットアップが面倒: ディレクトリを手作りして、テンプレートを自分で用意する必要がある
  • ファイル作成が手動: 毎回ファイル名のルールに従って、テンプレートを埋めていかなければならない
  • インデックス管理が負担: すべての決定記録を一覧化するために、インデックスファイルを手動で更新する必要がある

こうした面倒な作業を自動化し、MADR の採用がもっと簡単になるように、madr-kit を開発しました。

madr-kit の主な機能

1. プロジェクト初期化

npm install -g madrkit
cd your-project
madrkit init

初期化コマンドで、以下が自動的にセットアップされます：

  • docs/decisions/ ディレクトリの作成
  • 必要な設定ファイルの配置
  • テンプレートの準備

2. 対話的な決定記録作成

madrkit create

対話的なプロンプトを通じて、以下の情報を入力するだけで ADR が生成されます：

? ADR のタイトルを入力してください
> TypeScript を導入する

? ステータスを選択してください
> (1) Proposed (2) Accepted (3) Deprecated

? コンテキストを記入してください
> プロジェクトの規模が拡大しており、...

? 検討した選択肢を入力してください
> - JavaScript のまま続ける
> - TypeScript を導入する
> - ReScript を使用する

? 最終的な決定を入力してください
> TypeScript を導入する理由は...

? 結果・影響を記入してください
> 開発効率が向上し、バグが減少した...

3. 自動インデックス生成

すべての決定記録が作成されると、自動的に docs/decisions/index.md が生成され、以下のようなインデックスが作成されます：

# Architectural Decision Records

| # | Title | Status | Date |
|---|-------|--------|------|
| 0001 | Use TypeScript | Accepted | 2025-12-01 |
| 0002 | Use React for UI | Accepted | 2025-12-01 |
| 0003 | PostgreSQL as Database | Accepted | 2025-12-01 |

4. Git との統合

記録は Markdown ファイルなので、Git で自然にバージョン管理ができます。Pull Request で ADR の追加・修正をレビューする流れも確立しやすくなります。

インストール

npm パッケージとして公開

npm install -g madrkit

または、プロジェクトの開発依存として：

npm install --save-dev madrkit

npx で実行することもできます：

npx madrkit init
npx madrkit create

パッケージ情報

https://www.npmjs.com/package/madrkit
https://github.com/mahiguch/madr-kit

使用例

セットアップから記録作成まで

# 1. インストール
npm install -g madrkit

# 2. プロジェクト初期化
cd my-project
madrkit init

# 3. 最初の決定記録を作成
madrkit create

# 4. 作成されたファイルを確認
cat docs/decisions/0001-*.md

# 5. インデックスを確認
cat docs/decisions/index.md

# 6. Git にコミット
git add docs/decisions/
git commit -m "docs: add initial ADR"

既存プロジェクトへの導入

すでに進行中のプロジェクトにも簡単に導入できます。過去の重要な決定を遡って記録することで、プロジェクトのアーキテクチャの全体像が可視化されます。

なぜ MADR は広がるのか

  1. シンプル: テンプレートが単純で、特別なツールやスキルが不要
  2. バージョン管理との親和性: Markdown + Git で自然に履歴管理できる
  3. 実践的: 大手クラウドプロバイダーも推奨する形式
  4. 拡張性: チームの必要に応じてテンプレートをカスタマイズできる点

これまで ADR は「良いことはわかるものの、導入が面倒」というイメージがありました。madr-kit はそうした障壁を取り除き、どのプロジェクトでも気軽に ADR を始められる環境を提供します。

まとめ

  • ADR は、アーキテクチャ上の決定とその背景を記録する仕組み
  • MADR は、Markdown ベースのシンプルな ADR フレームワーク
  • madr-kit は、MADR の管理を自動化するコマンドラインツール

「重要な決定が埋もれてしまう」「過去になぜそう決めたのか思い出せない」という経験は誰しもあるはず。madr-kit を使って、プロジェクトのアーキテクチャ上の決定を体系的に記録していくことをお勧めします。

関連リンク

https://adr.github.io/madr/
https://adr.github.io/
https://www.npmjs.com/package/madrkit
https://github.com/mahiguch/madr-kit
https://github.com/joelparkerhenderson/architecture-decision-record

Discussion