决策记录

决策记录（Architecture Decision Records，ADR）用于追踪项目中的关键技术与设计选择。Backlog.md 原生支持 ADR 格式，所有决策以 Markdown 文件形式保存在 backlog/decisions/ 目录中，包含状态元数据和完整上下文。

创建决策记录

# 默认状态为 proposed（提议）
backlog decision create "使用 PostgreSQL 作为主数据库"

# 创建时直接指定状态
backlog decision create "迁移到 TypeScript" -s accepted

创建成功后，系统会在 backlog/decisions/ 下生成类似 decision-3 - 迁移到-TypeScript.md 的文件。文件 frontmatter 中包含 status 字段，用于标识决策当前所处的生命周期阶段。

状态流转

决策记录支持五种标准状态，反映从提出到退出的完整生命周期：

状态变更有三条路径：

# 只改状态，正文保持逐字节不变
backlog decision update decision-3 --status accepted

# 状态与正文同一次提交
backlog decision update decision-3 --status superseded --append-content "## 补充\n\n已被 decision-7 替代"

--status 接受自由文本，文档约定的值为 proposed / accepted / rejected / superseded；显式传入的状态优先于正文中 frontmatter 的值。也可直接编辑决策文件的 frontmatter，或在 Web 界面决策详情页编辑（见 文档与决策）。MCP 侧提供 decision_update 工具（content / appendContent / status 参数）。建议在正文中记录状态变更的原因和时间，保持审计轨迹完整。

列出决策

backlog decision list

输出包含所有决策的 ID、标题和当前状态。已完成处理的决策（accepted、rejected、deprecated、superseded）通常与活跃决策一同展示，便于快速查阅历史选择。

在支持 TTY 的终端中，该命令会打开双栏交互浏览器：左栏列出 Decisions (N)，右栏实时渲染选中决策的原始 Markdown，← / → 切换左右栏焦点，↑ / ↓（或 j / k）在当前栏内导航或滚动，Enter 打开完整查看器，? 打开帮助弹窗，q 退出，活动栏边框高亮为黄色。

# 纯文本输出（适合脚本处理）
backlog decision list --plain

# 分页窗口：最多 n 条 / 跳过 n 条 / 只输出总数
backlog decision list --max-count 20
backlog decision list --max-count 20 --skip 20
backlog decision list --count

# 结构化 JSON 输出（版本化信封 kind: "decision-list"）
backlog decision list --json

非 TTY 环境默认回退为纯文本输出；决策日志为空时打印 No decisions found.。

决策列表也已在 MCP 暴露：decision_list 工具支持 limit / offset / status / search 过滤，返回统一的 { items, total, offset, limit, hasMore } 分页信封。详见 MCP 工作流。

查看决策

backlog decision view decision-3

在 TTY 环境下默认打开可滚动的交互式查看器（PageUp / PageDown / Home / End 可用，Windows 下关闭鼠标跟踪避免 PowerShell / VS Code 挂起），非 TTY 环境回退为 --plain 输出 frontmatter 与 Markdown 正文。

当同一 ID 命中多个文件时，命令会打印全部候选路径并以退出码 1 失败，而不会任选一个（与文档一致的 fail-closed 身份规则）。

更新决策

# 替换决策正文
backlog decision update decision-3 --content "## 背景\n\n新的背景说明"

# 追加一段内容（可重复，保留已有正文）
backlog decision update decision-3 --append-content "## 补充\n\n新增考量"

decision update 复用结构化章节解析（背景 / 决策 / 后果 / 备选方案），--content 与 --append-content 都支持与其它命令一致的 \n 换行转义；状态通过 --status 修改（见上一节），三个选项可单独或组合使用。

ADR 格式简介

生成的决策记录文件遵循标准 ADR 结构：

---
status: proposed
date: 2026-05-07
---

# 迁移到 TypeScript

## 背景

项目目前使用 JavaScript，随着代码量增长，类型安全问题日益突出……

## 决策

全面迁移到 TypeScript，使用严格模式。

## 后果

- 正向：编译期类型检查、更好的 IDE 支持、降低运行时错误
- 负向：初期迁移成本、团队成员学习曲线

字段说明

• status：决策当前状态，必填。
• date：创建日期，自动生成。
• 背景（Context）：描述问题背景和约束条件。
• 决策（Decision）：明确陈述做出的决定。
• 后果（Consequences）：列出该决策带来的正面和负面影响。

与任务和文档的关联

在任务创建或编辑时，可通过 --doc 选项关联相关决策记录：

backlog task create "升级构建工具到 Vite" --doc decision-3

这样在看板或任务详情中，可以直接跳转到关联的决策上下文，避免重复讨论已定论的技术选型。

反向链接

决策页面（CLI decision view 的交互式浏览器右栏、Web 决策详情页）会展示反向链接列表，列出哪些任务、文档、决策或 Wiki 页面引用了当前决策：

• 索引在客户端构建（buildBacklinkIndex），随内容变更实时刷新，不回写任何文件
• 每条反向链接显示来源类型图标、标题与 ID，点击即在当前视图打开来源
• 多个 ID 同时命中的来源会以下拉选择器折叠展示

反向链接是只读的导航辅助，不影响决策内容或状态流转。

最佳实践

• 及时记录：在技术讨论结束后的 24 小时内创建决策记录，防止细节遗忘。
• 保持精简：每个决策聚焦一个问题，避免将多个不相关的选择混在同一文件中。
• 状态透明：一旦决策被替代或废弃，立即更新状态为 superseded 或 deprecated，并在正文中引用替代方案。
• 定期回顾：每季度运行 backlog decision list，检查是否存在长期停留在 proposed 状态的决策，推动闭环。