SuperAPI AI 工具集

record-a-decision

通用与其它

查看项目

更新于 10-15 22:38

技能介绍

用途:把已经做成的技术决策写成冻结的架构决策记录(ADR),保存在 decisions/ 目录下,供未来读者理解“决定了什么、为什么会有这个疑问、团队现在要承担什么”。它只做记录,不做决策。

主要能力与写法:文件名采用 NNNN-title.md(4 位零填充序号 + kebab 标题);状态词为 proposed / accepted / deprecated / superseded;使用 decision 模板,正文严格按 ## Context、## Decision、## Consequences 三段顺序。前置元数据含 type、description、status、date、deciders、supersedes、tags。

使用流程要点:先确认决策已经做出(仍在校衡选项应转 /frame-a-proposal;设计是否合理的问题应转 /review-a-design);写入前先扫描既有记录,判断是否与已接受记录冲突;用 ls -A decisions/ 取下一个序号——不猜。从模板创建,例如 write({ document: { path: "decisions/0012-adopt-event-sourcing-for-orders.md", template: "decision" } })。Context 写清系统状态、触发变化、约束与张力;Decision 用主动语态一段话说清选择并列出被否方案;Consequences 同时写收益、成本、新增义务与关闭的选项,至少写一条真实负面后果。若取代旧记录,双向链接:新记录 supersedes 指向旧路径,旧记录 status 置为 superseded 并加指向新记录的说明,且不改旧记录的正文。最后用 links 补回链、用 audit 校验无断链与 lint 问题,并确认状态是 accepted 还是待批准。

适用场景与限制:适用于已定决策的留痕与历史追溯。不在用户未做决策时代为决定,不改写已接受记录的正文,不把实现细节写进 ADR(移步 spec),不省略负面后果。平台 /open-knowledge 技能仍管辖所有 markdown 操作;具体模板字段与工具命令的可用性以该技能实际支持为准,资料未提供部分暂未说明。