当你想用定时、小步、可审查的改动把代码库某个属性推向目标时…

通过访谈用户、结合其代码库与现有工具，设计并落地一个由传感器、控制器、执行器组成的可本地运行的智能体控制回路，并接入 CI 定时开 PR。

适用场景

解决思路

1. 先读仓库再提问（Phase A）：阅读现有 CI 配置（如 `.github/workflows/*.yml`、`.github/actions/**` 或非 GitHub 的 CI 配置）了解 runner、checkout、依赖安装、缓存和 PR 约定；阅读包管理器文件（`package.json`、`bun.lock`、`pnpm-lock.yaml`、`yarn.lock`、`package-lock.json`、`pyproject.toml`、`go.mod`、`Cargo.toml` 等）；阅读现有校验脚本（typecheck、lint、test、quality、format 及包级命令）；查看现有 `.claude/skills` / `.agents/skills` 和已有 agent 回路（workflow、`agent-memory`、胶水脚本位置）以沿用约定；盘点仓库已有的静态分析、lint、代码生成、测试工具作为传感器的候选原料；高层了解包、服务与仓库用途。完成标准：能说出包管理器、安装命令、可能的校验命令、CI 平台和已有回路约定。
2. 向用户讲解控制论心智模型：代码库是被持续改动的动态系统（干扰来自队友、依赖、生成代码），控制回路把它逐步推向目标状态而非一次到位；包含设定点（期望终态）、传感器（测量当前状态并给出差距）、控制器（据测量决定下一个小的低风险改动）、执行器（编码智能体应用改动并开 PR），结果反馈到下一次运行，人始终在回路之上掌舵。先读 `references/control-loop-taxonomy.md` 并带用户过一遍这些概念，参考 `references/example-control-loop.md` 作为示例而非蓝图。
3. 与用户访谈式设计回路（Phase B），逐项确定并记录决策：1）设定点——驱动哪个属性、目标是什么（不变量、阈值或方向），并确定范围（哪些目录/包可改、哪些只读）；2）传感器——如何测量与设定点的差距，基于其技术栈提出选项（静态分析/lint 工具、结构化/AST 搜索、测试套件、类型检查器、遥测或错误查询、自定义脚本、甚至基于智能体的检查），讨论对其重要的权衡（稳定性、成本、可重复性、测量是否会被悄悄禁用），目标是控制器能可重复据其行动的测量；3）控制器——如何从测量选择下一个增量并保持低风险可审查，与用户一起设计优先级、单次增量大小、什么算「一个可审查的工作单元」，可从完全确定性（脚本选下一个目标）到完全智能体化（智能体按自然语言标准决定），也可与传感器或执行器融合，控制器是要随时间调优的部分，先简单再迭代；4）执行器——编码智能体加仓库本地技能应用改动，选定 CLI 智能体（Claude Code、Codex、OpenCode、CodeLayer 等）、其密钥和无头命令（见 `references/agent-runner-templates.md`），先确立「黄金模式」（问用户是否应遵循代码库现有模式并检查代码找出它们，写入 Phase C 的执行器技能），确定智能体提交前必须通过的校验命令（从 Phase A 提议并确认）；5）干扰与阻尼器（可选提供）——指出回路之外改变系统的因素（队友并发提交、依赖升级、生成代码），并提议阻尼器：一个防止被测问题在定时回路逐步改善期间恶化的检查，例如比较传感器输出与基线的 PR 检查，暴露（或最终阻止）新引入的偏差。完成标准：一份简短书面设计，写明设定点、传感器、控制器、执行器（智能体+技能+校验）和干扰/阻尼器，且每个组件用户都能本地运行。
4. 构建执行器技能（Phase C）：写一个仓库本地技能捕捉该任务下执行器的判断，可用仓库特定路径、包名和约定；在 `SKILL.md` 中把有序行为写成带可检查完成标准的步骤，长模板和示例移到同级参考文件；编码 Phase B4 的黄金模式让智能体遵循既有约定；每条规则保持单一事实来源，不要在技能、提示词和记忆文件中重复同一指导；包含响应模板（如 `references/response-template.md`）定义智能体最终输出格式（即 PR 正文），并指示技能读取并遵循它；用 `references/skill-template.md` 作骨架、`references/example-skill.md` 作具体示例，技能规范见 https://agentskills.io/specification。注意：技能 frontmatter 中的 `name` 必须与目录 slug 一致，名为 `migrate-foo` 的技能位于 `.claude/skills/migrate-foo/SKILL.md`（或 `.agents/skills/migrate-foo/SKILL.md`）。完成标准：技能清楚说明任务，使智能体能无人值守完成，包括如何格式化最终响应。
5. 让每个组件可本地运行（Phase D）：在有任何 CI 之前，把传感器和控制器落地为版本控制的命令或脚本（遵循仓库对脚本位置的约定），并手工验证整个回路——单独运行传感器确认产生稳定可用的测量；在真实传感器输出上运行控制器确认选出合理的下一个增量；通过其无头 CLI 命令在控制器选定的目标上本地运行执行器，确认它做出改动并通过校验。只有每部分都能独立本地运行后才进入 CI，这保持回路可调试，并使 workflow 只是用户已能手动运行之物的薄编排层。完成标准：用户能本地独立运行传感器、控制器和执行器。
6. 把回路接入 CI（Phase E）：把组件组装成定时任务，默认用 GitHub Actions（因为它已有代码、密钥、版本控制和调度/手动触发），但用仓库实际使用的 CI；以离散步骤运行回路：传感器 → 控制器 → 执行器，然后用智能体的最终消息作为正文提交并开 PR（当组件融合时——如传感器已做优先级排序，或一个智能体既选择又改动——折叠为单步，不要发明设计中不存在的分离）；可复用逻辑可放在自定义 composite action 中；根据任务风险和审查负担决定节奏（每日、工作日、每周、每月、仅手动或自定义 cron）；把记忆文件（Phase F）插值进执行器上下文；以 `references/workflow-template.yml` 为基础，用 `references/prompt-template.md` 作内嵌提示词，从 `references/agent-runner-templates.md` 取智能体运行和响应提取步骤（各智能体输出不同，要把最终响应写入 `/tmp/pr-body.md`）。完成标准：workflow 能从 `workflow_dispatch` 运行且不依赖不存在的文件。
7. 让人留在回路之上（Phase F）：定时回路若无掌舵会漂移，给人类两个渠道，且都应改变未来行为而非仅当前 PR——1）记忆/反馈文件：版本控制的 markdown 文件（如 `.github/agent-memory/<task-slug>.md`），每次运行在控制器之后确定性地加载进执行器上下文，用 `references/memory-template.md`，好的条目包括永久范围排除、已知误报区域、应改变未来选择的审查者反馈，而非一次性指令或单次运行日志；2）在 PR 上 `/iterate`：给每个回路的 PR 打标签并嵌入隐藏标记，使每个 workflow 只处理自己创建的 PR 上的评论，当维护者评论 `/iterate` 时，匹配的 workflow 加载 PR 上下文（diff、评论）和反馈，智能体更新其记忆和 PR，把 `references/agent-iteration.ts`（模式：`footer` 和 `prompt`）安装到仓库存放 CI 脚本的位置。向用户说明这是随时间调优控制器和技能的方式——回路因人类持续纠正而变好。完成标准：常驻反馈在运行间保留，且 `/iterate`（若启用）更新已有 PR。
8. 流控（Phase G）：限制在制品，使回路产生 PR 的速度不超过可审查速度，推荐默认每个回路一个未关闭 PR——workflow 检查带该回路标签的未关闭 PR，达到上限时定时运行直接 no-op，手动 `workflow_dispatch` 运行绕过该检查；决定 PR 元数据：标签名、PR 标题前缀、分支前缀。否则每日回路会在无人审查时堆积重复或冲突的 PR。完成标准：当该回路的未关闭 PR 已达上限时，定时运行 no-op。
9. 校验、试运行并加速迭代（Phase H）：校验 workflow YAML（`bunx js-yaml file.yml`、`python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.yml` 或 `yq`），并确认技能、workflow 和记忆文件引用的每个路径都存在或由本任务创建；试运行——workflow 在首次运行前无法 `workflow_dispatch`，临时为当前分支加 `push` 触发器，推送并观察运行，然后移除触发器，审查它开的任何 PR 以确认回路行为；准备加速迭代（当回路调优并产出稳定高质量输出后）：提高调度频率、扩大控制器批量（如每次选 N 个目标）、每次 workflow 运行执行 N 次感知→控制→执行循环，或多次运行 workflow 并给每位队友分配一个 PR。完成标准：workflow YAML 可解析、所有引用文件存在、回路已产出至少一个被审查的 PR。
10. 按阶段阅读参考文件：`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`（含离散传感器/控制器/执行器步骤的定时回路 workflow 骨架）、`references/prompt-template.md`（执行器步骤的内嵌提示词结构）、`references/memory-template.md`（记忆/反馈文件骨架）、`references/skill-template.md`（生成的执行器技能骨架）、`references/response-template.md`（智能体最终响应即 PR 正文的格式示例）、`references/example-skill.md`（一个格式良好的任务技能具体示例）、`references/agent-iteration.ts`（`/iterate` 支持辅助：PR footer 标记与迭代提示词构建）。

适用边界 · 注意事项

• 用户不想用定时、小步、可审查的改动来推进代码库属性，或不需要智能体控制回路时。
• 无法在目标仓库中落地版本控制的脚本、技能和 CI（如无 CI 平台、无密钥管理、无版本控制）时。
• 用户期望一次性完成大改动而非逐步推进，或不愿在回路之上持续人工掌舵与调优时。