ADR Tools - 架构决策记录工具
项目描述
ADR Tools 是一个轻量级的命令行工具，专门用于管理项目的架构决策记录（Architecture Decision Records, ADRs）。该项目采用Unix shell脚本实现，支持跨平台使用，能够帮助开发团队系统化地记录和追踪重要的架构决策过程。
功能特性
- 简单的命令行接口：提供统一的
adr命令，支持多种子命令操作 - Markdown格式支持：决策记录采用标准Markdown格式，便于阅读和版本控制
- 决策关联管理：支持创建新决策并标记其与旧决策的替代关系
- 跨平台兼容：支持Linux、MacOS X和Windows（通过Git Bash或Linux子系统）
- 自动编号和日期管理：自动为决策记录生成编号和ISO 8601格式日期
- 可配置性：支持通过配置文件自定义行为
安装指南
Homebrew (MacOS X)
brew install adr-tools
ASDF-VM (Linux, MacOS X)
通过ASDF版本管理器安装：
asdf plugin-add adr-tools
asdf install adr-tools latest
从发布包安装
- 从发布页面下载zip或tar.gz包
- 解压包文件
- 将
src/子目录添加到PATH环境变量中
从Git源码安装
git clone https://github.com/npryce/adr-tools.git
export PATH="$PATH:$(pwd)/adr-tools/src"
Windows 10
Git Bash方式
- 下载发布包并解压
- 将
src/目录内容复制到C:\Program Files\Git\usr\bin - 安装
more命令或设置PAGER环境变量为less
Linux子系统方式
在Windows的Linux子系统中按照"从发布包安装"的步骤操作。
使用说明
初始化ADR目录
adr init doc/architecture/decisions
这将在项目根目录创建ADR存储目录，并生成第一个决策记录。
创建新决策记录
adr new "Implement as Unix shell scripts"
创建新的决策记录并在编辑器中打开。
创建替代决策
adr new -s 9 "Use Rust for performance-critical functionality"
创建替代第9号决策的新决策记录。
获取帮助
adr help
adr help new # 获取特定子命令的帮助
核心代码
决策记录模板
# NUMBER. TITLEDate: DATE## StatusSTATUS## Context## 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-config)
#!/bin/bash
# ADR Tools配置脚本
# 输出工具运行所需的配置信息echo "ADR_DATE=$(date +%Y-%m-%d)"
echo "ADR_DIR=${ADR_DIR:-doc/adr}"
echo "EDITOR=${EDITOR:-vi}"
决策创建逻辑
#!/bin/bash
# adr-new脚本核心逻辑
# 创建新的架构决策记录generate_adr() {local number=$1local title=$2local date=$(date +%Y-%m-%d)cat > "$ADR_DIR/${number}-${title// /-}.md" << EOF
# ${number}. ${title}Date: ${date}## StatusProposed## Context$(get_context)## Decision$(get_decision)## Consequences$(get_consequences)
EOF
}
决策状态更新
#!/bin/bash
# 更新决策状态的函数
# 当新决策替代旧决策时自动更新状态update_status() {local old_adr=$1local new_adr=$2# 在旧决策中添加被替代标记sed -i.bak "/## Status/a\\
Superceded by [${new_adr}]" "$old_adr"# 在新决策中添加替代关系sed -i.bak "/## Context/a\\
Supercedes [${old_adr}]" "$new_adr"
}
该工具通过简单的shell脚本实现了完整的架构决策管理功能，具有良好的可扩展性和可维护性。
更多精彩内容 请关注我的个人公众号 公众号（办公AI智能小助手）
公众号二维码
