design-control-loop
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDesign Control Loop
设计控制回路
Use this skill when a user wants to drive some property of their codebase toward a target with small, low-risk, reviewable changes on a schedule — an agentic control loop.
Your job is to interview the user, design the loop with them, and then build it for them. The design must be tailored to their codebase and the tooling they already use. There is no fixed toolset and no template to reproduce: propose options grounded in what you find in the repo, discuss trade-offs, agree on a design, then implement it.
当用户希望通过定时执行的小型、低风险、可评审的变更,将代码库的某项特性推向目标状态时,可使用此技能——即agentic control loop(智能代理控制回路)。
你的任务是与用户沟通访谈,共同设计回路并完成构建。设计必须完全适配用户的代码库及已使用的工具链。不存在固定工具集或可复用模板:需基于代码库实际情况提出方案、讨论权衡、达成共识后再实施。
The mental model
核心思维模型
Borrow from control theory. The codebase is a dynamic system being changed continuously (by teammates, dependencies, and generated code — the disturbances). A control loop drives it toward a desired state instead of all at once:
- Set point — the desired end state for some property of the codebase.
- Sensor — measures the current state, producing the gap to the set point.
- Controller — decides the next small, low-risk change from that measurement.
- Actuator — a coding agent that applies the change and opens a PR.
- The result feeds back into the next run. A human stays on the loop to steer it.
Read and walk the user through these concepts before designing anything. For one fully worked example, see — treat it as an illustration, not a blueprint.
references/control-loop-taxonomy.mdreferences/example-control-loop.md借鉴控制理论:代码库是一个持续变化的动态系统(受团队成员、依赖项、生成代码等干扰因素影响)。控制回路可逐步将其推向期望状态,而非一次性完成:
- Set point(设定值)——代码库某项特性的期望最终状态。
- Sensor(传感器)——测量当前状态,计算与设定值的差距。
- Controller(控制器)——根据测量结果决定下一步的小型低风险变更。
- Actuator(执行器)——编码代理,负责应用变更并创建PR。
- 执行结果会反馈到下一次运行,由人工全程监控并引导回路运行。
在开始设计前,请阅读并向用户讲解这些概念。可参考中的完整示例——仅作演示,而非蓝图模板。
references/control-loop-taxonomy.mdreferences/example-control-loop.mdHow to run this skill
技能执行流程
- Read the repo before you ask (Phase A). Come to the interview with proposals, not a blank form.
- Tailor every component. The right sensor, controller, and actuator depend entirely on the user's problem and stack. The lists in the references are examples to spark discussion, never a checklist to push.
- Make each component runnable locally and standalone before wiring it into CI (Phase D). The workflow should only orchestrate pieces the user can already run by hand.
- Capture the agreed design in writing before building, so the user can correct it cheaply.
- 先读代码库再提问(阶段A):访谈前需准备好方案,而非空白提问。
- 定制每个组件:合适的Sensor、Controller、Actuator完全取决于用户的问题和技术栈。参考文档中的列表仅作启发,绝非强制 checklist。
- 先实现本地可独立运行的组件,再接入CI(阶段D):工作流仅需编排用户已能手动运行的模块。
- 构建前记录共识设计:让用户可低成本修正设计方案。
Outputs
输出成果
Create or update these in the target repo, tailored to the agreed design:
- The sensor and controller as version-controlled commands/scripts the user can run locally.
- — the actuator skill capturing the agent's judgement (path may be
.claude/skills/<skill-name>/SKILL.mdper repo convention)..agents/skills/... - The recurring workflow that runs the loop and opens a PR (GitHub Actions by default; whatever CI the repo uses).
- A memory/feedback file that carries standing feedback between runs.
- Optionally, a dampener (regression gate) that keeps the problem from getting worse while the loop improves it.
根据共识设计,在目标代码库中创建或更新以下内容:
- 作为版本化命令/脚本的Sensor和Controller,支持用户本地运行。
- ——记录执行器代理判断逻辑的Actuator技能文件(路径可根据代码库惯例改为
.claude/skills/<skill-name>/SKILL.md)。.agents/skills/... - 定时运行回路并创建PR的工作流(默认使用GitHub Actions;也可适配代码库现有CI工具)。
- 记忆/反馈文件:在多次运行间传递持续反馈。
- 可选的阻尼器(回归闸门):在回路优化问题的同时,防止问题恶化。
Workflow
工作流阶段
Phase A — Understand the system
阶段A — 理解系统
Read the following references: .
references/example-control-loop.mdRead before asking setup questions:
- Existing CI: ,
.github/workflows/*.yml, or the repo's non-GitHub CI config — runner, checkout, dependency install, cache, and PR conventions..github/actions/** - Package manager files (,
package.json,bun.lock,pnpm-lock.yaml,yarn.lock,package-lock.json,pyproject.toml,go.mod, …).Cargo.toml - Existing validation scripts: typecheck, lint, test, quality, format, and package-scoped commands.
- Existing /
.claude/skillsand any existing agent loops (workflows,.agents/skills, where glue scripts live) to mirror conventions instead of inventing new ones.agent-memory - The static-analysis, linting, codegen, and test tooling already in the repo — these are the most likely raw material for a sensor.
- Discover packages, services, and repo purpose at a high level.
Completion criterion: you can name the repo's package manager, install command, likely validation commands, CI platform, and any existing loop conventions. You understand the packages/services/applications it contains at a high level.
参考文档:。
references/example-control-loop.md提问前需阅读以下内容:
- 现有CI配置:、
.github/workflows/*.yml或非GitHub的CI配置——包括运行器、代码拉取、依赖安装、缓存及PR惯例。.github/actions/** - 包管理器文件(、
package.json、bun.lock、pnpm-lock.yaml、yarn.lock、package-lock.json、pyproject.toml、go.mod等)。Cargo.toml - 现有验证脚本:类型检查、 lint、测试、质量检测、格式化及包级命令。
- 现有/
.claude/skills及任何已存在的代理回路(工作流、.agents/skills、胶水脚本位置),遵循现有惯例而非重新发明。agent-memory - 代码库中已有的静态分析、lint、代码生成及测试工具——这些是Sensor最可能的原材料。
- 从宏观层面了解代码库包含的包、服务及用途。
完成标准:能说出代码库的包管理器、安装命令、常用验证命令、CI平台及任何现有回路惯例;从宏观层面理解其包含的包/服务/应用。
Phase B — Design the loop with the user
阶段B — 与用户共同设计回路
Read the following references: , , .
references/control-loop-taxonomy.mdreferences/example-control-loop.mdreferences/agent-runner-templates.mdThis is an interview. Work through each component below. Start by asking the user questions about the set point. Proposing options grounded in Phase A and surfacing trade-offs rather than mandating any choice. Record the decisions as you go.
-
Set point. What property are we driving, and to what target? Examples: an invariant ("no procedures use the old pattern"), a threshold ("test coverage ≥ X in these packages"), or a direction ("reduce occurrences each run"). Also pin the scope: which directories/packages the loop may change, and which it may only read.
-
Sensor. How will the loop measure the gap to the set point? Inspect the codebase and the user's existing tooling and propose the options that fit their stack — a static-analysis or lint tool, a structural/AST search, a test suite, a type checker, a telemetry or error query, a custom script, or even an agent-based check. Discuss the trade-offs that matter to them (stability, cost, repeatability, and whether the measurement can be silently disabled) instead of mandating any property. Aim for a measurement the controller can act on repeatably.
-
Controller. How will the loop choose the next increment from the measurement, sized to stay low-risk and reviewable? Design this with the user: how to prioritize targets, how big one increment is, and what "one reviewable unit of work" means here. A controller can be anything from fully deterministic (a script that selects the next target) to fully agentic (an agent that decides from natural-language criteria), and it may be fused with the sensor or the actuator. The controller is the part you will tune over time from loop output — start simple and expect to revise it.
-
Actuator. A coding agent plus a repo-local skill applies the change.
- Agent + credentials. Pick the CLI coding agent (Claude Code, Codex, OpenCode, CodeLayer, …), its secret, and its headless command from .
references/agent-runner-templates.md - Golden patterns first. Before automating, establish what a good change looks like: ask the user whether existing patterns in the codebase should be followed, and inspect the code to find them. Capture these in the actuator skill (Phase C).
- Validation. Decide which commands must pass before the agent commits (propose these from Phase A and confirm).
- Agent + credentials. Pick the CLI coding agent (Claude Code, Codex, OpenCode, CodeLayer, …), its secret, and its headless command from
-
Disturbances + dampener (offer). Name what changes the system outside the loop (teammates shipping concurrently, dependency bumps, generated code). Then offer a dampener: a check that keeps the measured problem from getting worse while the scheduled loop chips away at it — for example a PR check that compares the sensor's output against a baseline and surfaces (or eventually blocks) newly introduced deviations. This is optional; some loops do not need one.
Completion criterion: a short written design naming the set point, sensor, controller, actuator (agent + skill + validation), and disturbances/dampener — with each component something the user can run locally.
参考文档:、、。
references/control-loop-taxonomy.mdreferences/example-control-loop.mdreferences/agent-runner-templates.md此阶段为访谈环节,需逐一讨论以下组件。先询问用户关于设定值的问题,基于阶段A的发现提出方案并阐明权衡,而非强制选择。随时记录决策结果。
-
Set point(设定值):我们要优化哪项特性,目标是什么?例如:不变式(“无程序使用旧模式”)、阈值(“指定包的测试覆盖率≥X”)或方向(“每次运行减少问题出现次数”)。同时明确范围:回路可修改的目录/包,以及仅可读取的目录/包。
-
Sensor(传感器):回路如何测量与设定值的差距?检查代码库和用户现有工具,提出适配其技术栈的方案——静态分析或lint工具、结构/AST搜索、测试套件、类型检查器、遥测或错误查询、自定义脚本,甚至基于代理的检查。讨论用户关心的权衡点(稳定性、成本、可重复性、是否可静默禁用),而非强制要求某特性。目标是提供Controller可重复执行的测量结果。
-
Controller(控制器):回路如何根据测量结果选择下一个低风险、可评审的增量变更?与用户共同设计:如何优先处理目标、增量大小、“一个可评审工作单元”的定义。Controller可以是完全确定性的(选择下一个目标的脚本),也可以是完全智能代理式的(基于自然语言标准决策的代理),还可与Sensor或Actuator融合。Controller是后续需根据回路输出持续调优的部分——从简单开始,预期会不断修订。
-
Actuator(执行器):编码代理+代码库本地技能,负责应用变更。
- 代理+凭据:从中选择CLI编码代理(Claude Code、Codex、OpenCode、CodeLayer等)、密钥及无头命令。
references/agent-runner-templates.md - 先确定黄金模式:自动化前先明确良好变更的标准:询问用户是否应遵循代码库中的现有模式,并检查代码找到这些模式。将其记录到执行器技能文件中(阶段C)。
- 验证:确定代理提交前必须通过的命令(基于阶段A提出方案并确认)。
- 代理+凭据:从
-
干扰因素+阻尼器(可选):列出回路外的系统变更因素(团队成员并发提交、依赖版本更新、生成代码)。然后提供阻尼器方案:一种检查机制,在定时回路逐步解决问题的同时,防止测量到的问题恶化——例如PR检查,将Sensor输出与基线对比,发现(或最终阻止)新引入的偏差。此为可选组件,部分回路无需阻尼器。
完成标准:形成简短书面设计文档,明确设定值、Sensor、Controller、Actuator(代理+技能+验证)及干扰因素/阻尼器——每个组件均支持用户本地运行。
Phase C — Build the actuator skill
阶段C — 构建执行器技能
Read the following references: , , .
references/skill-template.mdreferences/example-skill.mdreferences/response-template.mdWrite a repo-local skill that captures the actuator's judgement for this task. It can use repo-specific paths, package names, and conventions since it lives in the repository.
- Put ordered behavior in as steps with checkable completion criteria; move long templates and examples into sibling reference files.
SKILL.md - Encode the golden patterns from Phase B4 so the agent follows established conventions.
- Keep one source of truth for each rule; do not repeat the same guidance in the skill, the prompt, and the memory file.
- Include a response template (e.g. ) defining how the agent formats its final output, which becomes the PR body. Instruct the skill to read and follow it.
references/response-template.md - Use as the skeleton and
references/skill-template.mdas a concrete example. See https://agentskills.io/specification for the skill spec.references/example-skill.md
IMPORTANT: the in the skill's frontmatter must match its directory slug — a skill named lives at (or ).
namemigrate-foo.claude/skills/migrate-foo/SKILL.md.agents/skills/migrate-foo/SKILL.mdCompletion criterion: the skill explains the job clearly enough that the agent can do it unattended, including how to format its final response.
参考文档:、、。
references/skill-template.mdreferences/example-skill.mdreferences/response-template.md编写代码库本地技能文件,记录此任务的执行器判断逻辑。可使用代码库特定路径、包名及惯例,因为文件将存放在代码库内。
- 在中按顺序编写带可检查完成标准的步骤;将长模板和示例移至同级参考文件。
SKILL.md - 编码阶段B4中确定的黄金模式,确保代理遵循既定惯例。
- 每个规则仅保留一个权威来源;不要在技能文件、提示词和记忆文件中重复相同指导。
- 包含响应模板(如),定义代理最终输出的格式(即PR正文)。指导技能文件读取并遵循该模板。
references/response-template.md - 以为框架,
references/skill-template.md为具体示例。技能规范详见https://agentskills.io/specification。references/example-skill.md
重要提示:技能文件前端元数据中的必须与其目录slug匹配——例如名为的技能需存放在(或)。
namemigrate-foo.claude/skills/migrate-foo/SKILL.md.agents/skills/migrate-foo/SKILL.md完成标准:技能文件足够清晰,可支持代理无人值守执行任务,包括如何格式化最终响应。
Phase D — Make each component runnable locally
阶段D — 实现各组件本地可运行
Read the following references: .
references/agent-runner-templates.mdBefore any CI exists, land the sensor and controller as version-controlled commands or scripts (follow the repo's convention for where such scripts live), and verify the whole loop works by hand:
- Run the sensor standalone and confirm it produces a stable, usable measurement.
- Run the controller on real sensor output and confirm it selects a sensible next increment.
- Run the actuator locally via its headless CLI command on a controller-selected target, and confirm it makes the change and passes validation.
Only proceed to CI once each piece runs locally on its own. This keeps the loop debuggable and makes the workflow a thin orchestrator of things the user can already run.
Completion criterion: the user can run sensor, controller, and actuator locally and independently.
参考文档:。
references/agent-runner-templates.md在接入CI前,先将Sensor和Controller实现为版本化命令或脚本(遵循代码库存放此类脚本的惯例),并手动验证整个回路可正常运行:
- 独立运行Sensor,确认其输出稳定、可用的测量结果。
- 使用真实Sensor输出运行Controller,确认其选择合理的下一个增量变更。
- 通过无头CLI命令在本地运行Actuator处理Controller选定的目标,确认其完成变更并通过验证。
仅当每个组件均可独立本地运行后,再接入CI。这可确保回路可调试,且工作流仅编排用户已能手动运行的模块。
完成标准:用户可本地独立运行Sensor、Controller和Actuator。
Phase E — Wire the loop into CI
阶段E — 将回路接入CI
Read the following references: , , .
references/workflow-template.ymlreferences/prompt-template.mdreferences/agent-runner-templates.mdAssemble the components into a recurring job. GitHub Actions is the default because it already has the code, the secrets, version control, and scheduling/dispatch — but use whatever CI the repo uses.
- Run the loop as discrete steps: sensor → controller → actuator, then commit and open a PR using the agent's final message as the body. (When components are fused — e.g. the sensor already prioritizes, or one agent both selects and changes — collapse them into a single step; do not invent separation the design does not have.)
- Reusable logic can live in a custom composite action.
- Decide the cadence (daily, weekdays, weekly, monthly, manual-only, or custom cron) based on task risk and review burden.
- Interpolate the memory file (Phase F) into the actuator's context.
- Use as the base and
references/workflow-template.ymlfor the embedded prompt. Pull the agent run + response-extraction steps fromreferences/prompt-template.md(each agent outputs differently; get the final response intoreferences/agent-runner-templates.md)./tmp/pr-body.md
Completion criterion: the workflow can run from without relying on files that do not exist.
workflow_dispatch参考文档:、、。
references/workflow-template.ymlreferences/prompt-template.mdreferences/agent-runner-templates.md将组件组装为定时任务。默认使用GitHub Actions,因其已集成代码、密钥、版本控制及调度/触发功能——但也可适配代码库现有CI工具。
- 按离散步骤运行回路:Sensor → Controller → Actuator,然后提交并创建PR,使用代理的最终消息作为PR正文。(若组件已融合——例如Sensor已包含优先级排序,或单个代理同时负责选择和变更——则合并为单个步骤;不要强行分离设计中未明确的部分。)
- 可复用逻辑可存放在自定义复合动作中。
- 根据任务风险和评审负担确定调度频率(每日、工作日、每周、每月、仅手动触发或自定义 cron 表达式)。
- 将记忆文件(阶段F)插入执行器的上下文。
- 以为基础,
references/workflow-template.yml为嵌入式提示词模板。从references/prompt-template.md中获取代理运行+响应提取步骤(不同代理输出格式不同;需将最终响应写入references/agent-runner-templates.md)。/tmp/pr-body.md
完成标准:工作流可通过触发,无需依赖不存在的文件。
workflow_dispatchPhase F — Put a human on the loop
阶段F — 人工监控回路
Read the following references: , .
references/memory-template.mdreferences/agent-iteration.tsA scheduled loop drifts without steering. Give the human two channels, both of which should change future behavior, not just the current PR:
- Memory/feedback file. A version-controlled markdown file (e.g. ) loaded deterministically into the actuator's context after the controller on every run. Use
.github/agent-memory/<task-slug>.md. Good entries: permanent scope exclusions, known false-positive areas, and reviewer feedback that should change future selections — not one-off instructions or single-run logs.references/memory-template.md - on the PR. Label each loop's PRs and embed a hidden marker so each workflow only handles comments on PRs it created. When a maintainer comments
/iterate, the matching workflow loads the PR context (diff, comments) and the feedback, and the agent updates its memory and the PR. Install/iterate(modes:references/agent-iteration.tsandfooter) where the repo keeps CI scripts.prompt
Frame this for the user as how you tune the controller and skill over time — the loop gets better because a human keeps correcting it.
Completion criterion: standing feedback survives between runs, and (if enabled) updates the existing PR.
/iterate参考文档:、。
references/memory-template.mdreferences/agent-iteration.ts定时回路若无人工引导会逐渐偏离。为人工提供两个可改变未来行为(而非仅当前PR)的渠道:
- 记忆/反馈文件:版本化Markdown文件(如),每次运行时在Controller之后确定性地加载到执行器上下文中。使用
.github/agent-memory/<task-slug>.md模板。合适的内容:永久范围排除、已知误报区域、应改变未来选择的评审反馈——而非一次性指令或单次运行日志。references/memory-template.md - PR上的指令:为每个回路的PR添加标签,并嵌入隐藏标记,确保每个工作流仅处理自己创建的PR的评论。当维护者评论
/iterate时,匹配的工作流会加载PR上下文(差异、评论)和反馈,代理会更新记忆文件和PR。将/iterate(模式:references/agent-iteration.ts和footer)安装到代码库存放CI脚本的位置。prompt
向用户说明这是持续调优Controller和技能的方式——回路会因人工持续修正而变得更完善。
完成标准:持续反馈可在多次运行间保留,且(若启用)可更新现有PR。
/iteratePhase G — Flow control
阶段G — 流量控制
Read the following references: .
references/workflow-template.ymlBound work-in-progress so the loop never produces PRs faster than they can be reviewed. Recommended default: one open PR per loop.
- The workflow checks for open PRs with this loop's label and no-ops on scheduled runs when the bound is met; manual runs bypass the check.
workflow_dispatch - Decide PR metadata: label name, PR title prefix, branch prefix.
Without this, a daily loop can stack up duplicate or conflicting PRs while no one is reviewing. Completion criterion: scheduled runs no-op when the open-PR bound for this loop is already met.
参考文档:。
references/workflow-template.yml限制在处理中的工作,确保回路创建PR的速度不超过评审速度。推荐默认值:每个回路最多一个开放PR。
- 工作流会检查带有此回路标签的开放PR,当达到限制时,定时运行会直接跳过;手动运行可绕过此检查。
workflow_dispatch - 确定PR元数据:标签名称、PR标题前缀、分支前缀。
若无此控制,每日运行的回路可能在无人评审时堆积重复或冲突的PR。完成标准:当回路的开放PR已达限制时,定时运行会直接跳过。
Phase H — Validate, dry-run, and iterate faster
阶段H — 验证、试运行、加速迭代
Read the following references: .
references/workflow-template.ymlValidate the workflow YAML (, , or ) and confirm every path named by the skill, workflow, and memory file exists or is created by this task.
bunx js-yaml file.ymlpython -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.ymlyqDry-run. A workflow cannot be -ed until it has run once. Temporarily add a trigger for the current branch, push, watch it run, then remove the trigger. Review any PR it opens to confirm the loop's behavior.
workflow_dispatchpushReady to iterate faster (once the loop is tuned and producing consistent, high-quality output): increase the schedule frequency; widen the controller's batch (e.g. select N targets per run); run the sense→control→actuate cycle N times per workflow run; or run the workflow multiple times and assign one PR to each teammate.
Completion criterion: the workflow YAML parses, all referenced files exist, and the loop has produced at least one reviewed PR.
参考文档:。
references/workflow-template.yml验证工作流YAML文件(使用、或),确认技能文件、工作流和记忆文件中引用的所有路径均已存在或会被此任务创建。
bunx js-yaml file.ymlpython -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.ymlyq试运行:工作流需先运行一次才能通过触发。临时为当前分支添加触发器,推送代码后观察运行情况,然后移除触发器。评审其创建的PR,确认回路行为符合预期。
workflow_dispatchpush准备加速迭代(当回路已调优并能持续生成一致的高质量输出时):提高调度频率;扩大Controller的批量处理能力(例如每次运行选择N个目标);每次工作流运行中执行多次sense→control→actuate循环;或多次运行工作流并为每个团队成员分配一个PR。
完成标准:工作流YAML可解析,所有引用文件均存在,且回路已生成至少一个经过评审的PR。
Reference Files
参考文件
Each phase above names the references relevant to it — read each one when you reach that phase. Full index:
- — the control-loop components and the design questions to ask; read this first and use it to teach the user.
references/control-loop-taxonomy.md - — one fully worked loop, annotated component-by-component. An illustration, not a template.
references/example-control-loop.md - — local + CI headless commands and secrets for Claude Code, Codex, OpenCode, and CodeLayer, with response extraction.
references/agent-runner-templates.md - — recurring loop workflow skeleton with discrete sensor/controller/actuator steps.
references/workflow-template.yml - — embedded prompt structure for the actuator step.
references/prompt-template.md - — memory/feedback file skeleton.
references/memory-template.md - — skeleton for the generated actuator skill.
references/skill-template.md - — examples for how the agent should format its final response (the PR body).
references/response-template.md - — a concrete example of a well-formed task skill.
references/example-skill.md - — helper for
references/agent-iteration.tssupport (PR footer marker + iteration prompt building)./iterate
上述每个阶段均标注了相关参考文档——到达对应阶段时请阅读。完整索引:
- ——控制回路组件及设计问题;请先阅读此文档并向用户讲解。
references/control-loop-taxonomy.md - ——完整的回路示例,逐组件注释。仅作演示,而非模板。
references/example-control-loop.md - ——Claude Code、Codex、OpenCode和CodeLayer的本地+CI无头命令及密钥配置,包含响应提取逻辑。
references/agent-runner-templates.md - ——包含离散Sensor/Controller/Actuator步骤的定时回路工作流框架。
references/workflow-template.yml - ——执行器步骤的嵌入式提示词结构。
references/prompt-template.md - ——记忆/反馈文件框架。
references/memory-template.md - ——生成执行器技能文件的框架。
references/skill-template.md - ——代理最终响应(PR正文)的格式示例。
references/response-template.md - ——结构良好的任务技能文件示例。
references/example-skill.md - ——支持
references/agent-iteration.ts指令的辅助工具(PR页脚标记+迭代提示词构建)。/iterate