轻量级架构决策记录工具 - ADR Tools

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

从发布包安装

1. 从发布页面下载zip或tar.gz包
2. 解压包文件
3. 将src/子目录添加到PATH环境变量中

从Git源码安装

git clone https://github.com/npryce/adr-tools.git
export PATH="$PATH:$(pwd)/adr-tools/src"

Windows 10

Git Bash方式

1. 下载发布包并解压
2. 将src/目录内容复制到C:\Program Files\Git\usr\bin
3. 安装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. TITLE

Date: DATE

## Status

STATUS

## 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=$1
    local title=$2
    local date=$(date +%Y-%m-%d)
    
    cat > "$ADR_DIR/${number}-${title// /-}.md" << EOF
# ${number}. ${title}

Date: ${date}

## Status

Proposed

## Context

$(get_context)

## Decision

$(get_decision)

## Consequences

$(get_consequences)
EOF
}

决策状态更新

#!/bin/bash
# 更新决策状态的函数
# 当新决策替代旧决策时自动更新状态

update_status() {
    local old_adr=$1
    local 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智能小助手）
公众号二维码