build-iterated-agentic-loop

构建迭代式 Agent 循环

当用户想要将可重复的 Agent 任务转化为仓库本地技能，并配套一个 GitHub Actions 工作流，以便按计划、手动或两者兼用的方式运行编码 Agent 时，请使用此技能。

目标结构是一个迭代式 Agent 循环：专注的技能定义 Agent 的判断方式，工作流使用特定于仓库的提示词调用编码 Agent，Agent 记忆文件在各次运行之间传递长期反馈，并且每个工作流都会为其 PR 添加标签，确保每个循环最多只有一个未关闭的 PR。narrow-react-prop-types 技能是具体的参考模式。

输出

在目标仓库中创建或更新以下文件：

• .claude/skills/<skill-name>/SKILL.md，用于定义仓库本地的 Agent 行为。
• .github/workflows/agent-<task-name>.yml，用于定期运行编码 Agent 自动化。
• .github/agent-memory/<task-name>.md，用于记录稳定的反馈和范围限制。
• 可选：在 .claude/skills/<skill-name>/references/ 下添加参考文件，供技能使用模板、示例或较长的辅助材料。

工作流

1. 探索目标仓库

先阅读以下内容，再询问设置问题：

• 现有的 .github/workflows/*.yml 和 .github/actions/**，以了解运行器、检出、依赖安装、缓存和 PR 模式。
• 包管理器文件，例如 package.json、bun.lock、pnpm-lock.yaml、yarn.lock、package-lock.json、pyproject.toml、go.mod 或 Cargo.toml，以及其他与包管理相关的文件。
• 现有的验证脚本，尤其是类型检查、lint、测试、质量检查、格式化和按包运行的命令。
• 现有的 .claude/skills 和 .agents/skills，以避免重复已有约定。

完成标准：能够说出仓库使用的包管理器、安装命令、可能的验证命令以及现有的工作流约定。

2. 询问配置问题

引导用户逐项做出以下决定。根据仓库中的证据推荐默认值，而不是让用户从空白表单开始填写。

1. 编码 Agent：Claude Code、Codex、OpenCode 或 CodeLayer。说明推荐选项所需的密钥和无头命令。使用 references/agent-runner-templates.md。CodeLayer 是 Humanlayer 的超轻量级 Agent harness。
2. 频率：每天、每周、工作日、每月、仅手动运行或自定义 cron。根据任务风险和审核负担推荐频率——最有可能是工作日、每天或每周。
3. 任务：Agent 循环应完成什么任务？

• 是否有现成的技能可用于完成这项任务？（你可以先进行调查，再询问用户。）
• 询问用户是否需要参考近期 PR、git 历史记录或代码库中的其他特定部分。

4. 范围：循环允许修改哪些目录／程序包，只允许检查哪些目录／程序包
5. 验证：Agent 提交前必须通过哪些命令？（你应根据前期调查向用户提出建议，并请他们确认。）
6. PR 数量限制：询问定时运行是否应在该 Agent 已有未合并的 PR 时不执行；如果是，询问允许存在多少个未合并的 PR，超过后应阻止新运行。

• **推荐：是，每个 Agent 循环最多允许 1 个未合并的 PR。**这样可以避免 Agent 不断堆积工作，导致工作量增长速度超过人工审核速度。如果不设限制，每日运行的 Agent 一周可能会生成 5 个以上尚未审核的 PR，造成审核疲劳和合并冲突。
• 工作流会使用标签（例如 agent-<task-slug>）来识别各个 Agent 循环生成的 PR。定时运行会检查 gh pr list --label <label> --state open，如果数量达到或超过限制，就会跳过运行。
• 手动 workflow_dispatch 运行会跳过限制检查，以便在需要时强制运行。

7. PR 元数据：标签名称、PR 标题前缀和分支前缀。

• 建议使用 [MM/DD][Agent: <Agent Name>]: <Concise Description> 作为模板，例如 [6/23][Agent: Effect Migrator]: Migrate XYZ module

8. 响应格式：CI Agent 应如何格式化最终响应（该响应将成为 PR 正文）？

• 向用户展示 references/response-template.md，其中包含修复／迁移、生成和重构的示例。
• 询问审核者需要哪些信息：汇总统计、风险级别、验证步骤、文件列表等。
• 创建自定义响应模板，供生成的技能在其 references/ 目录中引用。

9. 迭代行为：/iterate 评论是否应更新现有 PR。

• 如果启用，将 references/agent-iteration.ts 安装到仓库中。询问用户偏好的位置：.github/scripts/、ci-scripts/ 或 scripts/。
• 此脚本有两种模式：footer（添加 PR 正文标记）和 prompt（根据 PR 上下文构建迭代提示词）。
• 如果禁用，则移除 issue_comment 触发器和仅用于迭代的步骤。

完成标准：工作流、提示词和记忆模板中的每个占位符都已选定值或明确的默认值。

3. 定义 Agent 任务

提炼出 Agent 应执行的最小可重复任务。与用户一起梳理以下三个问题：

我们要查找什么？ Agent 如何识别本次运行的目标？

• 能报告问题的 CLI 工具（例如，bunx react-doctor、eslint --format json）
• 搜索模式（例如，匹配 *.test.ts 但没有覆盖率的文件、使用已弃用 API 的组件）
• 差异或变更日志（例如，上次发布后新增的依赖、PR 中变更的文件）
• 应替换为新模式或迁移到新框架的旧模式
• 根据之前的 CI 运行结果识别出的不稳定测试

我们要更改什么？ Agent 对每个目标应用什么转换？

• 修复：就地解决报告的问题
• 迁移：将代码从一种模式更新为另一种模式
• 生成：根据现有源文件创建新文件
• 重构：调整结构，但不改变行为

如何验证？ 什么可以证明更改正确？

• 构建／类型检查通过
• 测试通过（或指定的测试子集通过）
• 发现问题的同一工具现在报告问题已解决
• Lint 或格式检查通过

完成标准：能用一句话描述任务，例如：“找出 5 个 react-doctor 违规项，修复它们，并验证类型检查和质量检查均通过。”

4. 编写 skill

编写一个仓库本地 skill，记录 Agent 针对此任务的判断准则。由于 skill 位于此仓库中，可以包含仓库专属路径、包名和约定。

编写 skill 时遵循以下规则：

• 在 skill 目录的 SKILL.md 中，按顺序列出行为步骤，并为每一步设置可检查的完成标准（目录位置为 .claude/skill-slug-here 或 .agents/skill-slug-here，具体取决于仓库模式和用户偏好）。
• 将较长的模板和示例移至同级参考文件，并在 SKILL.md 中注明其位置。
• 每条规则只保留一个权威来源；不要在 skill、提示词和记忆文件中重复相同指导。
• 添加一个响应模板作为参考文件（例如，skill 目录下的 references/response-template.md），用于规定 CI Agent 的最终输出格式。skill 应要求 Agent 在撰写最终响应时阅读并遵循此模板；最终响应将用作 PR 正文。
• 使用 references/skill-template.md 中的 skill 模板。可在 references/example-skill.md 中查看示例 skill。
• 可参考 https://agentskills.io/specification 了解 skill 规范。

重要：SKILL.md frontmatter 中的 name 字段必须与 skill slug 一致。例如，名为 fix-eslint-issues 的 skill，必须位于 .claude/skills/fix-eslint-issues/SKILL.md 或 .agents/skills/fix-eslint-issues/SKILL.md。

完成标准：skill 应清晰说明如何执行任务，使 Agent 无需额外提示即可遵循，包括最终响应的格式。

5. 编写工作流提示词

将仓库专属的目标范围放在 GitHub Actions 提示词中，而不是通用 skill 中。请包含：

• Begin by using the <skill-name> skill.
• 范围：Agent 可以更改和检查的目录／包。
• 指示：可审查的工作单元、需要避免的事项以及验证方式。
• 如适用，使用 fenced bash 代码块列出验证命令。
• 从 .github/agent-memory/<task-name>.md 插入 Agent 记忆。
• 收尾要求：完成验证、提交、推送，并返回可直接用于 PR 的摘要。

以 references/workflow-template.yml 为基础模板。编写嵌入式提示词时使用 references/prompt-template.md。

完成标准：提示词包含无人值守运行所需的所有仓库专属约束。

6. 安装记忆文件

以 references/memory-template.md 为起点，创建 .github/agent-memory/<task-name>.md。记忆文件记录长期适用的反馈，应影响后续运行。内容保持简短。

适合写入记忆的内容：

• 永久性范围排除项。
• 已知的误报区域。
• 应影响未来 Agent 选择的审核反馈。

不适合写入记忆的内容：

• 一次性任务说明。
• 单次运行的验证输出。
• 技能中已说明的规则。

完成标准：删除记忆文件会导致丢失对未来运行有用的上下文，而不只是历史记录。

7. 创建工作流

根据 references/workflow-template.yml 创建 .github/workflows/agent-<task-name>.yml，并替换所有占位符。

必须自定义以下内容：

• 工作流名称、cron、分支前缀、工作流 ID、Agent 标签、PR 标题。
• 仓库的 Runner 标签和设置步骤。
• 依赖安装命令。
• 编码 Agent 的安装、密钥和无头运行命令（参见 references/agent-runner-templates.md）。
• 响应提取步骤：每个 Agent 的输出格式各不相同（JSON、stream-json、纯文本）。使用 references/agent-runner-templates.md 中对应 Agent 的提取方式，将最终响应写入 /tmp/pr-body.md，用作 PR 正文。
• 技能名称、范围、验证命令和记忆路径。
• PR 数量限制门禁：工作流在运行前检查是否有带 Agent 标签的未关闭 PR。根据用户在步骤 2 中的选择配置上限（默认值：1）。门禁使用 gh pr list --label "$AGENT_LABEL" --state open 并比较数量。如果禁用数量限制，则完全移除门禁步骤。
• 如果启用了 /iterate：将 references/agent-iteration.ts 安装到用户首选的位置，并相应更新工作流路径。该脚本负责生成 PR 页脚和构建迭代提示词。此文件可使用用户首选的 TypeScript 工具链运行（node 的类型剥离功能、Bun（推荐）、Deno、tsx 等），也可根据用户要求改写为其他语言。

如果禁用了 /iterate，则移除 issue_comment 触发器和仅用于迭代的步骤，并跳过安装 agent-iteration.ts。

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

8. 验证和检查

验证工作流 YAML： 提交前解析工作流文件，以便尽早发现语法错误。可使用以下任一工具：

# Node.js / bun (js-yaml)
bunx js-yaml .github/workflows/agent-<task-name>.yml > /dev/null && echo "Valid YAML"

# Python
python -c "import yaml; yaml.safe_load(open('.github/workflows/agent-<task-name>.yml'))"

# yq (if installed)
yq eval '.name' .github/workflows/agent-<task-name>.yml

如果解析失败，请先修复 YAML 语法，再继续。

检查引用和路径： 检查技能、工作流和记忆文件中提到的每个路径，确认其对应的文件已存在，或会由此任务有意创建。

完成标准：工作流 YAML 解析无误，且所有引用的文件均存在。

9. 试运行工作流

GitHub Actions 工作流至少运行过一次后，才能通过 workflow_dispatch 手动触发。请按以下步骤启动工作流：

1. 临时为当前分支添加 push 触发器（如果当前分支不是 main）：

   on:
     push:
       branches:
         - <current-branch-name>  # Remove after first run
     schedule:
       - cron: "0 13 * * *"
     workflow_dispatch:
       # ...
   

2. 提交并推送所有新文件（工作流、技能、记忆文件、脚本）。

3. 工作流会在推送时触发。请在 Actions 选项卡中查看，确认运行成功。

4. 首次成功运行后，移除临时 push 触发器并再次推送。之后即可通过 Actions UI 或 gh workflow run 手动触发工作流。

5. 如果试运行创建了 PR，请检查以确认 Agent 的行为符合预期，然后酌情关闭或合并。

完成标准：工作流显示在 Actions 选项卡中，且可通过 workflow_dispatch 触发。

参考文件

• references/workflow-template.yml - 编码 Agent GitHub Actions 工作流骨架。
• references/agent-runner-templates.md - Claude Code、Codex、OpenCode 和 CodeLayer 的无头命令和密钥。
• references/agent-iteration.ts - /iterate 支持的辅助脚本（PR 页脚和迭代提示词构建）。根据用户偏好，安装到 .github/scripts/、ci-scripts/ 或 scripts/。
• references/prompt-template.md - 工作流中嵌入的提示词结构。
• references/memory-template.md - Agent 记忆文件骨架。
• references/skill-template.md - 生成的任务技能骨架。
• references/response-template.md - CI Agent 最终回复（PR 正文）的格式示例。
• references/example-skill.md - 技能示例