adr-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADR Manager

ADR管理器

Purpose

目的

Turn vague design discussions into durable ADRs that future agents can reuse.
Start from repository evidence (existing ADRs, code, config, tests, docs)—not assumptions.
Ask follow-up questions only for information that cannot be recovered from the repo and that materially affects the decision.
Write ADR prose in the language of the current request (the language the user is using in session), or match the language of existing ADRs in this repository when that is clearly established—prefer consistency across the ADR set over mixing languages without reason.

将模糊的设计讨论转化为可长期复用的ADRs，供后续Agent使用。
以仓库现有证据（现有ADR、代码、配置、测试、文档）为基础，而非假设。
仅针对无法从仓库中获取且对决策有实质性影响的信息提出后续问题。
以当前请求所使用的语言（用户在会话中使用的语言）撰写ADR内容；当仓库中已有明确统一的ADR语言时，匹配该语言——优先保证ADR集合的一致性，避免无理由的语言混用。

When to Use

适用场景

"create an ADR", "ADR を書いて", "architecture decision", "design doc を ADR に"
The user wants to ingest a spec/design doc into one or more ADRs (
```
doc-ingest
```
).
The user wants to query what is already decided before coding (
```
adr-query
```
).
The user wants to update, supersede, or clarify an existing ADR (
```
adr-update
```
).
The user is exploring a technical choice and needs help shaping it (
```
decision-intake
```
).

"create an ADR", "ADR を書いて", "architecture decision", "design doc を ADR に"
用户希望将规格/设计文档转化为一个或多个ADR（
```
doc-ingest
```
模式）。
用户希望在编码前查询已有的决策（
```
adr-query
```
模式）。
用户希望更新、替代或澄清现有ADR（
```
adr-update
```
模式）。
用户正在探索技术选型，需要帮助梳理决策（
```
decision-intake
```
模式）。

Do Not Use When

不适用场景

The work is a routine bugfix, refactor, or local implementation detail with no durable architectural stake—prefer a ticket/PR description, not an ADR.
The user only needs git operations (commit, push, PR)—use commit-jp, push, create-pr-jp, etc.
The question is purely factual about existing code with no decision to record—answer from the repo without drafting an ADR unless the user asks for one.

工作内容为常规Bug修复、重构或局部实现细节，不涉及长期架构影响——优先使用工单/PR描述，而非ADR。
用户仅需要Git操作（提交、推送、创建PR）——使用commit-jp、push、create-pr-jp等工具。
问题仅涉及现有代码的纯事实查询，无需记录决策——直接从仓库中获取答案，除非用户明确要求生成ADR。

Overview

概述

If multiple workflow modes apply, begin with the earliest prerequisite (e.g.

doc-ingest

before

adr-create

when a design doc maps to new ADRs).

若多个工作流模式适用，从最早的前置模式开始（例如：当设计文档需要转换为新ADR时，先执行

doc-ingest

模式，再执行

adr-create

模式）。

Workflow

工作流

Follow this sequence:

Detect the request type.
Discover repository ADR conventions and overrides.
Gather repository evidence.
Decide whether this should create a new ADR, update an existing ADR, or remain a non-ADR note.
Identify missing decision-critical information.
Ask focused questions if needed.
Draft or update ADR content.
Update supporting files when appropriate.
Return a concise summary of what changed, what remains open, and what future agents should read first.

遵循以下步骤：

检测请求类型。
发现仓库的ADR约定和自定义规则。
收集仓库证据。
决定是否创建新ADR、更新现有ADR，或仅生成非ADR记录。
识别缺失的关键决策信息。
如有需要，提出针对性问题。
起草或更新ADR内容。
适时更新支持文件。
返回简洁的总结，包括变更内容、未解决问题，以及后续Agent应优先阅读的ADR。

1. Detect the request type

1. 检测请求类型

Classify the request into one primary mode:

decision-intake: the user is talking loosely about a technical choice and wants help shaping the decision.
adr-create: the user wants a new ADR.
adr-update: the user wants an existing ADR revised, superseded, or clarified.
doc-ingest: the user provides a design doc, spec, or notes and wants it turned into one or more ADRs.
adr-query: the user wants to know what has already been decided and how that should affect current implementation.

If multiple modes apply, begin with the earliest prerequisite mode. Example: for a design doc that likely maps to new ADRs, do

doc-ingest

before

adr-create

将请求分类为以下主要模式之一：

decision-intake：用户正在松散地讨论技术选型，需要帮助梳理决策。
adr-create：用户希望创建新ADR。
adr-update：用户希望修订、替代或澄清现有ADR。
doc-ingest：用户提供设计文档、规格说明或笔记，希望将其转换为一个或多个ADR。
adr-query：用户希望了解已有的决策，以及这些决策对当前实现的影响。

若多个模式适用，从最早的前置模式开始。例如：对于可能映射到新ADR的设计文档，先执行

doc-ingest

模式，再执行

adr-create

模式。

2. Discover repository ADR conventions and overrides

2. 发现仓库的ADR约定和自定义规则

Before drafting anything, search the repository in this order:

```
.adr-manager.yaml
```
```
.adr-manager.yml
```
```
.ai/adr-manager.yaml
```
```
.ai/adr-manager.yml
```
```
docs/adr/README.md
```
```
docs/adr/index.md
```
any existing ADR directory listed in references/default-conventions.md

If an override file exists, follow it. If multiple override files exist, prefer the first one in the list above unless one explicitly points to another source of truth.

If no override file exists, infer conventions from existing ADR files. If there are no ADR files, use the default conventions in references/default-conventions.md.

在起草任何内容前，按以下顺序搜索仓库：

```
.adr-manager.yaml
```
```
.adr-manager.yml
```
```
.ai/adr-manager.yaml
```
```
.ai/adr-manager.yml
```
```
docs/adr/README.md
```
```
docs/adr/index.md
```
references/default-conventions.md中列出的任何现有ADR目录

若存在自定义规则文件，遵循该规则。若存在多个自定义规则文件，优先使用上述列表中靠前的文件，除非其中一个明确指向另一个可信来源。

若不存在自定义规则文件，从现有ADR文件中推断约定。若没有任何ADR文件，使用references/default-conventions.md中的默认约定。

3. Gather repository evidence

3. 收集仓库证据

Inspect the repository before asking questions.

Prioritize these sources:

existing ADRs on the same theme
superseded or rejected ADRs
code paths that will change
interfaces, schemas, migrations, and feature flags
tests that reveal intended behavior
design docs, RFCs, or issue notes stored in the repository
README, architecture docs, and module-level docs

Build a compact evidence summary for yourself with:

current state
constraints already encoded in code
alternatives already discussed
related decisions and conflicts
unresolved questions

在提出问题前先检查仓库。

优先检查以下来源：

同一主题的现有ADR
已被替代或否决的ADR
将要变更的代码路径
接口、schema、迁移脚本和功能开关
能体现预期行为的测试
仓库中存储的设计文档、RFC或问题记录
README、架构文档和模块级文档

为自己整理一份简洁的证据摘要，包括：

当前状态
代码中已编码的约束
已讨论过的替代方案
相关决策和冲突
未解决的问题

4. Decide whether this should be a new ADR, an update, or not an ADR

4. 决定创建新ADR、更新现有ADR或生成非ADR记录

Create a new ADR when the decision changes architecture, system boundaries, data contracts, deployment/runtime model, major library/framework selection, security/privacy posture, or an important trade-off likely to matter later.

Prefer updating an existing ADR when the repository already has an ADR covering the same decision and the user is refining scope, changing status, or recording consequences.

Prefer a non-ADR note when the request is just a local implementation detail, routine refactor, bug fix, or one-off task that has little long-term architectural significance.

When the decision is borderline, say so explicitly and explain the recommendation.

当决策涉及架构变更、系统边界、数据契约、部署/运行时模型、主要库/框架选型、安全/隐私策略，或可能对未来产生影响的重要权衡时，创建新ADR。

当仓库中已有覆盖同一决策的ADR，且用户正在调整范围、变更状态或记录决策后果时，优先更新现有ADR。

当请求仅涉及局部实现细节、常规重构、Bug修复或一次性任务，且几乎没有长期架构意义时，优先生成非ADR记录。

当决策处于模糊地带时，明确说明并解释推荐方案。

5. Identify missing decision-critical information

5. 识别缺失的关键决策信息

Check whether the repository evidence answers these fields:

context
problem or tension
decision
options considered
why rejected options were rejected
consequences and trade-offs
rollout or migration impact
validation plan
rollback or escape hatch
status
owners or stakeholders when relevant
open questions that should remain open

Ask follow-up questions only for missing items that materially change the ADR.

检查仓库证据是否能回答以下字段：

背景
问题或矛盾
决策内容
考虑过的选项
否决其他选项的原因
后果和权衡
发布或迁移影响
验证计划
回滚或应急方案
状态
相关负责人或利益相关者（如有必要）
应保留的未解决问题

仅针对会实质性改变ADR的缺失信息提出后续问题。

6. Ask focused questions

6. 提出针对性问题

When questions are needed:

ask 3 to 7 questions maximum in one round
ask only repository-grounded questions
separate must answer before drafting from can remain open in the ADR
offer provisional assumptions when possible

Good examples:

"I found an existing PostgreSQL-first direction in ADR-0012, but this new proposal adds Elasticsearch. Is the goal full replacement, or search-only augmentation?"
"The current code supports both sync and async job execution. Should this decision standardize on one path or preserve both behind a feature flag?"
"I found no rollout notes. Should the ADR include a staged migration plan, or is this intended for greenfield only?"

Use references/question-rubric.md to decide whether a question is worth asking.

当需要提问时：

一轮最多提出3到7个问题
仅提出基于仓库的问题
区分起草前必须回答和可在ADR中保留未解决的问题
尽可能提供临时假设

优秀示例：

"我在ADR-0012中发现了优先使用PostgreSQL的方向，但新提案加入了Elasticsearch。目标是完全替代还是仅增强搜索功能？"
"当前代码支持同步和异步作业执行。此决策应标准化为其中一种方式，还是在功能开关后保留两种方式？"
"我未找到发布记录。ADR是否应包含分阶段迁移计划，还是仅适用于全新项目？"

使用references/question-rubric.md判断问题是否值得提出。

7. Draft or update ADR content

7. 起草或更新ADR内容

Use the repository's template if one exists. Otherwise use the template in references/adr-template.md.

若仓库存在模板，使用该模板。否则使用references/adr-template.md中的模板。

Language

语言

Default: Write the ADR body in the same language as the user’s messages in this session (e.g. Japanese if the user writes Japanese, English if they write English).
Repository alignment: If the repo already has ADRs in a consistent language, match that language for new or updated ADRs so the corpus stays uniform—even when the current request is in another language, unless the user explicitly asks otherwise.
If existing ADRs mix languages, follow the dominant language in the ADR directory you are editing, or the language of the most relevant ADR on the same theme; if unclear, ask once or state the assumption in the handoff.

Always preserve concrete why/why-not reasoning. Future coding agents need the rationale, not just the conclusion.

When drafting from a design doc, first split the document into separate decision units. Do not force unrelated choices into one ADR. Use the guidance in references/doc-to-adr.md.

When information is still missing, write explicit placeholders only when they are decision-safe, such as:

```
Open question:
```
```
Assumption:
```
```
Needs confirmation:
```

Do not invent rejected alternatives, rollout plans, or validation evidence.

默认规则：ADR正文使用用户在当前会话中使用的语言（例如：用户使用日语则用日语，用户使用英语则用英语）。
仓库一致性：若仓库中已有统一语言的ADR，新创建或更新的ADR应匹配该语言，以保持ADR集合的一致性——即使当前请求使用其他语言，除非用户明确要求例外。
若现有ADR混合使用多种语言，遵循你正在编辑的ADR目录中的主导语言，或同一主题最相关ADR的语言；若不明确，可询问一次或在交接时说明假设。

始终保留具体的决策原因/否决原因。未来的编码Agent需要的是决策依据，而非仅仅是结论。

从设计文档起草ADR时，先将文档拆分为独立的决策单元。不要将无关的选择强行放入一个ADR中。遵循references/doc-to-adr.md中的指导。

当信息仍缺失时，仅在决策安全的情况下写入明确的占位符，例如：

```
待解决问题:
```
```
假设:
```
```
需确认:
```

不要虚构被否决的替代方案、发布计划或验证证据。

8. Update supporting files when appropriate

8. 适时更新支持文件

When the repository uses an ADR index, catalog, or README, update it to include:

ADR number and title
current status
supersedes/superseded-by links when relevant
one-line summary

If the repository has no index and the default conventions are in use, create or update the index format described in references/default-conventions.md.

If a decision supersedes another, preserve history instead of deleting old ADRs.

当仓库使用ADR索引、目录或README时，更新以包含：

ADR编号和标题
当前状态
相关的替代/被替代ADR链接（如有必要）
一行摘要

若仓库没有索引且使用默认约定，创建或更新references/default-conventions.md中描述的索引格式。

当某个决策替代了另一个决策时，保留历史记录，不要删除旧ADR。

9. Return a concise implementation handoff

9. 返回简洁的实现交接信息

At the end, provide:

what evidence you used
whether you created a new ADR or updated an existing one
what remains open
which ADR(s) future coding agents should read first
any implementation guardrails implied by the decision

最后，提供以下内容：

使用的证据
是否创建了新ADR或更新了现有ADR
未解决的问题
后续编码Agent应优先阅读的ADR
决策隐含的实现约束

Output expectations by mode

各模式的输出预期

decision-intake

Return:

current understanding
related repository evidence
missing decision-critical questions
recommendation on whether this should become a new ADR, update an ADR, or stay a note

当前理解
相关的仓库证据
缺失的关键决策问题
关于是否应创建新ADR、更新ADR或生成记录的推荐

adr-create

Return:

related ADRs and code evidence
any necessary clarification questions
a complete ADR draft or repository edit
index updates if applicable

相关ADR和代码证据
任何必要的澄清问题
完整的ADR草稿或仓库编辑内容
（如适用）索引更新

adr-update

Return:

the ADR being updated
what changed since the prior decision
updated status and rationale
cross-links to superseded or related ADRs

正在更新的ADR
自上次决策以来的变更
更新后的状态和理由
与被替代或相关ADR的交叉链接

doc-ingest

Return:

candidate ADR list extracted from the document
missing information per candidate
recommended split or merge of decision units
drafted ADRs for the candidates with enough confirmed information

从文档中提取的候选ADR列表
每个候选ADR缺失的信息
关于决策单元拆分或合并的推荐
针对已有足够确认信息的候选ADR起草的内容

adr-query

Return:

the most relevant ADRs
how they constrain the current request
contradictions or stale decisions
whether a follow-up ADR is needed

最相关的ADR
这些ADR对当前请求的约束
矛盾或过时的决策
是否需要后续ADR

Present Results to User

向用户展示结果

Lead with what changed (files created/updated) and where ADRs live in the repo.
Give one short handoff block: evidence used, open questions, which ADR to read first, implementation guardrails.
For multi-mode work, state the mode you used (
```
decision-intake
```
,
```
adr-create
```
, etc.).

首先说明变更内容（创建/更新的文件）和ADR在仓库中的位置。
提供一段简短的交接内容：使用的证据、未解决的问题、优先阅读的ADR、实现约束。
对于多模式工作，说明你使用的模式（
```
decision-intake
```
、
```
adr-create
```
等）。

Quality bar

质量标准

A good ADR produced by this skill should let a future coding agent answer all of these without rereading the whole repository:

what problem were we solving
what did we choose
what alternatives were considered
why did we reject them
what consequences and trade-offs did we accept
what code areas are expected to follow this decision
what is still intentionally unresolved

本技能生成的优质ADR应能让未来的编码Agent无需重新阅读整个仓库即可回答以下问题：

我们要解决什么问题
我们做出了什么选择
考虑过哪些替代方案
为什么否决这些方案
我们接受了哪些后果和权衡
哪些代码区域应遵循此决策
哪些内容仍有意保留未解决

Constraints

约束

stay within the current git repository unless the user explicitly expands scope
write ADR text in the session language or aligned with existing ADRs (see §7 Language); do not default to English when the repo or user context is elsewhere
prefer repository evidence over user memory when they conflict; surface the conflict clearly
do not silently overwrite an existing ADR when a superseding ADR would preserve history better
do not collapse multiple major decisions into one ADR just because they came from one design doc
do not ask questions already answered by code, docs, or existing ADRs

仅在当前Git仓库内操作，除非用户明确扩展范围
使用会话语言或与现有ADR对齐的语言撰写ADR文本（见第7节语言）；当仓库或用户上下文非英语时，不要默认使用英语
当仓库证据与用户记忆冲突时，优先以仓库证据为准；明确指出冲突
当创建替代ADR能更好地保留历史时，不要静默覆盖现有ADR
不要仅仅因为来自同一设计文档，就将多个主要决策合并到一个ADR中
不要询问已被代码、文档或现有ADR回答的问题

Troubleshooting

故障排除

Situation	Action
No ADR directory / conventions found	Apply references/default-conventions.md; prefer creating `docs/adr/` if nothing exists
Override and existing ADRs disagree	Prefer explicit override file if present; otherwise document conflict and ask user
Design doc mixes many decisions	Split per references/doc-to-adr.md; one major decision per ADR
User wants an answer without writing files	Use `adr-query` mode; still cite paths to ADRs in the repo

场景	操作
未找到ADR目录/约定	应用references/default-conventions.md；若不存在任何内容，优先创建 `docs/adr/`
覆盖配置与现有ADR存在冲突	若存在明确的覆盖文件则优先使用；否则记录冲突并询问用户
设计文档包含多个决策	按照references/doc-to-adr.md拆分；每个ADR对应一个主要决策
用户希望获取答案但不生成文件	使用 `adr-query` 模式；仍需引用仓库中的ADR路径

Resources

资源

references/default-conventions.md — fallback layout, numbering, naming, config overrides.
references/adr-template.md — default ADR structure.
references/doc-to-adr.md — design docs → ADRs.
references/question-rubric.md — which follow-up questions are worth asking.

There is no required shell script for this skill; the workflow is agent-driven. If the repository adds automation later, document it in the repo’s own README or

.adr-manager.yaml

references/default-conventions.md — 备用布局、编号、命名、配置自定义规则。
references/adr-template.md — 默认ADR结构。
references/doc-to-adr.md — 设计文档转ADR指南。
references/question-rubric.md — 哪些后续问题值得提出。

本技能不需要特定的Shell脚本；工作流由Agent驱动。若后续仓库添加了自动化，需在仓库自身的README或

.adr-manager.yaml

中记录。