log-decisions skill 是什么，给 agent 决策留底
log-decisions skill 写 DECISIONS.md，decide/assume/escalate 三分法，跨 Claude Code 与 Cursor。
log-decisions skill 是什么：一个纯 markdown 的 Agent Skill，让 agent 把「规格没写清但不得不选」的调用记进项目根 DECISIONS.md，append-only，带来 decide / assume / escalate 三条规则。适合 Claude Code、Codex、Cursor Skills 等任意 skills 宿主。它解决的是「chat 里说过但 PR 里找不到」的决策蒸发问题，不是替 spec 写需求。
安装与文件长什么样
通用安装（官方仓库）：
npx skills add swe-workflow/log-decisions
Claude Code 也可用 plugin 路径：/plugin marketplace add swe-workflow/log-decisions 再 install。Skill 本体是 skills/log-decisions/SKILL.md，无脚本，靠 agent 读规则后执行。
每条决策一块，字段含 Question、Options considered、Chosen、Decided-by、Justification、Outcome；修订用 Supersedes: 指向前条目，旧块不删不改顺序。journal 不限 coding：调研、写作、运维只要存在「事后会被问为什么这样选」的调用，都可以记。
示例条目（示意，非官方模板原文）：
## 2026-08-12 — 缓存 TTL 选 5 分钟还是 1 小时
**Question:** PRD 未写 TTL，接口默认多少？
**Options considered:** 5m / 1h / 会话级
**Chosen:** 5m
**Decided-by:** agent (assume)
**Justification:** 只读 dashboard，可逆，Stale 5m 可接受
**Outcome:** （待部署后填）
与 Skills 和 MCP 有什么区别 对照：这是流程 skill，不连外部 API；加载时机仍走各宿主 skills 清单规则。在 Cursor 里装 skills 的路径与触发方式见 Cursor 怎么加载 Claude Skills；若你还混用 rules，分工可参考 Cursor Skills 和 Rules 怎么分。
decide、assume、escalate 怎么分
Skill 用 2×2 分类：可确定 × 可逆。能确定且有 artifact 支撑 → decide，直接选并写入 journal。可逆且影响面小 → assume，选安全默认并标记待异步 review。任一维不满足，或踩 catastrophic floor（数据丢失、不可逆花费、对外发送不可撤回内容、破坏他人依赖）→ escalate，停手问人。
「规格已授权」的不记；「agent 自己发明授权」的才记。判句：给规格的人，会不会希望在验收前知道这一下？若 issue 里已写「缓存 TTL 5m」，agent 照做不必记；若 issue 只写「要快一点」，agent 选 5m 就要 assume 并留 justification。
Handoff 时，skill 要求列出本次 append 的 assumed 与 escalated 条目，读者拿 review queue，不必通读整本 journal。swe-workflow 套件在 ship 阶段还会把条目 stage 到 per-worktree DECISIONS.staged.md，close-out 时再 promote；standalone skill 不依赖该套件也能用。
catastrophic floor 永远 escalate：删生产数据、不可逆扣费、对外发送不可撤回内容、破坏他人依赖的系统行为。即使「技术上可回滚」，只要 spec 没授权且 stakeholder 会在意，也应 escalate 而不是 assume。determinable 侧要有 artifact：issue 链接、度量截图、官方 doc 段落号，不能写「感觉 5 分钟够用」。
2×2 快速对照：可确定 + 可逆 → decide；不可确定但可逆且影响小 → assume；任一不可逆或不确定且影响大 → escalate。agent 在 assume 时必须写清默认理由，方便人异步扫一遍 DECISIONS.md 批红。
journal 文件建议进 git，与代码同 PR 审查；不要只放本地否则 handoff 丢上下文。条目只 append 意味着「改主意」用 Supersedes 新块，禁止 silent edit 旧块，否则 audit trail 断裂。大 refactor 可能一次 session 写十几条，reviewer 优先看 escalated 与 assumed，decide 且有 artifact 的可 spot check。
Codex 用户同样 npx skills add 后，在 AGENTS.md 或项目说明里要求读 log-decisions skill；Gemini CLI 若支持 skills 目录，复制 SKILL.md 即可。无 skills 宿主的纯 chat 无法自动 enforce，只能靠人粘贴 skill 正文当 system 片段，效果差一截。
什么时候值得开、什么时候别用
值得开：多人接力同一 repo、agent 长会话、PRD 故意留白让 implementer 填。DECISIONS.md 可 grep，比散落在 chat transcript 里好审计。Code review 时可要求 PR 描述链到本次新增 decision 块，reviewer 只看 delta。
别指望它替代 code review 或 ADR 全套流程：它记录 agent 当下的 judgment，不保证选项穷尽。团队若已有 rigid ADR 模板，可把 journal 当 agent 侧草稿，定期人工升格为 ADR-00N。与 .cursor/rules 或 CLAUDE.md 冲突时，以人写的 spec 为准，journal 只解释 agent 在 spec 空白处做了什么。Show HN 讨论里有人类比轻量 ADR，作者强调 append-only 与 handoff queue 才是本体。
与 MCP 决策日志不同：MCP 连的是系统；DECISIONS.md 是 git 里的文本产物，适合进 PR diff。灵感部分来自 Thariq 的 implementation-notes prompt（仓库 README 有链），1.1.0 吸收了 confirm-or-revise queue framing。早期 skill，Show HN 讨论见仓库链接；行为以 SKILL.md 版本为准。
维护习惯：每 sprint 让人 owner 扫 assume 项，确认或 Supersedes；escalated 项必须在合并前关闭。空 DECISIONS.md 也要提交仓库，skill 才能 append。monorepo 约定 journal 只在根目录一份，子包不再建副本，否则 handoff 不知道读哪份。版本升级 skill 后 diff 旧 SKILL.md，把 catastrophic floor 新条目同步进团队 onboarding。
常见问题
和 CLAUDE.md / PLAN.md 有什么分工？
CLAUDE.md 管长期约束与工具习惯；PLAN 管当前任务步骤。DECISIONS.md 只记「这一下选了 A 而非 B」的 consequential call，且 append-only。三者不要混写，否则 grep 决策理由时会被流程噪音淹没。若 PLAN 里临时写了「先用 Redis」，而 agent 在 DECISIONS 里又记一遍，属于重复；应把 PLAN 更新为 spec 授权，或删掉 journal 里等价条目。
Cursor 里 agent 不自动写 DECISIONS.md 怎么办？
确认 skill 已进宿主清单且 description 够触发（Cursor 侧注意 skills 描述长度与加载规则）。在任务 prompt 里显式要求「凡 spec 未覆盖的选择走 log-decisions」；必要时把 DECISIONS.md 路径写进项目 rules。仍不写时，是宿主未加载 skill，不是 skill 缺 API。
可在 PR template 加 checkbox：「本 PR 若含 agent assume 决策，链接 DECISIONS.md 对应段落」。Review 时 grep Decided-by: agent 快速扫 assume 项。与 ADR 并存时，约定 DECISIONS 是 working log，ADR 是 ratified 结论，避免同一决定写两处不同版本。首次引入 skill 时让人类在 DECISIONS.md 顶部写三行格式示例，agent 后续会模仿块结构，减少字段漏填。Outcome 字段可在部署后补写，便于 retro 时对照实际结果与当初 justification 是否一致。
若仓库同时开了多个 agent 会话，约定只有一个 worktree 写根目录 DECISIONS.md，其余写 DECISIONS.staged.md 再合并，减少并行 append 冲突。这比事后从聊天记录考古「当时为什么选方案 B」便宜得多。