用 AI 在 PR 中自动补齐架构决策记录

dev.to · AI#GitHub#架构决策#自动化

Editor brief · 编辑速览

教程使用 GitHub Agentic Workflows 检查 PR 及已有架构决策记录，在需要时起草包含背景、备选方案和后果的 ADR。示例依赖 GitHub Actions、CLI 和受支持的 AI 引擎，相关框架仍处于公开预览。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

代码能说明改了什么，却往往解释不了为什么要改。

开发者可能引入缓存、更换数据库，或调整服务边界。实现最终合入了，但背后的理由只存在于 pull request 的讨论中，甚至根本没有记录。几个月后，其他人只能对着代码，还原当初的决策过程。

Architecture Decision Records（ADRs，架构决策记录）通过记录决策的上下文、备选方案和后果来解决这个问题。麻烦在于，人们总忍不住把这件事往后拖。

2026 年 10 月 15 日，GitHub Agentic Workflows 重点介绍了一个 Design Decision Gate：它会检查 pull request，查找已有的 ADR，并在需要时起草一份。下面，我们用 GitHub Agentic Workflows 构建一个更精简的版本。这是 GitHub 推出的仓库自动化框架，由 AI Agent 驱动。

1. 设置 GitHub Agentic Workflows

你需要一个已启用 Actions 的 GitHub 仓库、GitHub CLI，以及受支持的 AI 引擎访问权限。本例使用 GitHub Copilot；其他引擎需要配置各自对应的身份验证。

安装 Agentic Workflows 扩展，并登录你的 GitHub CLI 账号：

gh auth login --scopes repo,workflow
gh extension install github/gh-aw

GitHub Agentic Workflows 目前处于公开预览阶段，语法和功能可能发生变化。开始设置前，请先查看最新的快速入门指南。

在仓库中创建一个名为 implementation 的标签。我们会用它来决定哪些 pull request 需要分析，避免每次小改文档都消耗 token。

2. 定义工作流

在仓库的 GitHub 工作流目录中创建一个工作流源文件，例如 .github/workflows/adr-gate.md：

---
description: "Propose ADRs for significant pull requests"
on:
  pull_request:
    types: [labeled, ready_for_review]
    names: ["implementation"]
permissions:
  contents: read
  pull-requests: read
  copilot-requests: write
engine: copilot
tools:
  github:
    mode: gh-proxy
    toolsets: [default, repos]
safe-outputs:
  add-comment:
    max: 1
  push-to-pull-request-branch:
    allowed-files:
      - docs/adr/**
  noop:
timeout-minutes: 15
---

这份配置指定了要监听的 pull request 事件、使用的 AI 引擎、所需权限，以及允许执行的写入操作。最关键的安全设置，是限制生成内容的修改范围：即使 Agent 获准提出修改，它对分支的写入操作也只能发生在 ADR 目录中。Agent 任务本身对仓库只有只读权限；允许的写入操作由配置好的 safe outputs 单独处理。

对于个人仓库，Copilot 身份验证可能需要配置 COPILOT_GITHUB_TOKEN secret。请按照所选引擎的身份验证指南操作。

3. 给 Agent 一个明确而有限的任务

给 Agent 的指令应该只定义一项职责：判断某个 pull request 是否引入了需要记录的重要架构决策。

它应该阅读 pull request 描述、检查变更文件，并搜索已有 ADR，确认是否有记录涵盖这项决策。如果只是常规修改，就解释为什么不需要 ADR。如果已有 ADR 涵盖了这次变更，就报告实现是否符合该决策。

如果某项重要决策缺少文档，Agent 应该起草一份 ADR，包含四个部分：上下文、决策、考虑过的备选方案，以及后果。

每一项陈述都必须以 pull request 或仓库中已有的证据为依据。如果无法推断出决策理由或备选方案，Agent 应该明确说明，而不是编造作者的思考过程。

工作流应该在指定的 ADR 目录中提出草稿，并在 pull request 中留下一条简洁的评论，说明哪些内容需要审阅。

在结束标记 --- 下方追加以下指令：

# Architecture Decision Gate

Inspect the triggering pull request and determine whether it
introduces a significant architectural decision.

## Procedure

1. Read the pull-request description, changed files, and diff.
2. Search `docs/adr/` for an existing decision that covers the change.
3. If the change is routine or no architectural decision is evident,
   use `noop` and briefly explain why.
4. If an existing ADR covers the change, compare its decision with
   the implementation and report alignment or specific divergences.
5. If a significant decision lacks an ADR, draft one using:
   - Context
   - Decision
   - Alternatives Considered
   - Consequences

Base every claim on the pull request or existing repository evidence.
Write "Not inferable from current PR evidence" where information
is missing. Never invent the author's rationale or alternatives.

If a draft is justified, write it under `docs/adr/` using a
filename based on the pull-request number and a short title.
Use the configured branch-write safe output to propose the draft,
then use the comment safe output to explain what requires review.

Keep the comment concise and provide one clear next action.
If nothing requires action, use `noop`.

这个版本有意比 GitHub 自己的示例更精简。后者还包含对标签、关联 issue、大型 diff、可配置目录和报告模板的额外处理。需要这些功能时，请参考原始工作流。

4. 编译并审查工作流

使用 Agentic Workflows CLI 编译并验证工作流：

gh aw compile
gh aw validate

对照 Markdown 源文件，审查生成的 .github/workflows/adr-gate.lock.yml，然后将这两个文件一起提交到仓库：

git add .github/workflows/adr-gate.md \
  .github/workflows/adr-gate.lock.yml
git commit -m "Add AI architecture decision workflow"
git push

不要把编译成功当成 Agent 行为正确的证明。编译检查的是工作流定义；运行时的行为仍然需要测试。

5. 测试两个形成对照的 pull request

在生产代码库中启用这个工作流之前，先用测试仓库验证。

测试 A：常规修改。创建一个只修正拼写错误的 pull request，添加 implementation 标签来触发分析。Agent 应该解释为什么不需要 ADR，并且不再执行其他操作。

测试 B：架构变更。创建一个引入新数据库或调整服务边界的 pull request，但不记录决策理由。Agent 应该根据现有证据起草 ADR，或者指出缺少哪些信息。

检查 Actions 日志、评论，以及生成的所有文件。确认写入范围始终限制在指定的 ADR 目录内，并且能够安全处理不受支持或存在歧义的情况。在这两个场景都实际运行过之前，不要宣称测试成功。

6. 把它当作审阅者，而不是架构师

根据 diff 生成的 ADR，仍然只是对作者意图的一种推测。补丁能表明数据库发生了更换，但通常无法解释团队考虑过的所有备选方案，也无法呈现全部运维约束。

因此，工作流应该提供一个供人审阅的起点，而不是悄悄把看似合理的猜测变成组织知识。pull request 的 diff 同样是不可信输入：保持最小权限，并在启用之前检查生成的工作流。

这个原型会对决策发表评论，并提出文档草稿。它不能保证缺少 ADR 的 pull request 无法合并。要强制执行这项策略，需要额外添加并测试明确的 required-check 或分支保护机制；仅有评论并不能构成合并门禁。

收益很直接：趁上下文还清晰时，把重要的设计决策记录下来，同时不必让工程师每次都从空白页开始写 ADR。Agent 负责初稿，人类仍然对决策负责。

如需采取进一步行动，你可以考虑屏蔽此人和／或举报滥用行为。