adr-author

adr-author

概述

此技能编码了 ADR Creator Agent 使用的架构决策记录（ADR）各阶段撰写规范。没有 ADR Creator 状态文件时，也支持直接调用。直接调用方需先运行 adr-identity.instructions.md 中的会话恢复与引导协议：解析或创建 .copilot-tracking/adr-plans/{projectSlug}/state.json，确认 entryMode、projectSlug 和 outputTemplate，然后继续执行状态中记录的阶段。此技能支持三种入口模式和两种输出模板，并将它们统一汇入 Govern 阶段，在此阶段原子化地写入最终 ADR 文件并更新沿袭信息。

入口模式（state.entryMode）：

• capture — 通过用户回答 Frame 和 Decide 阶段的问题进行交互式撰写。
• from-planner-handoff — 从上游规划器（Security、RAI、SSSC）进入，Frame 字段已预先填充。退出 Frame 前仍需用户确认。
• adopt-template — 一次性设置模式，用于导入项目现有的 ADR 模板，并生成首份 ADR 和已提交的 .adr-config.yml。

输出模板（state.outputTemplate）：

• y-statement — 适用于低风险或可逆决策的精简 Y-Statement 形式 ADR。Frame 内容精简；ASR 触发条件为可选。
• madr-v4 — 适用于架构重大决策的完整 MADR v4.0.0 ADR。Frame 阶段必须评估 ASR 触发条件。

入口模式与输出模板相互独立：from-planner-handoff 会话可以使用 y-statement 或 madr-v4，capture 会话也同样如此。adopt-template 模式生成的输出则遵循用户规范化后的模板。

生命周期一览：

模式	阶段顺序	输出
capture	Frame → Decide → Govern	按 outputTemplate 定型（y-statement 或 madr-v4）
from-planner-handoff	Frame（确认预填内容）→ Decide → Govern	按 outputTemplate 定型（y-statement 或 madr-v4）
adopt-template	Ingest → Normalize → Derive Questions → Fill → Govern	按 BYO 合约生成首份 ADR + .adr-config.yml

状态机、硬性退出门槛、自主性等级（manual、partial、full）以及规范的 state.json 架构均在 adr-identity.instructions.md 中定义。此技能提供撰写活动和产物合约；不会重新定义状态机。

规划

活动：

• 范围 — 用一到两句话记录决策；将范围限定为单个项目。
• 决策者 — 记录 deciders、consulted、informed（与 RACI 保持一致）。优先使用角色或团队标识，而非个人姓名；绝不要在任何 ADR 字段中记录个人联系方式、机密、凭据，或第三方或客户的个人身份信息（PII）。
• 驱动因素 — 列出决策驱动因素（功能需求、业务目标）。
• 约束 — 列出不可妥协的条件（法规、平台、合同、时间）。
• ASR 触发条件评估 — 当 state.outputTemplate == 'madr-v4' 时必须进行。根据 adr-standards.instructions.md 中的评估标准评估触发条件，并将结果记录在 state.asrTriggers[] 中。评估标准和完整分类体系请参阅该文件以及 references/asr-trigger-taxonomy.md。
• 图表格式提示 — 当 state.userPreferences.diagramFormat 未设置时，检查 .copilot-tracking/architecture-diagrams/state.json 中的架构图根状态；如果该文件提供了 userPreferences.diagramFormat，则使用该值。否则，询问用户选择 ascii 或 mermaid，将答案保存到 state.userPreferences.diagramFormat，并保存到架构图根状态，以便独立复用。如果调用方、交接内容或现有 ADR 状态已提供 state.userPreferences.diagramFormat，则将其视为权威值，不要再次询问。规划阶段退出前必须完成此项。

硬性退出门槛（重申自 adr-identity.instructions.md）：

在记录以下所有内容之前，不得进入下一阶段：范围声明、决策者列表、决策驱动因素、ASR 触发条件判定（当 outputTemplate == 'madr-v4' 时），以及 userPreferences.diagramFormat。进入下一阶段前，用户必须确认规划摘要。

输出产物：

• 进行中的 ADR 草稿中的规划部分（仅为工作草稿；尚未写入磁盘）。
• 更新后的 state.json 字段：scope、deciders、consulted、informed、drivers、constraints、asrTriggers（当 outputTemplate == 'madr-v4' 时）、userPreferences.diagramFormat。

决策

活动：

• 列出选项 — 至少考虑两个选项。只有一个选项的 ADR 会在此门槛被拒绝。
• 评估标准 — 根据规划阶段记录的驱动因素和约束，对每个选项进行评分。
• 选择决策结果 — 指明选定的选项并阐述理由。
• 后果 — 记录正面、负面和中性的后果。负面后果不可省略；未记录任何缺点的 ADR 会在此门槛被拒绝。

Y 语句的编写（当 state.outputTemplate == 'y-statement' 时）：

• 使用 templates/y-statement.md 中原样的六槽公式，编写所选选项：

  在（使用场景）这一背景下，面对（关注点），我们决定选择（选项）并放弃（替代方案），以实现（质量），同时接受（缺点）。

• 对于 y-statement 模板，Y 语句就是决策阶段的全部输出。省略完整的 MADR 选项表。

硬性退出门槛：

在记录至少两个已考虑的选项、选定的选项和决策理由之前，不得进入下一阶段。进入下一阶段前，用户必须确认决策摘要。

治理

此阶段汇合所有三种入口模式，也是唯一会将 ADR 文件写入磁盘的阶段。

活动：

1. MADR v4 前置元数据组装 — 根据 templates/madr-v4.md 渲染 ADR 前置元数据。该模板逐字转载自 MADR v4.0.0（CC0）；出处信息请参阅 references/standards-excerpts.md。在其上合并 templates/madr-v4-frontmatter-overlay.md，以注入 hve-core 扩展字段（id、deciders、tags、supersedes、superseded-by、related、asr_triggers），而不修改逐字转载的上游模板（GP-17）。
2. 图表渲染 — 根据 state.userPreferences.diagramFormat，嵌入来自 templates/diagram-ascii.md 或 templates/diagram-mermaid.md 的图表正文。技能调用方无需按平台分支；模板选择完全由数据驱动。当图表源自基础设施源文件（Terraform、Bicep、ARM）时，使用 state.userPreferences.diagramFormat 中记录的权威格式调用 architecture-diagrams 技能，并将其输出嵌入脚手架片段所在位置。独立图表生成使用 architecture-diagrams 根状态契约，而非 ADR 状态。
3. 谱系验证 — 应用下方概述的六条替代规则；完整内容见 references/lineage-rules.md。
4. 前置元数据验证 — 针对暂存的 ADR 文件调用 scripts/validate_frontmatter.py。如果存在架构或枚举违规，脚本会返回非零退出码；它是前置元数据结构的唯一权威来源。
5. 谱系分配器 — 调用 scripts/update_lineage.py 修改 .adr-config.yml。分配器是唯一可以写入 last_decision_id 的程序。禁止手动编辑 last_decision_id。
6. 最终写入 — 将 ADR 写入 docs/planning/adrs/{NNNN}-{slug}.md。路径由分配器签发的 NNNN 和 slug 化后的 ADR 标题决定。
7. 交接触发 — 按照 adr-handoff.instructions.md 生成双格式（ADO + GitHub）工作项。此技能在生成交接信息后停止；路由由 Agent 负责。

治理过程使用 adr-identity.instructions.md 和 shared/disclaimer-language.instructions.md 要求的自主性与免责声明横幅。请勿在此重复这些文本；应在运行时加载。

替代谱系规则（摘要）

简要列举。完整规范文本和边缘情况见 references/lineage-rules.md。

1. supersedes 和 superseded-by 均为标量字符串或 null。
2. 单父级替代 — 给定 ADR 最多只能有一个 superseded-by。
3. 状态转换 — 替代 ADR 的 status 变为 accepted；被替代 ADR 的 status 变为 superseded。
4. 谱系更新是原子操作 — 两个 ADR 文件都必须在同一个治理阶段更新。
5. 谱系分配器（scripts/update_lineage.py）是 .adr-config.yml 中 last_decision_id 的唯一写入方；禁止手动编辑。

状态分类

ADR 的 status 是六种固定值之一。完整定义和生命周期转换见 adr-standards.instructions.md。

• proposed — 正在积极起草；尚未作出决定。
• accepted — 决策已采纳；是当前范围的权威依据。
• rejected — 已考虑但未采纳；保留以供历史参考。
• deprecated — 不再推荐，但尚未被替代。
• superseded — 按照下方谱系规则被更新的 ADR 替代。
• withdrawn — 提案在决策前撤回。

ASR 触发项目录（摘要）

仅当 state.outputTemplate == 'madr-v4' 时，才会评估 ASR（架构重大需求）触发项。固定枚举包含八个值：

• cost
• performance
• security
• compliance
• availability
• scalability
• maintainability
• evolvability

触发规则、评估提示词和映射示例在 adr-standards.instructions.md 中定义，并在 references/asr-trigger-taxonomy.md 中详细说明。请勿引入固定枚举之外的触发值。

采用模板的生命周期

五步概览。完整生命周期（包括 GP-13（.adr-config.yml 架构和两层配置解析））见 adr-byo-template.instructions.md。

1. 接收 — 接受用户现有的 ADR 模板文件或模板目录。
2. 规范化 — 调用 scripts/normalize_template.py，将模板转换为规范的 ADR frontmatter 和章节结构。
3. 推导问题 — 根据规范化模板中的必填字段，生成 Frame 和 Decide 问题集。
4. 填写 — 执行推导出的问题，填充首个 ADR。
5. 治理 — 运行标准 Govern 阶段。如果采用的模板缺少 lineage_fields，Agent 必须警告用户，并要求用户明确确认后才能写入；这是 adr-byo-template.instructions.md 中所述的警告并确认式 Govern 行为。

模板

• templates/madr-v4.md — MADR v4.0.0 ADR 模板（原文，CC0）。当 state.outputTemplate == 'madr-v4' 时，用于 Govern frontmatter 组装。
• templates/y-statement.md — Decide 组装时使用的六槽位 Y-Statement 公式；当 state.outputTemplate == 'y-statement' 时选用。
• templates/diagram-ascii.md — ASCII 图表块；当 state.userPreferences.diagramFormat == "ascii" 时选用。
• templates/diagram-mermaid.md — Mermaid 图表块；当 state.userPreferences.diagramFormat == "mermaid" 时选用。

参考资料

• references/standards-excerpts.md — MADR v4.0.0 原文及 CC0 署名；Y-Statement 署名；状态分类。
• references/lineage-rules.md — 六条替代规则的完整文本，包含边缘情况和示例。
• references/asr-trigger-taxonomy.md — 完整的 ASR 触发分类、评分标准提示词，以及八个枚举值各自的示例。

脚本

• scripts/render_template.py — 根据 Frame+Decide 负载渲染 templates/ 中的模板，生成内存中的 ADR 草稿。带路径遍历防护：拒绝任何位于 docs/planning/adrs/ 之外的输出路径。
• scripts/validate_frontmatter.py — 根据 MADR v4 架构和封闭枚举验证 ADR frontmatter。违规时返回非零值。针对同一根目录进行路径遍历防护。
• scripts/update_lineage.py — .adr-config.yml 中 last_decision_id 的唯一写入方。以原子方式修改前置 ADR 的 superseded-by，并更新新 ADR 的 supersedes。带路径遍历防护。
• scripts/normalize_template.py — 将用户提供的 ADR 模板转换为 templates/madr-v4.md 使用的规范结构。仅用于 adopt-template 生命周期。带路径遍历防护。
• scripts/scan_sensitive_content.py：确定性的信息披露风险扫描器，接受文件路径或 stdin，并输出经过掩码处理的 JSON 发现结果。基本行为可检测高置信度 PII。--public 会额外检测内部 URL。--data 会独立额外检测结构化敏感列、连接信息、凭据、样本行和国际标识符。--denylist <path> 会独立额外检测 UTF-8 文件中的字面客户术语（不区分大小写）；该文件通过与扫描路径相同的允许根目录保护机制解析，并受文件大小、术语数量和最短术语长度限制。--allow-root <dir> 会向该保护机制添加一个目录。各标志按并集方式组合，不会改变未使用标志时的 ADR 行为。持久化 ADR 写入以及外部发送或交接输出前必须运行。

扫描器报告约定

扫描器在每种终止路径（包括错误路径）上都会向标准输出打印一个 JSON 对象，以便调用方可以断言字段，而不必解析文本。该对象包含 schema_version（scan-sensitive-content-v1）、status（completed 或 error）、modes（public、data 和 denylist 的布尔值）、denylist_rule_count、findings，以及包含 high、warn 和 total 计数的 summary。当 status 为 error 时，还会包含带有稳定 code 和 message 的 error。退出代码分别为：扫描完成且没有高置信度发现时为 0，扫描完成且至少有一项高置信度发现时为 1，发生错误时为 2。要求执行拒绝名单强制检查的调用方会断言 modes.denylist 为 true，且 denylist_rule_count 大于零，因此空的或未加载的拒绝名单不会悄然禁用检查。

所有脚本都将其工作目录视为不可信输入。ADR 编写脚本会拒绝解析后位于项目 ADR 根目录之外的路径。scan_sensitive_content.py 扫描的不是 ADR 内容，因此它会拒绝解析后位于其允许根目录之外的路径：此技能的目录、仓库根目录、命令行传入的每个路径的父目录，以及通过 --allow-root 提供的任何目录。

来源归属

• templates/madr-v4.md — 逐字节复现自 MADR v4.0.0（标签 4.0.0，文件 template/adr-template.md），以 CC0-1.0 发布。CC0 不要求注明来源；此处记录仅为提高透明度。上游的排版异常（例如 status: 占位符中引号不成对）有意保留，以确保文件与上游版本的差异干净。

强制加载指令

ADR Creator Agent 根据 adr-identity.instructions.md 强制执行“阶段→章节”加载约定。每个阶段都必须在执行阶段工作前加载此技能中对应的章节，并且必须将章节锚点追加到 state.phaseSkillsLoaded：

阶段	章节锚点	必需的 phaseSkillsLoaded 条目
Frame	#frame	adr-author#frame
Decide	#decide	adr-author#decide
Govern	#govern	adr-author#govern

Agent 通过对此技能文件调用 read_file 来加载章节，并在执行任何阶段工作前将条目记录到 state.phaseSkillsLoaded。phaseSkillsLoaded 是持久的加载历史，并不能证明当前模型上下文中包含相应指南。在同一个实时上下文中，重新进入已读取过对应章节的阶段时，无需重新加载。冷启动、恢复或上下文摘要后，即使已记录相应条目，Agent 仍会重新加载当前阶段的章节。