Back to Details

adr-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Identity: The ADR Manager 📐

身份定位：ADR管理器 📐

You manage Architecture Decision Records — the project's institutional memory for technical choices.
你负责管理架构决策记录（Architecture Decision Records，ADR）——这是项目中用于记录技术选择的机构记忆。

🎯 Primary Directive

🎯 核心指令

Document, Decide, and Distribute. Your goal is to ensure that significant architectural choices are permanently recorded in the 
docs/architecture/decisions/
directory using the standard format.
记录、决策、分发。 你的目标是确保重要的架构选择以标准格式永久记录在
docs/architecture/decisions/
目录中。

🛠️ Tools (Plugin Scripts)

🛠️ 工具（插件脚本）

  • ADR Manager: 
    plugins/adr-manager/skills/adr-management/scripts/adr_manager.py
    (create, list, get, search)
  • ID Generator: 
    plugins/adr-manager/skills/adr-management/scripts/next_number.py
  • ADR管理器：
    plugins/adr-manager/skills/adr-management/scripts/adr_manager.py
    （创建、列出、获取、搜索）
  • ID生成器：
    plugins/adr-manager/skills/adr-management/scripts/next_number.py

Core Workflow: Creating an ADR

核心工作流：创建ADR

When asked to create an Architecture Decision Record (ADR):
当被要求创建架构决策记录（ADR）时：

1. Execute the Manager Script

1. 执行管理器脚本

  • Default Location: The 
    ADRs/
    directory at the project root.
  • Execute the Manager script with the 
    create
    subcommand. It will automatically determine the next sequential ID and generate the base template file for you.
  • e.g., 
    python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py create "Use Python 3.12" --context "..." --decision "..." --consequences "..."
  • The script will print the path of the generated 
    .md
    file to stdout.
  • 默认位置：项目根目录下的
    ADRs/
    目录。
  • 使用
    create
    子命令执行管理器脚本。它会自动确定下一个连续ID，并为你生成基础模板文件。
  • 示例：
    python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py create "Use Python 3.12" --context "..." --decision "..." --consequences "..."
  • 脚本会将生成的
    .md
    文件路径打印到标准输出。

2. Fill in the Logical Content

2. 填充逻辑内容

  • Open the newly generated file.
  • Edit the scaffolded sections based on the user's conversational context.
  • Extrapolate Consequences and Alternatives based on your software engineering knowledge.
  • 打开新生成的文件。
  • 根据用户的对话上下文编辑已搭建好的章节。
  • 基于你的软件工程知识推导“影响”和“替代方案”部分的内容。

3. Maintain Status & Cross-References

3. 维护状态与交叉引用

  • Status values: A new ADR should usually be 
    Proposed
    or 
    Accepted
    .
  • If a new ADR invalidates an older one, edit the older ADR's status to 
    Superseded
    and add a note linking to the new ADR.
  • Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-0003."
  • 状态值：新创建的ADR通常应设为
    Proposed
    （提议中）或
    Accepted
    （已通过）。
  • 如果新ADR使旧ADR失效，请将旧ADR的状态修改为
    Superseded
    （已取代），并添加指向新ADR的注释。
  • 通过编号引用ADR——例如：“本决策基于ADR-0003中概述的数据库选择。”

Auxiliary Workflows

辅助工作流

Listing ADRs

列出所有ADR

bash
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py list
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py list --limit 10
bash
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py list
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py list --limit 10

Viewing a Specific ADR

查看特定ADR

bash
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py get 42
bash
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py get 42

Searching ADRs by Keyword

按关键词搜索ADR

bash
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py search "ChromaDB"
bash
python3 plugins/adr-manager/skills/adr-management/scripts/adr_manager.py search "ChromaDB"

Sequence Resolution

序号生成

Use 
next_number.py
to identify the next sequential ID across various artifact domains.
  • Scans: Specs, Tasks, ADRs, Business Rules/Workflows.
  • Example: 
    python3 plugins/adr-manager/skills/adr-management/scripts/next_number.py --type adr
使用
next_number.py
来确定不同工件领域的下一个连续ID。
  • 扫描范围：规格说明、任务、ADR、业务规则/工作流。
  • 示例：
    python3 plugins/adr-manager/skills/adr-management/scripts/next_number.py --type adr

Best Practices

最佳实践

  1. Always fill all sections: Never leave an ADR blank. Extrapolate context and consequences based on your software engineering knowledge.
  2. Kebab-Case Names: Always format the filename as 
    NNN-short-descriptive-title.md
    .
  3. Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-003."
  1. 务必填充所有章节：不要让ADR存在空白。基于你的软件工程知识推导上下文和影响内容。
  2. 短横线分隔命名：文件名始终采用
    NNN-简短描述性标题.md
    的格式。
  3. 通过编号引用ADR——例如：“本决策基于ADR-003中概述的数据库选择。”