Continue 意图层同步机制解析.continue/checks/update-agents-md.md中的 AGENTS.md 维护 Agent【免费下载链接】continueopen-source coding agent项目地址: https://gitcode.com/GitHub_Trending/co/continue本文以 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一条环境安装指令。该文件的结构分为两部分YAML Frontmatter用于注册检查项元信息--- name: Update AGENTS.md description: Update AGENTS.md ---Markdown 正文即完整的 Agent 系统提示词定义了角色、任务、处理流程、质量标准与反模式清单。从文件组织方式看.continue/checks/下每个.md文件就是一个可独立运行的“检查”checkfrontmatter 的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 codebases 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)——叶节点优先的更新策略当判定需要更新时文档规定了四条编辑纪律Work leaf-first从最具体的节点最深目录的意图文件开始写再向上更新祖先节点保持 dense and high-signal更新必须压缩到要点信息密度优先遵循既有结构/格式不引入新排版延续该意图文件已有的风格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 的所有检查及 diffcn checks accept [pr-url]接受全部待处理 suggestioncn checks reject [pr-url]拒绝全部待处理 suggestion入口逻辑见 checks 主函数。PR 自动检测若不传 PR URLCLI 会读取当前 git 分支与 remote通过 GitHub API 的pulls?headowner:branchstateopen接口自动定位当前分支对应的 PRresolvePrUrl支持 HTTPS 与 SSH 两种 remote 格式。状态模型每个 check 上报statepending/success/failure、suggestionStatuspending/accepted等、commitMessage与sessionIdCheckStatus 定义。列表模式下凡带 commit 的 check 会拉取其 diff 一并展示printCheckDiffaccept/reject则是向agents/{sessionId}/accept或/reject端点逐条 POSTacceptChecks、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 形式逐行被人审查的低信号内容会直接抬高审查成本。七、设计要点提炼与可复用实践从这份检查定义可以提炼出三个可迁移到其他团队仓库的实践要点意图层是“给 Agent 读的 README”把边界、契约、模式、坑四类知识从口口相传固化进 AGENTS.md / CLAUDE.md 等层级化文件让每个 AI 协作者与人类新人获得同一份上下文。仓库自身即是示范者——extensions/cli/下的 AGENTS.md 与.continue/下成体系的 agents、rules、checks 共同构成了 Continue 的 AI 协作基础设施。判断标准双向给出不仅列“何时更新”还列“何时不更新”用明确的豁免清单抑制 Agent 的过度触发这与 update-continue-docs.md 中 “Only update docs when changes meaningfully affect developer understanding or usage” 的克制基调一致。写入位置有算法约束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.mdCLI 行为见 checks.ts两者如有后续演进以仓库实际代码为准。【免费下载链接】continueopen-source coding agent项目地址: https://gitcode.com/GitHub_Trending/co/continue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考