Continue 意图层同步机制：解析 `.continue/checks/update-agents-md.md` 中的 AGENTS.md 维护 Agent

本文以 Continue 仓库中的检查定义文件 update-agents-md.md 为主体，完整拆解“意图层同步”这一 Agent 检查项的设计思路：它如何定义意图层（AGENTS.md / CLAUDE.md）的概念、如何判断一次 PR 是否需要更新意图文档、如何按“叶节点优先”策略执行编辑，以及如何通过 CLI 的 cn checks 机制查看、接受或拒绝该 Agent 产出的修改。读完本文，你可以理解 Continue 团队如何用结构化 Prompt 让 AI Agent 自动维护代码库中“代码看不见的知识”，并能在自己的项目中复刻这套 PR 级文档同步检查。

一、文件定位：这是一个 Check 定义，而非普通文档

update-agents-md.md 位于仓库的 .continue/checks/ 目录下，与 anti-slop.md、react-best-practices.md、security-audit.md、stale-comments.md、update-continue-docs.md 等并列。.continue 目录是 Continue 的本地配置目录，还包含 agents/（审查型 Agent 定义）、rules/（编码规则）、prompts/（提示词模板）以及 environment.json（仅声明 "install": "npm i" 一条环境安装指令）。

该文件的结构分为两部分：

1. YAML Frontmatter，用于注册检查项元信息：

   ---
   name: Update AGENTS.md
   description: Update AGENTS.md
   ---
   

2. Markdown 正文，即完整的 Agent 系统提示词，定义了角色、任务、处理流程、质量标准与反模式清单。

从文件组织方式看，.continue/checks/ 下每个 .md 文件就是一个可独立运行的“检查”（check）：frontmatter 的 name/description 用于展示与索引，正文则是驱动 Agent 行为的完整指令。同一目录中的 update-continue-docs.md 是职责相近的姊妹检查——它面向 docs/ 下的用户文档，而 update-agents-md.md 面向的是面向 AI 协作者的意图层文档，两者共同构成 Continue 仓库“代码变更带动文档自动跟进”的机制。

二、核心概念：什么是意图层（Intent Layer）

文档开宗明义地定义了 Agent 的角色：

You are an Intent Layer maintenance agent. Your job is to keep the codebase's intent documentation (AGENTS.md, CLAUDE.md, or similar files) synchronized with code changes.

意图层文件（AGENTS.md、CLAUDE.md 或类似文件）承载的是代码中不可见的组织性知识（institutional knowledge）。文档将其归纳为四类：

• 系统边界与所有权（System boundaries and ownership）——哪个模块负责什么、不负责什么；
• 必须始终成立的不变量与契约（Invariants and contracts）；
• 应遵循的模式与应规避的反模式（Patterns to follow / anti-patterns to avoid）；
• 工程师实际踩过的坑与边缘情况（Pitfalls and edge cases）。

这一概念在当前仓库中有真实落点：例如 extensions/cli/AGENTS.md 就是 CLI 子项目的意图文件，而同仓的 breaking-change-detector.md 等检查在扫描破坏性变更时，也明确把“.continue/agents/ 下的 Agent 定义是否引用了旧命令”列入检查范围——说明仓库自身就把这类文件视为需要与代码保持同步的活文档。

三、任务目标：分析 PR 变更，决定是否在 stacked PR 中编辑意图文件

文档的 Your Task 一节给出了 Agent 的单一目标：

Analyze the PR changes and determine if any intent layer files need updates. If yes, make edits in a stacked PR.

两个关键点：

• 输入是 PR 的变更集，而非整个代码库——检查是增量式的，只针对本次 PR 引入的改动做判断；
• 产出方式是 stacked PR（堆叠式 PR）——意图文件的修改不直接塞进原 PR，而是通过一个独立叠加的 PR 提交，便于人工单独审查“文档改动”这一层，与原代码 PR 解耦。

四、五步处理流程（Process）详解

文档将 Agent 的工作拆为五个明确步骤，这是全文的操作性核心，逐一展开：

Step 1: Analyze Changed Files——分析变更文件

• 列出本 PR 中所有被修改的文件；
• 理解变更的语义性质（新特性、重构、bug 修复、API 变更等）。

这一步强调的是“语义”而非“文本”：同样是改 100 行，一个内部重构和一个公共 API 签名变更对意图层的影响完全不同。语义定性直接决定 Step 3 的判断走向。

Step 2: Identify Affected Intent Nodes——定位受影响的意图节点

• 找到覆盖被改动目录的意图文件（AGENTS.md、CLAUDE.md 等）；
• 同时检查直接目录与所有祖先目录（intent is hierarchical，意图是层级化的）。

这里隐含了一个目录树心智模型：仓库中每个目录层级都可能挂一份意图文件，越靠近文件叶子的意图文件越具体，根目录的越全局。Agent 必须沿目录向上回溯，才能找全所有可能被本次变更波及的意图节点。

Step 3: Evaluate Need for Updates——评估是否需要更新

这是整个检查的决策闸门，文档给出了双向判定标准。

需要更新的情形（当变更影响到）：

维度	触发条件
Boundaries（边界）	某模块拥有或不拥有的职责发生了变化
Contracts/APIs（契约/API）	入口点、不变量或接口发生了变化
Patterns（模式）	出现了新的推荐做法，或旧模式被弃用
Anti-patterns（反模式）	发现了新的“陷阱”，或既有陷阱被消除
Dependencies（依赖）	新增了系统级集成，或移除了依赖
Pitfalls（坑）	bug 修复暴露出一个非显而易见的隐患

不需要更新的情形（文档同样明确列出，防止 Agent 过度触发）：

• 不影响使用方式的内部实现变更；
• 没有暴露系统性问题的 bug 修复；
• 无行为变化的测试新增；
• 纯文档变更。

“需要/不需要”成对给出，是该 Prompt 设计的显著特点：它不仅告诉 Agent 什么时候该动手，也明确告诉它什么时候必须克制，这直接对应后文质量准则中的“选择性”原则。

Step 4: Make Updates (Leaf-First)——叶节点优先的更新策略

当判定需要更新时，文档规定了四条编辑纪律：

1. Work leaf-first：从最具体的节点（最深目录的意图文件）开始写，再向上更新祖先节点；
2. 保持 dense and high-signal：更新必须压缩到要点，信息密度优先；
3. 遵循既有结构/格式：不引入新排版，延续该意图文件已有的风格；
4. LCA 原则（Lowest Common Ancestor，最近公共祖先）：把事实放在“能覆盖所有相关代码的最浅节点”上——即该事实应写在能涵盖其全部适用范围的最低层级意图文件中，既不下放（导致只覆盖部分代码）也不上提（污染更浅层的全局文档）。

LCA 原则与 leaf-first 策略是配套的：先逐叶写入最具体的事实，再用 LCA 原则决定哪些事实应该/可以在祖先节点上收敛合并，从而保证同一事实只存在于最恰当的一层。

Step 5: Push your changes——推送变更

完成编辑后，将修改推送出去，形成 stacked PR 供人工审查。结合 cn checks 的机制（见第六节），这一步的产物会呈现为一条待接受/拒绝的 suggestion 与对应的 diff。

五、质量准则与反模式清单

五条质量准则（Quality Criteria）

文档对产出质量给出五个硬性标准：

• Density（密度）：每一个 token 都必须有存在的理由，无废话；
• Accuracy（准确性）：必须反映代码的真实行为；
• Completeness（完整性）：捕获 Agent 在此目录高效工作所需的信息；
• Consistency（一致性）：匹配既有意图文件的风格与格式；
• Non-duplication（不重复）：不重复子节点或代码注释中已有的内容。

五条必须规避的反模式

• ❌ 把本该写在代码注释里的实现细节倾倒进意图文件；
• ❌ 在多个意图文件之间复制内容；
• ❌ 添加低信息量的样板话；
• ❌ 对每一个微小变更都更新意图文件（必须保持选择性）；
• ❌ 提出会立刻与现实脱节的修改（避免写“现在时”的临时性描述，否则文档瞬间腐烂）。

这套准则与反模式本质上是在对抗文档腐化的两大根源：冗余（重复、样板、细节下沉错误）与漂移（写下的事实很快被代码演进推翻）。

六、配套机制：cn checks 如何驱动与验收该检查

意图层同步 Agent 的产出需要通过 Continue CLI 的 checks 机制被查看与处置。查看 extensions/cli/src/commands/checks.ts 可以确认其运行链路：

• 命令形态：cn checks [pr-url] 列出某 PR 的所有检查及 diff；cn checks accept [pr-url] 接受全部待处理 suggestion；cn checks reject [pr-url] 拒绝全部待处理 suggestion（入口逻辑见 checks 主函数）。
• PR 自动检测：若不传 PR URL，CLI 会读取当前 git 分支与 remote，通过 GitHub API 的 pulls?head=owner:branch&state=open 接口自动定位当前分支对应的 PR（resolvePrUrl），支持 HTTPS 与 SSH 两种 remote 格式。
• 状态模型：每个 check 上报 state（pending / success / failure）、suggestionStatus（pending / accepted 等）、commitMessage 与 sessionId（CheckStatus 定义）。列表模式下，凡带 commit 的 check 会拉取其 diff 一并展示（printCheckDiff）；accept / reject 则是向 agents/{sessionId}/accept 或 /reject 端点逐条 POST（acceptChecks、rejectChecks）。
• 退出码约定：全部通过返回 0，任一失败返回 1，仍有 pending 返回 2（退出码逻辑），可直接用于 CI 集成。

把这条链路与文档对应起来：update-agents-md.md 中 Step 5 的 “Push your changes”，在 CLI 侧就体现为一条 suggestionStatus: pending、附带 commit 与 diff 的 check 记录；开发者用 cn checks 审阅 diff 后用 accept/reject 做最终裁决。这解释了为什么文档反复强调“dense and high-signal”“不重复”——因为产出是以 diff 形式逐行被人审查的，低信号内容会直接抬高审查成本。

七、设计要点提炼与可复用实践

从这份检查定义可以提炼出三个可迁移到其他团队仓库的实践要点：

1. 意图层是“给 Agent 读的 README”：把边界、契约、模式、坑四类知识从口口相传固化进 AGENTS.md / CLAUDE.md 等层级化文件，让每个 AI 协作者与人类新人获得同一份上下文。仓库自身即是示范者——extensions/cli/ 下的 AGENTS.md 与 .continue/ 下成体系的 agents、rules、checks 共同构成了 Continue 的 AI 协作基础设施。
2. 判断标准双向给出：不仅列“何时更新”，还列“何时不更新”，用明确的豁免清单抑制 Agent 的过度触发，这与 update-continue-docs.md 中 “Only update docs when changes meaningfully affect developer understanding or usage” 的克制基调一致。
3. 写入位置有算法约束：leaf-first 加 LCA 原则把“这段事实该写在哪一层文档”变成了一个可执行的决策规则，而不是留给执行者自由发挥，从而避免同一知识在多层文档中重复或错位。

八、适用前提与限制

• 该检查面向基于 PR 的工作流：它以“当前 PR 的变更文件”为输入，并假设修改通过 stacked PR 提交，因此适用于以 GitHub PR 为协作载体的仓库；
• 其效果依赖仓库中已存在层级化的意图文件体系（至少根目录或关键子目录有 AGENTS.md / CLAUDE.md）。若代码库尚未维护任何意图文件，应先建立基线，再启用该检查；
• 与 cn checks 的联动依赖 Continue 的 checks 运行环境（会话、suggestion 端点等），从 CLI 源码看其状态查询走 api/checks/status 接口，本地仅 npm i 安装（见 environment.json）不足以让该检查脱离 Continue 的检查服务独立运行；
• 本文所述行为均以当前仓库文件内容为准：检查定义见 update-agents-md.md，CLI 行为见 checks.ts，两者如有后续演进，以仓库实际代码为准。