design-control-loop

设计控制循环

当用户希望按计划通过小幅、低风险、易于审查的更改，让其代码库的某项属性逐步达到目标时，使用此技能——这就是Agent 控制循环。

你的工作是采访用户，与他们共同设计循环，然后为他们构建循环。设计必须针对他们的代码库和他们已经在使用的工具。没有固定的工具集，也没有可照搬的模板：根据你在代码库中发现的情况提出选项，讨论权衡，商定设计，然后着手实现。

思维模型

借鉴控制理论。代码库是一个不断变化的动态系统，持续受到队友、依赖项和生成代码的影响（这些都是扰动）。控制循环会逐步推动系统达到期望状态，而不是试图一步到位：

• 设定值——代码库某项属性的期望最终状态。
• 传感器——测量当前状态，并得出与设定值之间的差距。
• 控制器——根据测量结果决定下一项小幅、低风险的更改。
• 执行器——应用更改并发起 PR 的编码 Agent。
• 结果会反馈到下一次运行。由人类参与循环并进行引导。

在设计之前，先阅读 references/control-loop-taxonomy.md，并向用户讲解这些概念。有关完整的示例，请参阅 references/example-control-loop.md——将其视为示例，而不是蓝图。

如何运行此技能

• 先阅读代码库，再提问（阶段 A）。带着建议开始访谈，不要拿着空白表格。
• 每个组件都要量身定制。 传感器、控制器和执行器的选择完全取决于用户的问题和技术栈。参考资料中的列表只是用于启发讨论的示例，绝不是要强行推行的检查清单。
• 先确保每个组件都能在本地独立运行，再将其接入 CI（阶段 D）。工作流只应负责协调用户已经可以手动运行的组件。
• 在开始构建之前，以书面形式记录商定的设计，让用户可以轻松地提出修改。

输出

在目标代码库中创建或更新以下内容，具体内容根据商定的设计量身定制：

• 作为受版本控制的命令或脚本的传感器和控制器，供用户在本地运行。
• .claude/skills/<skill-name>/SKILL.md——记录 Agent 判断逻辑的执行器技能（路径可根据代码库惯例使用 .agents/skills/...）。
• 定期运行循环并发起 PR 的工作流（默认使用 GitHub Actions；也可使用代码库采用的 CI）。
• 用于在多次运行之间保留长期反馈的记忆/反馈文件。
• 可选的阻尼器（回归关卡），用于在循环逐步改善问题的同时防止情况恶化。

工作流

阶段 A — 了解系统

阅读以下参考资料： references/example-control-loop.md。

在询问设置问题之前，先阅读：

• 现有 CI：.github/workflows/*.yml、.github/actions/** 或代码库使用的非 GitHub CI 配置——运行器、检出、依赖安装、缓存和 PR 惯例。
• 包管理器文件（package.json、bun.lock、pnpm-lock.yaml、yarn.lock、package-lock.json、pyproject.toml、go.mod、Cargo.toml 等）。
• 现有验证脚本：类型检查、lint、测试、质量检查、格式化和特定包的命令。
• 现有的 .claude/skills / .agents/skills 和任何现有 Agent 循环（工作流、agent-memory、胶水脚本所在位置），以便遵循现有惯例，而不是另起炉灶。
• 代码库中已有的静态分析、lint、代码生成和测试工具——这些最有可能成为传感器的原始素材。
• 从较高层面了解代码库中的包、服务及其用途。

完成标准：你能够说出代码库使用的包管理器、安装命令、可能的验证命令、CI 平台以及任何现有循环惯例。你对其中包含的包、服务和应用程序有较高层面的了解。

阶段 B——与用户共同设计循环

阅读以下参考资料： references/control-loop-taxonomy.md、references/example-control-loop.md、references/agent-runner-templates.md。

这是一次访谈。逐一讨论以下组件。先询问用户关于设定点的问题。根据阶段 A 提出选项并说明权衡，而不是强制要求用户做出某种选择。讨论过程中记录各项决策。

1. 设定点。 我们要推动什么属性达到什么目标？例如，不变量（“不再有流程使用旧模式”）、阈值（“这些软件包的测试覆盖率 ≥ X”）或方向（“每次运行都减少出现次数”）。还要明确范围：循环可以修改哪些目录／软件包，又只能读取哪些目录／软件包。

2. 传感器。 循环如何测量与设定点之间的差距？检查代码库和用户现有的工具，并根据其技术栈提出合适的选项——静态分析或 lint 工具、结构化／AST 搜索、测试套件、类型检查器、遥测或错误查询、自定义脚本，甚至基于 Agent 的检查。讨论对用户重要的权衡（稳定性、成本、可重复性，以及测量是否可能在不被察觉的情况下停用），而不是强制要求任何属性。目标是获得控制器可以重复执行操作的测量方式。

3. 控制器。 循环如何根据测量结果选择下一个增量，并控制好工作量，使风险较低且便于审查？与用户共同设计：如何确定目标优先级、每个增量应有多大，以及在这里“一项可审查的工作单元”意味着什么。控制器可以是完全确定性的（选择下一个目标的脚本），也可以完全基于 Agent（根据自然语言标准做出决策），还可以与传感器或执行器融合。控制器是你们会根据循环输出随时间调优的部分——从简单方案开始，并做好修改的准备。

4. 执行器。 编码 Agent 加上仓库本地技能来应用更改。

   • Agent + 凭据。 从 references/agent-runner-templates.md 中选择命令行编码 Agent（Claude Code、Codex、OpenCode、CodeLayer 等）、其密钥及无头命令。
   • 先确定优秀模式。 自动化之前，先明确什么样的更改才算好：询问用户是否应遵循代码库中的现有模式，并检查代码以找到这些模式。在执行器技能中记录这些模式（阶段 C）。
   • 验证。 决定 Agent 提交前必须通过哪些命令（根据阶段 A 提出并确认）。

5. 扰动因素 + 阻尼器（提供选项）。 指出哪些因素会在循环之外改变系统（队友并发提交更改、依赖项升级、生成的代码）。然后提供一个阻尼器选项：在预定循环逐步解决问题期间，通过检查防止测量结果变得更糟——例如，添加 PR 检查，将传感器的输出与基线比较，并提示（或最终阻止）新引入的偏差。此项为可选；有些循环不需要阻尼器。

完成标准：提供一份简短的书面设计，说明设定点、传感器、控制器、执行器（Agent + 技能 + 验证命令）以及扰动因素／阻尼器，并确保每个组件都可由用户在本地运行。

Phase C — 构建执行器技能

阅读以下参考资料： references/skill-template.md、references/example-skill.md、references/response-template.md。

编写一个仓库本地技能，记录执行器针对该任务的判断方式。由于技能位于仓库中，可以使用仓库专属路径、软件包名称和惯例。

• 将有序行为写入 SKILL.md，以步骤形式呈现，并为每步设置可核验的完成标准；将较长的模板和示例移至同级参考文件。
• 编入 Phase B4 中的黄金模式，确保 Agent 遵循既有惯例。
• 每条规则只保留一个信息源；不要在技能、提示词和记忆文件中重复相同指导。
• 加入响应模板（例如 references/response-template.md），定义 Agent 如何格式化最终输出，该输出将作为 PR 正文。要求技能读取并遵循该模板。
• 将 references/skill-template.md 用作骨架，将 references/example-skill.md 用作具体示例。技能规范请参阅 https://agentskills.io/specification。

**重要：**技能前置元数据中的 name 必须与其目录 slug 一致——名为 migrate-foo 的技能应位于 .claude/skills/migrate-foo/SKILL.md（或 .agents/skills/migrate-foo/SKILL.md）。

完成标准：技能对任务的说明足够清晰，使 Agent 无需人工干预即可完成任务，包括如何格式化最终响应。

Phase D — 让各组件可在本地运行

阅读以下参考资料： references/agent-runner-templates.md。

在 CI 尚未建立前，将传感器和控制器作为纳入版本控制的命令或脚本提交（遵循仓库中存放此类脚本的惯例），并手动验证整个流程：

• 单独运行传感器，确认其能生成稳定、可用的测量结果。
• 使用真实的传感器输出运行控制器，确认其能选出合理的下一个增量。
• 在控制器选定的目标上，通过无头 CLI 命令在本地运行执行器，确认其完成更改并通过验证。

只有当每个组件都能独立在本地运行后，才开始接入 CI。这样可以让流程便于调试，并使工作流成为用户已能运行各个组件的轻量级编排器。

完成标准：用户可以在本地独立运行传感器、控制器和执行器。

Phase E — 将流程接入 CI

阅读以下参考资料： references/workflow-template.yml、references/prompt-template.md、references/agent-runner-templates.md。

将各个组件组装成一个定期运行的任务。GitHub Actions 是默认选择，因为它已具备代码、密钥、版本控制和计划任务/调度能力；但应使用仓库实际采用的 CI。

• 按离散步骤：传感器 → 控制器 → 执行器运行流程，然后提交并创建 PR，使用 Agent 的最终消息作为 PR 正文。（当组件已经融合时——例如传感器本身会确定优先级，或单个 Agent 同时选择目标并进行修改——应合并为一个步骤；不要臆造设计中不存在的步骤划分。）
• 可将可复用逻辑放入自定义复合操作中。
• 根据任务风险和审查负担确定运行频率（每日、工作日、每周、每月、仅手动触发或自定义 cron）。
• 将记忆文件（Phase F）插入执行器的上下文中。
• 使用 references/workflow-template.yml 作为基础模板，并使用 references/prompt-template.md 作为嵌入式提示词。参照 references/agent-runner-templates.md 添加 Agent 运行和响应提取步骤（每个 Agent 的输出格式都不同；将最终响应写入 /tmp/pr-body.md）。

完成标准：工作流能够通过 workflow_dispatch 运行，且不依赖不存在的文件。

阶段 F — 让人在环路中参与

阅读以下参考资料： references/memory-template.md、references/agent-iteration.ts。

没有引导，定时循环就会偏离方向。为人提供两个渠道，二者都应改变未来的行为，而不只是当前 PR：

• 记忆／反馈文件。 一个受版本控制的 Markdown 文件（例如 .github/agent-memory/<task-slug>.md），每次运行时，在控制器之后确定性地加载到执行器的上下文中。使用 references/memory-template.md。合适的条目包括：永久性范围排除项、已知的误报区域，以及应影响未来选择的审阅者反馈，而不是一次性指令或单次运行日志。
• 在 PR 上使用 /iterate。 为每个循环的 PR 添加标签，并嵌入隐藏标记，使每个工作流只处理自己创建的 PR 上的评论。当维护者评论 /iterate 时，相应的工作流会加载 PR 上下文（差异、评论）和反馈，然后由 Agent 更新记忆和 PR。在仓库存放 CI 脚本的位置安装 references/agent-iteration.ts（模式：footer 和 prompt）。

向用户说明，这是随时间调整控制器和技能的方式——人不断纠正循环，使其不断改进。

完成标准：持续性反馈能在多次运行之间保留；如果启用了 /iterate，它能更新现有 PR。

阶段 G — 流程控制

阅读以下参考资料： references/workflow-template.yml。

限制进行中的工作，避免循环创建 PR 的速度超过审阅速度。推荐的默认设置：每个循环最多有一个未关闭的 PR。

• 工作流会检查是否存在带有此循环标签的未关闭 PR；达到上限时，定时运行不执行任何操作；手动触发的 workflow_dispatch 运行则跳过此检查。
• 确定 PR 元数据：标签名称、PR 标题前缀、分支前缀。

否则，每日循环可能会不断堆积重复或冲突的 PR，却无人审阅。完成标准：当此循环的未关闭 PR 数量已达到上限时，定时运行不执行任何操作。

阶段 H — 验证、试运行并加快迭代

阅读以下参考资料： references/workflow-template.yml。

验证工作流 YAML（使用 bunx js-yaml file.yml、python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.yml 或 yq），并确认技能、工作流和记忆文件中指定的每个路径都已存在或由此任务创建。

试运行。 工作流至少运行一次后，才能通过 workflow_dispatch 手动触发。临时为当前分支添加 push 触发器，推送代码并观察运行，然后移除该触发器。审阅它创建的任何 PR，以确认循环的行为符合预期。

准备好加快迭代后（循环经过调整并能稳定产出高质量结果后）：提高计划任务的执行频率；扩大控制器的批次（例如每次运行选择 N 个目标）；在每次工作流运行中执行 N 次感知→控制→执行循环；或者多次运行工作流，并为每位队友分配一个 PR。

完成标准：工作流 YAML 可解析，所有引用的文件均已存在，并且循环至少生成了一个经过审阅的 PR。

参考文件

上文的每个阶段都列出了与之相关的参考文件——到达相应阶段时，请阅读这些文件。完整索引：

• references/control-loop-taxonomy.md — 控制循环的组成部分和需要思考的设计问题；请先阅读此文件，并用它来指导用户。
• references/example-control-loop.md — 一个完整示例循环，按组件逐一注释。仅作说明，不是模板。
• references/agent-runner-templates.md — Claude Code、Codex、OpenCode 和 CodeLayer 的本地与 CI 无头命令及密钥，并介绍如何提取响应。
• references/workflow-template.yml — 循环运行工作流骨架，包含独立的传感器／控制器／执行器步骤。
• references/prompt-template.md — 执行器步骤中嵌入的提示词结构。
• references/memory-template.md — 记忆／反馈文件骨架。
• references/skill-template.md — 生成的执行器技能骨架。
• references/response-template.md — Agent 最终响应（PR 正文）的格式示例。
• references/example-skill.md — 格式规范的任务技能示例。
• references/agent-iteration.ts — 为 /iterate 提供支持的辅助工具（PR 页脚标记和迭代提示词构建）。