Claude Code Agent Loops 与 SKILL.md 自检工程指南

1. 基本心智模型：Loop 是“行动之后还有校验”

普通聊天像一次函数调用：输入 prompt，得到输出。Agent loop 更像一个控制系统：每轮都要读取状态、采取行动、观察反馈，并决定是否继续。

Agent loop 的最小闭环 上下文不是静态文本，而是每轮行动后的新状态

1 理解上下文 读取需求、代码、日志、评论、测试结果和外部事件。

2 执行行动 编辑文件、调用工具、运行命令、回复评论或创建任务。

3 检查证据 用测试、截图、CI、日志、指标或人工门禁判断结果。

4 修正或停止 未达标就进入下一轮；达标才汇报完成。

关键区别不在“模型有多聪明”，而在“谁触发下一轮、谁定义完成、失败证据能否自动把系统推回修复状态”。

2. 四种 loop：触发方式和停止条件不同

Anthropic 的官方文章把 Claude Code 的循环实践分成四类：turn-based、goal-based、time-based 和 proactive。它们适合的任务、自动化程度和风险边界都不同。

Turn-based

你每轮发起下一步。Claude Code 完成一次行动后停下来汇报，是否继续由你判断。

触发用户输入下一条消息
停止模型认为本轮完成，或需要你补充信息
适合短任务、探索、一次性修改、需要频繁人工判断的工作

Goal-based

你给出明确目标，系统反复尝试，直到 evaluator 判断成功，或达到轮次上限。

触发一个可验证目标，例如分数、测试、CI、错误消失
停止目标达成、轮次耗尽，或遇到不可恢复阻塞
适合测试修复、性能阈值、迁移检查、质量门禁

Time-based

按时间间隔重复执行同一类任务。它关注“外部状态可能已经变化”，例如 CI、评论、队列或日报。

触发每隔 N 分钟、每天、每周，或指定 schedule
停止本轮检查结束，或时间窗口结束
适合轮询 PR、跟进 CI、汇总信息、定期审计

Proactive

事件或计划触发完整工作流，智能体自行发现任务、执行、验证、升级和汇报。

触发事件、定时器、外部系统状态或业务规则
停止流程完成、门禁失败、风险升级或人工接管
适合反馈初筛、依赖升级、告警处理、自动 triage

3. 控制权阶梯：从“你开车”到“系统值班”

四类 loop 不是互斥选项，而是自动化程度逐步上升的阶梯。越往右，越需要明确的权限、预算、停止条件和验收证据。

Turn-based 人类决定下一轮。最灵活，最依赖人工。

Goal-based 人类定义完成标准，系统尝试达成。

Time-based 系统按时间检查变化，适合等待外部反馈。

Proactive 系统主动发现和处理任务，但必须有升级边界。

维度	低自动化	高自动化
触发权	人类逐轮触发	目标、时间或事件自动触发
判断权	人类看结果再决定	evaluator、脚本、CI、指标和门禁判断
风险	速度慢，但误操作范围小	速度快，但需要更硬的权限和回滚策略
沉淀方式	提示词和聊天记录	`SKILL.md`、validator、runbook 和自动化例程

4. 选择矩阵：先看任务能不能被验证

不要先问“用哪种 loop 更高级”，而要先问“完成标准能否机器判断、外部状态是否会变化、失败后能否自动修复”。

任务形态	推荐 loop	验收证据	注意事项
解释代码、梳理方案	Turn-based	引用文件、结论、风险清单	不要伪装成自动完成，保留人工判断空间。
修复测试失败	Goal-based	失败测试变绿、相关回归通过	设置轮次上限，防止为了过测试破坏真实逻辑。
等待 CI 或 PR 评论	Time-based	CI 状态、评论线程、commit 结果	每轮都要避免重复提交和重复回复。
反馈初筛和自动派单	Proactive	分类结果、关联上下文、升级记录	必须定义权限、静默失败处理和人工升级条件。
UI 变更自测	Goal-based + Skill	浏览器截图、console、交互路径、响应式检查	不要只用构建成功代替可见页面验收。

5. SKILL.md 的作用：把人工提醒变成默认流程

Skill 不是“更长的 prompt”。它更像团队 runbook：告诉智能体什么时候使用、必须读取什么上下文、怎么执行、怎么验证、失败后怎么修复，以及最终必须交付哪些证据。

SKILL.md 文件结构

YAML frontmatter name 和 description 决定技能何时被自动发现或手动调用。

Trigger rules 明确任务边界，避免每个请求都误触发。

Workflow 写清读取、修改、验证、回滚、汇报的顺序。

Validators 把测试命令、脚本、截图、日志检查写成硬步骤。

Evidence report 最终回复必须说明跑了什么、通过什么、还剩什么风险。

Skill 把“提醒”变成“门禁” 从手工检查迁移到可重复自检

6. 端到端自检：不要把“完成”定义成“我改了文件”

端到端自检的目标不是让 agent 多跑命令，而是把“真实用户会不会成功”变成可观察证据。对前端、后端、数据任务、文档任务，证据形态不同，但结构相同。

自检闭环 validator 失败时，自动回到修复阶段

1 准备环境 安装依赖、启动服务、加载种子数据。

2 执行路径 模拟真实入口，而不是只调用内部函数。

3 采集证据 测试、截图、日志、指标、SQL 或 API 响应。

4 判断结果 通过阈值、断言、schema、视觉检查或人工门禁。

5 修复重跑 失败不得直接汇报完成，必须回到行动。

对 UI 任务，最低自检通常包括：启动页面、实际点击、检查状态变化、看 console、做桌面和移动端截图。对 API 任务，最低自检通常包括：接口请求、响应 schema、错误路径和日志。

好的停止条件

指定测试命令全部通过。
目标页面在浏览器中可见，核心交互成功。
CI 状态为 green，且没有新增失败评论。
性能、覆盖率或错误率达到明确阈值。
失败原因被记录，并有下一步升级路径。

危险停止条件

“代码看起来没问题”。
“我已经修改完成”。
“构建过了，所以用户路径也应该没问题”。
“因为没有更多错误输出，所以可以结束”。
“测试太慢，这次先不跑”。

7. 一个可复制的 SKILL.md 自检模板

下面的模板可以作为团队技能的起点。实际使用时，最重要的是把 validator 从自然语言变成具体命令、脚本、截图步骤或可判定阈值。

---
name: verify-change-end-to-end
description: Use when a code or documentation change must be verified through the real user-facing path before reporting completion.
---

# End-to-End Verification Skill

## When to use

Use this skill when the task changes behavior, UI, API contracts, data shape,
automation, deployment configuration, or user-facing documentation.

Do not report completion based only on file edits.

## Workflow

1. Read the user's request and identify the changed surface:
   - UI page or workflow
   - API endpoint or background job
   - database migration or data import
   - CLI command or automation
   - documentation page or generated artifact

2. Define the acceptance evidence before editing:
   - test command
   - browser path and interaction
   - API request and expected response
   - database query
   - log or metric check
   - screenshot or rendered artifact

3. Make the smallest scoped change that can satisfy the acceptance evidence.

4. Run validators in this order:
   - static checks, lint, typecheck, or schema validation
   - unit or focused regression tests
   - integration or browser checks for the changed path
   - artifact inspection for screenshots, PDFs, docs, or generated output

5. If any validator fails:
   - read the failure literally
   - fix the root cause
   - rerun the failed validator
   - rerun any earlier validator that could be invalidated by the fix

6. Stop only when the acceptance evidence is satisfied, or when a true blocker
   prevents further progress.

## Reporting

Final response must include:

- files changed
- validators run
- evidence observed
- known gaps or tests not run
- exact blocker, if blocked

Never say "done" without evidence.

把动词写具体 不要写“检查页面”，写“打开 /settings，切换 Billing tab，保存表单，检查 toast 和网络响应”。

把阈值写清楚 不要写“性能不错”，写“Lighthouse performance >= 90，最多尝试 5 轮”。

把失败路径写进去 validator 失败时必须修复并重跑，不能直接把失败结果包装成完成说明。

把证据留在回复里 最终报告要能让人知道：到底跑了什么、看到什么、哪些风险没覆盖。

8. 反模式：自动化越强，越不能靠感觉

loop 和 skill 的风险不是“模型不会做事”，而是“模型很会做事，但没有清晰边界”。下面这些反模式会让 agent 看起来高效，实际却不可靠。

反模式	表现	修正方式
目标不可判定	“优化一下”“修到没问题”“体验更自然”	改成明确阈值、断言、截图、错误消失或人工验收项。
只验最短路径	主流程过了，但权限、空状态、失败状态和历史数据没测	把异常路径写成 validator 或风险残留。
轮询无幂等	time-based loop 重复发评论、重复提交、重复创建任务	记录已处理状态，检查现有结果后再行动。
权限过宽	proactive loop 能直接改生产配置或大范围删除数据	限制工具、目录、分支、预算和人工审批点。
汇报无证据	最终回复只说“已完成”，没有命令、截图、日志或结果	把 Verification Report 写成 skill 的强制输出格式。

实战判断：能不能用 proactive loop，不取决于模型能力，而取决于你的门禁、权限、回滚、审计和升级路径是否已经写清楚。

9. 参考资料

本文基于 Claude Code 官方 loop 文章和 Skills 相关文档整理，并加入面向工程团队的落地模板。

LoopsAnthropic, Getting started with loops.
SkillsAnthropic, Claude Code Skills.
Best practicesAnthropic, Skill authoring best practices.
RoutinesAnthropic, Claude Code Routines.
Agent designAnthropic, Building effective agents.