用途
这份 Playbook 的目标，是把“会提示 agent”升级为“会设计、运行、审查 agent loop”。
适合场景：
- 代码维护
- CI 修复
- issue triage
- PR 审查
- 日志巡检
- 日常工程自动化
它不追求一上来就做“全自动工程师”。相反，它强调：先让 loop 可停止、可验证、可复盘、可交回人类。
Playbook 总览
一个可运行的 agent loop 必须回答六个问题：
- 目标是什么？
- 触发条件是什么？
- agent 能访问哪些上下文和工具？
- 谁来执行，谁来验证？
- 状态和经验写到哪里？
- 哪些情况必须交回给人？
如果这六个问题没有答案，不要启动长期 loop。先缩小范围。
先回答六个问题，再启动长期 loop。否则你启动的不是系统，而是失控的长提示词。
Loop 设计画布
每次设计新 loop，先填这张表。
| 模块 | 要填写的内容 | 示例 |
|---|---|---|
| Loop 名称 | 这个 loop 负责什么 | Daily CI Triage |
| 业务目标 | 为什么值得自动化 | 每天发现 main 分支 CI 失败并归因 |
| 触发方式 | 手动、定时、事件 | 每天 9:00，或 CI 失败后 |
| 输入来源 | repo、CI、issue、日志、数据库 | GitHub Actions、open issues、recent commits |
| 执行 agent | 谁负责分析或修改 | triage agent、fix agent |
| 验证 agent | 谁判断是否完成 | verifier agent |
| 停止条件 | 什么叫完成 | 原失败复现、修复后相关测试通过 |
| Memory | 状态写在哪里 | memory/ci-triage.md |
| 人类介入点 | 什么时候交给人 | 生产数据、权限、架构改动、证据不足 |
| 输出物 | 每次运行留下什么 | triage report、PR、memory entry |
Loop 设计画布的价值，是把自动化冲动压缩成可审查的系统规格。
Phase 1：定义目标
操作步骤
- 写出一句业务目标。
- 把业务目标改写成可检查的工程目标。
- 写出停止条件。
- 写出不做什么。
模板
## Goal
Business goal:
-
Engineering goal:
-
Done only if:
-
-
-
Out of scope:
-
- 通过标准
- 目标能被第三方 verifier 判断。
- 停止条件可以通过命令、日志、diff 或明确证据验证。
- 没有使用“优化”“完善”“检查一下”这类软目标。
目标不是愿望。目标是第三方 verifier 能判断的完成合同。
Phase 2：设计上下文和工具边界
操作步骤
- 列出 agent 必须读取的上下文。
- 列出 agent 可以使用的工具。
- 明确危险工具和禁止动作。
- 写入 skill 或项目说明。
工具权限分级
| 级别 | 权限 | 适用场景 |
|---|---|---|
| Read only | 读文件、读日志、读 issue | triage、审查、分析 |
| Local write | 修改本地文件、跑测试 | 小型修复 |
| Repo write | 创建分支、提交、开 PR | 明确修复 loop |
| External write | 更新 ticket、发 Slack | 成熟 loop |
| Production write | 改线上数据或配置 | 默认禁止，必须人工确认 |
通过标准
- agent 不需要靠猜测了解项目约定。
- 高风险工具有明确限制。
- 输出里必须包含使用过的关键证据来源。
工具边界越清楚，loop 越像工程系统；工具边界越模糊，loop 越像风险放大器。
Phase 3：拆分 Maker 和 Checker
推荐角色
| 角色 | 职责 | 不该做什么 |
|---|---|---|
| Explorer | 阅读代码、日志、issue，提出假设 | 不直接大改代码 |
| Implementer | 按目标做最小修改 | 不宣布最终完成 |
| Verifier | 根据 rubric 判断是否达成 | 不替 implementer 找借口 |
| Reviewer | 从维护性、安全性、边界条件挑错 | 不扩大需求 |
Verifier 指令模板
你是 verifier，不是实现者。
任务：
- 根据 rubric 判断目标是否达成。
- 自己检查 diff、日志、测试结果和证据。
- 如果证据不足，返回 not complete。
- 不要因为实现者声称完成就接受。
输出格式：
- Verdict: complete / not complete
- Evidence:
- Missing evidence:
- Risks:
- Required next action:通过标准
- 做事的人和验收的人不是同一个上下文。
- verifier 有明确 rubric。
- verifier 可以返回
not complete，且 loop 会继续或交回给人。
做事的人，不应该独自宣布任务完成。
Phase 4：写 Rubric
Rubric 是 loop 的验收合同。它决定 loop 什么时候可以停。
通用 Rubric 模板
# Rubric: <loop name>
Complete only if:
- The original problem is reproduced or explained with evidence.
- The root cause is stated clearly.
- The change is limited to relevant files.
- Required checks pass.
- The output includes commands or evidence used for verification.
- Any reusable lesson is written to memory.
Not complete if:
- The agent cannot show evidence.
- The fix changes unrelated files.
- Tests were skipped without explanation.
- The result depends on an unverified guess.
- The task requires human approval.通过标准
- 每条标准都能被检查。
- 包含正向完成条件和反向失败条件。
- 明确何时升级给人类。
Rubric 不是形式感。它是 loop 的刹车系统。
Phase 5：设计 Memory
Memory 是跨会话 loop 的脊柱。它不是聊天记录，而是经过验证的状态和规则。
Memory 写入规则
只写三类东西：
- 已验证事实。
- 当前状态。
- 未来可复用规则。
不要写：
- 没验证过的猜想。
- 大段流水账。
- 实现者的自我表扬。
- 已经过期的临时状态。
Memory 条目模板
## <date> <topic>
Status:
- verified / unresolved / handed-off
Fact:
-
Evidence:
- Command:
- File:
- Log:
Rule:
-
Next time:
-
Open questions:
- 五步记忆法
- Fail：记录失败。
- Investigate：查清原因。
- Verify：用证据确认。
- Distill：提炼成规则。
- Consult：下次先读规则。
Memory 的价值不是记录所有东西，而是让下一轮少踩同一个坑。
Phase 6：运行最小可用 Loop
从小 loop 开始，不要一开始就全自动合并。
Daily Repo Triage Loop
Cadence:
- 每天一次，或手动触发。
Inputs:
- 最近 24 小时 CI 失败。
- 新增 issue。
- 最近 commits。
Agent task:
- 找出最多 3 个值得处理的问题。
- 对每个问题写明证据、影响、建议动作。
- 不直接修改代码，除非问题有明确复现路径。
Verifier:
- 检查每个问题是否有证据。
- 没有证据的项目降级为观察项。
Memory:
- 记录已确认的问题、已忽略噪声、重复出现的模式。
Human review:
- 选择一个问题进入修复 loop。运行后输出
## Run Report
Loop:
Date:
Trigger:
Findings:
1.
2.
3.
Actions taken:
-
Verification:
-
Memory updated:
- yes / no
Needs human:
- yes / no
- reason:Phase 7：从 Triage 进入 Fix Loop
只有满足以下条件，才进入自动修复：
- 问题有明确证据。
- 影响范围小。
- 可以在隔离 worktree 修改。
- 有可运行的验证命令。
- 不涉及生产权限、数据迁移、账务、安全策略。
Fix Loop 模板
Goal:
- Fix <specific problem>.
Steps:
1. Reproduce or confirm the failure.
2. Identify the smallest relevant code path.
3. State the hypothesis before editing.
4. Make the smallest reasonable change.
5. Run targeted checks.
6. Ask verifier to judge against rubric.
7. If complete, prepare PR summary.
8. If not complete after 2 attempts, hand off to human.
Stop:
- Related tests pass.
- Verifier returns complete.
- Run report and memory are updated.
先分诊，再修复；先证据，再自动化。
Human Gate：必须交回给人的情况
遇到这些情况，loop 不应该继续自动推进：
- 需要产品取舍。
- 涉及用户数据、隐私、安全、支付、权限。
- 需要生产环境写操作。
- 修改公共 API 或数据库 schema。
- 测试缺失，无法验证。
- verifier 连续两次返回证据不足。
- agent 的修改超过预期范围。
- 出现相互矛盾的证据。
Human Gate 不是低效，而是让判断权留在正确节点。
Review Checklist
每次 review loop 输出，按这张表看。
## Agent Loop Review
Goal clarity:
- [ ] 目标明确
- [ ] 停止条件明确
Evidence:
- [ ] 有复现或日志证据
- [ ] 有验证命令
- [ ] 有 diff 摘要
Scope:
- [ ] 修改范围合理
- [ ] 没有无关格式化
- [ ] 没有引入新依赖或新架构，除非明确需要
Quality:
- [ ] 相关测试通过
- [ ] 风险被说明
- [ ] reviewer/verifier 独立检查过
Memory:
- [ ] 写入了可复用事实或规则
- [ ] 没有把未验证猜想写成规则
Decision:
- [ ] accept
- [ ] request changes
- [ ] hand off to humanAnti-patterns
| 反模式 | 表现 | 修正 |
|---|---|---|
| Prompt loop | 只是反复让 agent 继续 | 写停止条件和 verifier |
| Rubber-stamp verifier | 只读实现总结 | verifier 必须看证据 |
| Memory junk drawer | 什么都写进 memory | 只写 verified fact 和 rule |
| Parallel chaos | 多 agent 改同一工作区 | 每个任务独立 worktree |
| Auto-merge fantasy | 一上来就全自动合并 | 先 triage，再人工 gate |
| Cognitive surrender | 人不再理解输出 | review 时必须读 diff 和证据 |
成熟度模型
| 等级 | 状态 | 判断标准 |
|---|---|---|
| L0 | 手动 prompt | 人每一步推动 |
| L1 | 单次目标 loop | agent 根据目标连续工作到停止条件 |
| L2 | Triage loop | agent 定时发现问题并写报告 |
| L3 | Fix loop | agent 能在隔离环境修小问题并请求验证 |
| L4 | Multi-agent loop | maker/checker/reviewer 分工清楚 |
| L5 | Operational loop | 接入真实工具、memory、人工 gate，可长期运行 |
成熟不是更自动，而是更可控。
复制即用：创建一个新 Loop
# Loop Spec: <name>
Owner:
Purpose:
Cadence / Trigger:
Inputs:
Tools allowed:
Tools forbidden:
Skill / context files:
Maker agent:
Verifier agent:
Rubric:
Memory location:
Human gate:
Run report format:
First dry run date:
Success metric after 2 weeks:教练提示
判断一个人是否真的会 agent loop，不看他说了多少模型名，而看他能不能稳定回答：
- 这个 loop 为什么会停？
- 停的时候谁说了算？
- 证据在哪里？
- 失败会不会污染下一轮？
- 多个 agent 会不会互相踩？
- 人类在哪些节点保留判断权？
能回答这些，才是在设计 loop。否则只是把 prompt 写长了。