mcpField
R
recording-architecture-decisions

recording-architecture-decisions

github.com/ganyuanran开发1.4k55 次安装4 天前更新
代码仓库

关于 recording-architecture-decisions

面向特定任务的工作流，用于创建、修改或评估架构决策记录，并检查当前状态文档是否同步。它帮助贡献者判断决策条件、记录归属和基线闭环，但不授予完成授权。

主要功能

  1. 01按可逆性、意外性和权衡筛选决策
  2. 02选择创建、修订、取代或跳过
  3. 03确定权威 ADR 存放位置
  4. 04检查 ADR 变更后的基线同步
  5. 05通过辅助命令执行受支持的写入

适用场景

  1. 01判断持久架构选择是否需要 ADR
  2. 02架构决策变更后更新现有 ADR
  3. 03检查当前状态文档是否反映 ADR

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ganyuanran/aegis --skill recording-architecture-decisions

安装后在 Claude Code 中输入/recording-architecture-decisions确认已加载。

详细介绍

记录架构决策

目的

记录持久的架构决策，同时确保当前状态基线闭合。ADR 记录做出决策的原因；基线记录该决策之后的架构状态。

这项技能是一种按需使用、针对特定任务的工作流。它不会取代 verification-before-completion，不会授予完成权限，也不会生成权威的 GateDecision 或 PolicySnapshot 输出。

必需的阅读材料

在做出决定或撰写文档之前，阅读以下文档中最相关的部分：

  • docs/adr/ADR-CREATION-GATE.md
  • docs/current/AEGIS_ADR_AUTO_BACKFILL.md
  • 目标项目中负责受影响架构范围的当前 ADR、基线或权威文档

对于 Aegis 仓库的变更，遵循本仓库 docs/adr/ 和 docs/current/ 的权威顺序。对于拥有自身 ADR 体系的目标项目，遵循该项目负责方的规范，而不要在 docs/aegis/adr/ 中重复记录同一决策。

适用场景

用户要求执行以下操作时，使用此技能：

  • 创建、撰写、更新、修订、取代或评估 ADR
  • 判断是否需要架构决策记录
  • 记录持久的架构决策或决策日志条目
  • 在涉及 ADR 的架构变更后完成基线同步
  • 验证 ADR 操作没有导致架构基线过时

对于简单的措辞编辑、普通的 README 清理、仅改进测试覆盖率、低风险的单文件变更，或仅恢复现有基线的错误修复，不要使用此技能。

决策流程

  1. 确定候选决策及其证据来源。
  2. 运行 ADR 创建门槛检查：
    • 难以撤销
    • 缺少背景信息时会令人意外
    • 存在真实的权衡
  3. 应用 Retro / Memory 筛选：
    • 已执行的持久决策可记录为 ADR 或基线记忆
    • 未执行的想法不应纳入已接受的架构记忆
    • 如果流程说明不会改变当前架构状态，可采用较轻量的记录方式
  4. 确定唯一一项 ADR 操作：创建、修订、取代或跳过。
  5. 选择归属位置：项目的 docs/adr/、docs/aegis/adr/、现有 ADR，或较轻量的记录。
  6. 完成基线同步闭合。
  7. 如果要写入文件，遵循本地 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 门槛或归属位置的判断结果是 skip，不要仅仅因为辅助工具存在就创建或修订 ADR 文件。设计或计划中的 ADR 提示只是供日后完成的备注，不是 ADR 文件。只有已执行的持久决策才应创建、修订或取代 ADR；如果现有 ADR 已涵盖该决策范围，应修订它，而不是另建同级 ADR。

基线同步闭环

如果 ADR 操作为创建、修订或取代，则必须检查基线同步。

在决策更改或确认以下任何内容时，必须同步基线：

  • 规范所有者或所有权映射
  • 公共 API、架构、工件形态或行为契约
  • 依赖方向或允许的跨模块关系
  • 事实来源所有者
  • 主机兼容策略或安装／发现契约
  • 方法包／运行时核心边界
  • 运行时就绪工件边界或证据模型
  • 保留的回退方案、适配器、兼容路径、重复所有者或弃用时间表
  • 已接受的架构范围内实现偏差
  • 否则未来贡献者可能会误解的发布或分发策略

如果未回写基线，请说明现有基线为何仍然有效。 创建、修订或取代 ADR 后，绝不能让基线同步处于未说明状态。

精简输出约定

Aegis Visibility:
- Why executed-decision filtering, ADR gate, owner surface, or baseline sync matters now:

Decision Candidate:
- Summary:
- Evidence source:

ADR Gate:
- Hard to reverse: yes | no | unknown
- Surprising without context: yes | no | unknown
- Real trade-off: yes | no | unknown

Retro / Memory Filter:
- Classification: executed durable decision | unexecuted idea | process note
- Memory action: record | skip | lighter record
- Reason:

ADR Action:
- create | amend | supersede | skip
- Reason:

Owner Surface:
- Target:
- Existing ADR / baseline checked:

Baseline Sync:
- Required: yes | no | unknown
- Target:
- Action: create snapshot | update baseline | cite unchanged | blocked
- Reason:

Boundary:
- Advisory method-pack signal only; not completion authority.

常见错误

  • 仅仅因为某个主题感觉重要就编写 ADR，尽管未通过门槛检查。
  • 在 ADR 中记录原因，却让基线中的当前状态事实保持过时。
  • 未先判断偏差是否有意且是否值得记录在 ADR 中，就更新基线以匹配偏差。
  • 在项目的 docs/adr/ 和 docs/aegis/adr/ 中重复记录同一决策，却未明确说明两者存在镜像关系。
  • 将 ADR 或基线同步视为工作已完成的证明。

评论

支持 Markdown