decision-log

决策日志

概述

当团队或 Agent 需要记住决定了什么、为何做出此决定、考虑过哪些替代方案，以及应何时复审此决定时，使用此技能来保存持久且可搜索的决策记录。

它解决了聊天记录和会议记录难以妥善解决的常见问题：

• 决策淹没在冗长的对话中，之后很难找到。
• 人们会忘记选择背后的理由和限制条件。
• 由于没有权威记录，已解决的问题会被反复讨论。
• 撤销决定时，人们会删除旧背景，而不是保留历史记录。
• 没有复审周期，受时间影响的决策会悄然过时。

此模式遵循 ADR 风格：每项决策对应一个 Markdown 文件，按顺序编号，包含状态、背景、选项、决策、后果和复审元数据。其格式遵循 Michael Nygard 的架构决策记录（ADR）模式的理念，并将其推广到产品、运营、研究和团队决策。

决策记录存放在可配置的目录中：

• 每条命令都可以使用 --decisions-dir DIR，或
• 使用 DECISIONS_DIR=/path/to/decisions，或
• 默认使用相对于当前工作目录的 ./decisions/。

快速开始

python scripts/decision_log.py new --title "Use SQLite for source-tracker"

该命令会创建下一个编号的文件，例如：

./decisions/ADR-001-use-sqlite-for-source-tracker.md

打开打印出的路径，填写各个部分，然后在决策获批后，将 ## Status 从 proposed 改为 accepted。

何时创建 ADR

当某项选择足够重要，以至于未来的人会问“我们为什么这么做？”时，请创建决策记录。例如：

• 架构、存储、API、依赖项、部署或安全方面的选择。
• 影响多个用户或未来工作的产品或工作流选择。
• 存在实际成本、限制条件或被排除选项的权衡。
• 可能需要在某个日期、里程碑或外部触发条件之后复审的决策。
• 对先前决策的撤销。

以下琐碎选择不要创建 ADR：

• 拼写错误修复、一次性重构或显而易见的实现细节。
• 已由明确标准或用户指示规定的选择。
• 不会影响未来工作的临时性权宜决定。

ADR 格式

每条决策记录都是一个 Markdown 文件，文件名为：

ADR-NNN-short-title.md

NNN 是零填充的序列号（001、002……）。除非是在迁移旧记录，否则不要手动编号文件；请使用 CLI，以保持编号一致。

各部分如下：

状态

允许的值：

• proposed — 已起草，但尚未采纳。
• accepted — 当前生效的决策。
• superseded by ADR-NNN — 已被后续决策取代。
• deprecated — 已主动废弃，且没有直接替代项。

即使旧决策发生变化，也绝不要删除它。应将其标记为已取代，以保留完整的审计记录。

日期

记录创建或获批的日期，格式为 YYYY-MM-DD。

背景

问题陈述、背景信息、限制条件、影响因素、假设和事实，这些内容使决策成为必要。好的背景说明能解释为什么这个决策并非显而易见。

考虑过的选项

列出有意义的替代方案及其优缺点。包括未来读者可能会询问的被拒绝选项。

决策

说明选择了什么以及原因。“为什么”和选择本身同样重要：应将选择与限制条件、权衡和预期结果联系起来。

后果

记录正面、负面和中性的后果。这可以避免记录沦为单纯的论证备忘录；已知缺点也应清晰呈现。

复审

记录复审周期、下次复审日期和触发条件：

• 周期：monthly、quarterly、annually 或 on-trigger。
• 下次复审：YYYY-MM-DD；对于有日期周期的复审，会自动计算。
• 触发条件：可选条件；如果出现，应在计划的复审时间之前启动重新评估。

工作流 1：创建

使用默认的 quarterly 复审周期创建一项新决策：

python scripts/decision_log.py new --title "Use SQLite for source-tracker"

添加初始背景：

python scripts/decision_log.py new \
  --title "Use SQLite for source-tracker" \
  --context "Single-user local index, low write volume, simple backup needs."

在指定目录中创建：

python scripts/decision_log.py new \
  --title "Use hosted object storage for exports" \
  --decisions-dir ./docs/decisions

选择复审周期：

python scripts/decision_log.py new \
  --title "Adopt quarterly vendor review" \
  --cadence annually

完成标准：CLI 会打印新的 ADR-NNN-short-title.md 路径；文件中包含已填写的标题、日期、周期，以及适用时的下次复审日期。

工作流 2：列出

列出所有决策：

python scripts/decision_log.py list

按状态筛选：

python scripts/decision_log.py list --status accepted
python scripts/decision_log.py list --status proposed
python scripts/decision_log.py list --status superseded
python scripts/decision_log.py list --status deprecated

按主题文本筛选：

python scripts/decision_log.py list --topic storage

完成标准：表格显示 ADR 编号、日期、状态、标题和路径。

工作流 3：取代

决策发生变化时，先创建新决策，再将旧决策标记为已取代：

python scripts/decision_log.py new --title "Move source-tracker storage to Postgres"
python scripts/decision_log.py supersede 001 --by 005

此操作会将 ADR-001...md 更新为：

## Status
superseded by ADR-005

并添加指向取代它的 ADR 的链接。旧背景仍可搜索。

完成标准：list --status superseded 中包含旧 ADR，且 timeline 显示这条链。

工作流 4：搜索

跨决策搜索全文：

python scripts/decision_log.py search "SQLite"
python scripts/decision_log.py search "backup"

搜索结果会返回匹配的 ADR 和背景摘录，帮助你避免重新讨论已解决的问题。

完成标准：打印匹配的 ADR 编号、标题、路径和摘录，或由 CLI 明确说明未找到匹配项。

工作流 5：复审计划

显示下次复审日期已到期的决策：

python scripts/decision_log.py due-review

使用兼容 cron 的检查器安排提醒：

python scripts/review_checker.py --decisions-dir ./decisions

每周 cron 调度器条目示例：

0 9 * * MON DECISIONS_DIR=/path/to/decisions python /path/to/scripts/review_checker.py

没有到期事项时，检查器不会输出任何内容。有已接受的决策到期时，它会打印简洁摘要，可由你已在使用的调度器或封装程序发送到消息平台。

完成标准：有已接受的决策到期时，会生成以 N decisions due for review: 开头的消息；没有到期决策时，检查器不会输出任何内容。

工作流 6：时间线

显示取代链：

python scripts/decision_log.py timeline

按主题筛选链：

python scripts/decision_log.py timeline --topic storage

输出示例：

ADR-001 → ADR-005 → ADR-012

完成标准：每条链都按从最早决策到最新决策的顺序显示，并沿着 superseded by ADR-NNN 链接向前延伸。

复审周期选项

• monthly — 适用于变化迅速的决策、实验、供应商试用，或可能很快过时的运营决策。下次复审日期为当前日期加 1 个日历月。
• quarterly — 大多数活跃的产品、架构和工作流决策的默认选项。下次复审日期为当前日期加 3 个日历月。
• annually — 适用于较稳定的决策，每年验证一次即可。下次复审日期为当前日期加 1 个日历年。
• on-trigger — 适用于日期没有实际意义的情况。将 Next review 留空，并写明具体触发条件，例如“如果月度记录量超过 1M，则复审”或“如果第二个团队采用此工作流，则复审”。

按日历月计算时，会将日期调整为目标月份的最后一个有效日期。例如，从 1 月 31 日起按月复审，下次复审日期为 2 月 28 日或 29 日。

文件交付

当工作流生成或更新文件时，请向用户提供文件路径，以便他们在常用编辑器中打开、复审和编辑 Markdown 记录。

常见陷阱

1. 删除而不是取代。 删除会丢失历史记录。将旧记录标记为 superseded by ADR-NNN，并保留文件。
2. 缺少背景信息。 如果决策没有说明约束条件和被否决的选项，就无法避免未来重新讨论。请提供足够的背景，让新读者也能理解。
3. 没有复审日期。 有固定复审周期的已采纳决策应设置 Next review 值。只有触发条件明确时，才使用 on-trigger。
4. 文件未编号。 不符合 ADR-NNN-short-title.md 模式的文件不会纳入列表、复审或时间线命令。
5. 状态不一致。 请严格使用 proposed、accepted、superseded by ADR-NNN 或 deprecated，以确保筛选和提醒正常工作。
6. 尚未编写替代记录就先取代旧记录。 请先创建新的 ADR，这样旧 ADR 才能指向现有记录。
7. 触发条件含糊。 “稍后复审”不算触发条件。请使用可衡量的事件、日期、阈值或依赖项变更。

验证清单

• 新文件命名为 ADR-NNN-short-title.md，且编号连续。
• 每份 ADR 都包含 Status、Date、Context、Options Considered、Decision、 Consequences 和 Review 部分。
• 已批准的当前有效决策状态为 accepted。
• 已变更的决策应标记为取代，而不是删除。
• python scripts/decision_log.py list 显示预期的记录。
• python scripts/decision_log.py due-review 找出到期的记录。
• python scripts/decision_log.py timeline 显示取代关系链。
• cron 调度器使用预期的 DECISIONS_DIR 或 --decisions-dir 运行 review_checker.py。
• 创建或更新文件时，应向用户提供文件路径。

文件

• scripts/decision_log.py — 用于创建、列出、取代、搜索、查找待复审记录和查看时间线的主要 CLI。
• scripts/review_checker.py — 供 cron 调度器使用、无待办时静默的提醒检查器。
• templates/decision-template.md — 空白 ADR 模板。
• references/adr-format.md — 按章节编写 ADR 的指南。
• references/review-cadence.md — 复审周期和触发条件规则。