用途:当用户要求记录某项技术决策、架构选择或解释原因时,create-adr 技能会生成结构化的架构决策记录(ADR),采用 Michael Nygard 格式,便于后续工程师了解决策背景与取舍。
主要能力:读取项目内 .chalk/docs/engineering/ 的既有架构文档与 ADR;通过匹配 adr.md 找出最大编号并加一(无则从 1 开始);梳理决策、驱动力与约束、备选方案;若用户未提供替代方案,可根据项目上下文提出 2 至 4 个选项,且至少包含 2 个替代方案(含所选方案);按固定格式撰写并保存文件;最后向用户确认路径、决策摘要及关联 ADR。
使用方式:文件保存为 .chalk/docs/engineering/<n>adr<decision_slug>.md,例如 3_adr_use_postgres_over_mongodb.md。ADR 格式包含状态(Proposed、Accepted、Deprecated、Superseded)、日期、Context、Decision、Alternatives Considered 表格、Consequences(Positive、Negative、Neutral)、Revisit When。状态更新时,若被取代,旧 ADR 状态应指向新 ADR。
适用场景:记录已做或拟做的重大技术选择,例如数据库选型、事件溯源、单体仓库迁移等,特别是在需要留存决策理由、避免重复评估时。
限制与注意:资料未提供安装命令或运行环境要求;该技能依赖 .chalk/docs/engineering/ 目录与对话上下文中的参数($ARGUMENTS)。撰写时需避免模糊表述,替代方案的拒绝理由要具体,后果需包含负向权衡与缓解措施,重访触发条件应可衡量。可补写追溯性 ADR,但须在 Context 中说明其事后记录性质。每个 ADR 仅对应一项决策。