技能介绍

为什么需要记录架构决策？

代码仓库能展示系统“做了什么”，却往往无法解释“为什么这么做”。随着项目迭代，技术选型背后的上下文极易丢失，导致后来者重复造轮子，或者对历史遗留设计感到困惑。架构决策记录（ADR）正是为了解决这个问题，它强制团队在实施前捕捉Context（背景）、Decision（决策）与 Consequences（后果），将隐性的技术债显性化。

核心能力与工作流

该技能提供了一套完整的 ADR 管理规范。首先明确了触发边界：在引入新框架、数据库选型或安全架构设计时应当编写 ADR；而日常 Bug 修复、配置调整或 minor 版本升级则直接跳过。其次，它内置了五种模板：

标准 MADR 格式与轻量级记录
Y-Statement 与废弃记录
RFC 风格

覆盖从立项到下线的完整生命周期。在管理层面，技能指导你建立规范的目录结构与 README.md 索引，并通过 adr-tools 等工具实现自动化，从而构建出一张清晰的决策图谱。

适用边界与安全原则

在遵循“尽早编写、保持简短、诚实记录代价”等最佳实践的同时，本技能有严格的安全边界。它不会自动安装依赖、修改系统权限或创建持久化任务。当流程涉及发布、删除、付款等外部写入操作时，必须先展示目标与影响并取得明确确认。凭据仅用于指定的官方服务，命令和代码默认仅作参考，只有在范围清晰且用户明确授权时才会执行。