用途:在需要创建、编写、更新、修订、取代或评估架构决策记录(ADR)时,记录持久性架构决策,同时不丢失当前状态基线。ADR 记录“为什么做此决策”,基线记录决策后架构“是什么”。该技能是惰性的、面向具体任务的工作流,不替代完成前验证,不授予完成权限,也不产生权威的 GateDecision 或 PolicySnapshot 输出。
主要能力:判断架构决策是否需要 ADR;执行 ADR 创建门(难以逆转、脱离上下文会令人意外、存在真实权衡);应用 Retro/Memory 过滤器(已执行的持久决策可进入 ADR 或基线记忆,未执行的想法不进入已接受架构记忆,流程说明可用更轻记录);选择唯一 ADR 动作(create、amend、supersede、skip);选择归属面(项目 docs/adr/、docs/aegis/adr/、现有 ADR 或更轻记录);执行基线同步闭合。
使用方式:决策或写入前,先阅读 docs/adr/ADR-CREATION-GATE.md、docs/current/AEGIS_ADR_AUTO_BACKFILL.md 及目标项目拥有受影响架构面的当前 ADR、基线或权威文档的最小相关摘录。当归属面为目标项目的 docs/aegis/adr/ 时,使用共享工作区助手而非临时创建文件:create 用 <aegis-workspace-helper> new-adr --root <target-project-root> ...;amend 用 <aegis-workspace-helper> amend-adr --root <target-project-root> --path docs/aegis/adr/ADR-####-<slug>.md ...;supersede 用 <aegis-workspace-helper> supersede-adr --root <target-project-root> --path docs/aegis/adr/ADR-####-<slug>.md ...。写入后运行 <aegis-workspace-helper> check --root <target-project-root>。助手只负责文件形态、ADR 编号、取代标记和 INDEX.md 覆盖,不决定架构真相、门是否通过或基线同步是否语义充分。
适用场景:用户要求创建、编写、更新、修订、取代或评估 ADR;判断是否需要 ADR;记录持久架构决策或决策日志条目;在 ADR 相关架构变更后闭合基线同步;验证 ADR 操作未使架构基线过期。
限制:不用于简单措辞修改、普通 README 清理、仅测试覆盖改进、低风险单文件变更,或仅恢复现有基线的缺陷修复。若 ADR 门或归属面决策为 skip,不要仅因助手存在而创建或修订 ADR 文件。设计/计划中的 ADR 信号是后续完成的备注,不是 ADR 文件。仅对已执行的持久决策创建/修订/取代 ADR;若现有 ADR 已覆盖该决策面,应修订而非新建同级文件。若未做基线写回,须说明现有基线为何仍然有效;create、amend、supersede 后不得让基线同步保持隐式。常见错误包括:门未通过却因主题重要而写 ADR;在 ADR 中记录原因却让基线当前状态事实过期;未先判断漂移是否有意且值得 ADR 就更新基线以匹配漂移;无明确镜像关系却将同一决策重复写入项目 docs/adr/ 和 docs/aegis/adr/;把 ADR 或基线同步当作工作已完成的证明。