AI 编程 Loop 工程 — Agent Loop Engineering

你现在运行 agent-loop-engineering 技能。目标：把 coding agent 从「每次都手写 prompt」升级成「拥有一条可跑、可评分、可硬化的 loop」——一条能自己被 loop-audit 打分、能被 gate.yaml 卡红线、能被 loop-cost 提前算钱的常驻回路。

底层是 Cobus Greyling 出品的开源 loop-engineering（MIT、5.5k+ stars，Addy Osmani + Boris Cherny 撰文背书），一共 7 个已发的 @cobusgreyling/loop-* npm 包，本课直接消费上游 CLI：

CLI	用来
`@cobusgreyling/loop-init`	一把在你仓库里落 `STATE.md` / `LOOP.md` / `loop-budget.md` / `loop-run-log.md` / `AGENTS.md` / `loop-constraints.md`
`@cobusgreyling/loop-audit`	Loop Readiness Score（L0–L3, 0–100）+ 逐条 finding + `--badge` 生成 README 徽章
`@cobusgreyling/loop-cost`	按 pattern × cadence × 等级估 token / 每日 $ 预算
`@cobusgreyling/loop-sync`	检测 `STATE.md` ↔ `LOOP.md` drift，避免意图和记忆漂移
`@cobusgreyling/loop-context`	常驻 loop 的记忆管理 + 「无进展就停下并升级人」的 circuit breaker
`@cobusgreyling/loop-worktree`	每次修一个问题起一个隔离 worktree，失败的尝试自动回收
`@cobusgreyling/loop-mcp-server`	把 pattern / skill / state / audit 暴露成 MCP 资源，供其它 agent 运行时查询

gate.yaml（denylist / auto_merge_allowlist / budget）是配置文件，被 loop-audit、CI workflow 和你自己的 fix skill 读取，本课不依赖任何单独的 loop-gate CLI。

这门课做什么（边界写在第一屏）

✅ 做：在你现有 git repo 里 5 步把 Loop Ready 从 10 分推到 100 分：① 起脚手架 → ② 估成本 → ③ 首次审计 → ④ 加 gate.yaml + safety doc + verifier skill → ⑤ 二次审计 + 徽章嵌 README。产物永远长在你仓库里，可 diff、可版本、可 review。
✅ agent-as-LLM：每一步「跑哪个 CLI、怎么读 finding、把哪条建议落进 STATE.md / LOOP.md」由你正在用的那款 coding agent（Claude Code / Codex / Grok / OpenCode / Cursor）自己想。本课不导入任何商业 LLM SDK、不设置任何 base URL、不调任何远端推理服务。
✅ 完全本地：7 个 CLI 全部 npx 走本地缓存；loop-audit 读你仓库文件系统 + git log，loop-cost 是 heuristic 表；无网络推理、无 telemetry。
❌ 不做：事后成本审计（→ agent-cost-audit，那门课审的是账单）；一屏并行 pane（→ parallel-agents）；仓库审计→plans/*.md（→ agent-plan-then-execute）；一包 skill 让 agent 变听话（→ agent-lazy-coder）。本课的评分对象是 loop 本身，不是仓库代码，也不是账单。
🔒 零 API key、零代理、零远端调用、不接 Clawvard SDK。

一句话定位：agent-cost-audit = 事后算 loop 花了多少；agent-loop-engineering = 事前把 loop 设计、评分、卡住，让它值得跑。

前置

Node ≥ 18（node -v）
一款你已经在用的 coding agent CLI —— Claude Code / Codex / Grok / OpenCode / Cursor，用你自己的订阅登录；本课不代你付任何 LLM 费用
目标目录必须是 git repo（loop-audit 读 git log 判定「有没有真跑」）
无 GPU 要求；macOS / Linux / WSL 均可

5 步 quickstart

一次跑完，看着 Loop Ready 从 10 → 100 爬完两级。全程在你自己的仓库根目录。

步骤 1 — 起脚手架

先识别你正在用的 coding agent：Claude Code → --tool claude；Codex → --tool codex；Grok → --tool grok；OpenCode → --tool opencode；Cursor → 也用 --tool grok 起手（template 通用）。

npx @cobusgreyling/loop-init . --pattern daily-triage --tool <your-tool>

跑完你会看到 6 个新文件：STATE.md、LOOP.md、loop-budget.md、loop-run-log.md、loop-constraints.md、AGENTS.md，以及 .<tool>/skills/{loop-triage,loop-budget,loop-constraints}/SKILL.md。逐个 head -20 看一眼模板长什么样，别一句「已生成」敷衍过去——用户需要知道未来编辑哪个字段。

步骤 2 — 估成本

npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d

输出 4 档预估：early-exit / full-triage / action-every-run / realistic-blend + "Suggested daily cap: N tokens"。把 realistic 数字写进 loop-budget.md 的 ## Budget 段，把 daily cap 记下来给 gate.yaml 用（见步骤 4）。

步骤 3 — 首次审计

npx @cobusgreyling/loop-audit . --suggest

刚 init 完通常已经 100/100——--tool grok / --tool codex / --tool opencode 停在 L2（脚手架里 STATE / LOOP / budget / run-log / triage skill / constraints 全齐但没 verifier）；--tool claude 因为默认多带一份 .claude/agents/loop-verifier.md，直接进 L3。任意一种：这不是终点——分数只是覆盖率，看剩下的 ! 建议：多数是「加 verifier skill（如果没有）/ 加 safety doc / 加 .github workflow / 加 patterns registry / 收敛 tool 权限」。

不要一次改完。先只做能拿快胜的两三条：

把 STATE.md 的 "Last run" 从 never 改成上一次实际时间戳（哪怕是手动跑的）
把 LOOP.md 里空的 trigger 填成真实 cron / webhook / 手动 /loop 意图
把 AGENTS.md 里空 stub 段补一句本项目上下文

步骤 4 — 加 gate.yaml + verifier + safety doc

Loop Ready 里 level 从 L2 升 L3 的门槛不是分数，而是四件硬件：

gate.yaml（本课模板见 references/gate-yaml.md）—— denylist / auto_merge_allowlist / budget 三段。
docs/safety.md —— 一段人类可读的：这条 loop 禁止碰什么、允许自动合并什么、MCP 权限、circuit breaker 规则。
.<tool>/skills/loop-verifier/SKILL.md —— 一个只读 skill，收到 maker 的 diff 后 approve / block；帮你把 maker/checker 分离出来。
SKILL.md 顶部加 allowed-tools: —— 每个 skill 只声明它真正需要的工具（Read / Grep / Edit / Bash 子集），least-privilege。

# 参考模板复制
mkdir -p docs .<your-tool>/skills/loop-verifier .github/workflows patterns
# 从 loop-audit --suggest 输出粘 cp templates/SKILL.md.verifier ...

gate.yaml 本身不需要单独的 CLI 去 enforce：loop-audit 会读它并把「gate 就位」计入评分，你的 fix skill 应该在真去改文件前先把 denylist 当禁飞区读一遍，CI workflow 也可以直接 grep 它。参考模板见 references/gate-yaml.md。

步骤 5 — 二次审计 + 徽章嵌 README

npx @cobusgreyling/loop-audit . --suggest       # 分数不动（还是 100/100）但 level 应升到 L3
npx @cobusgreyling/loop-audit . --badge >> README.md

--badge 输出一行 markdown（[![Loop Ready L3 (100/100)](https://img.shields.io/badge/...)](https://...)）——直接追加到你 README.md 顶部。GitHub 会自动从 shields.io 拉真实徽章图，你的同事一眼看到这条 loop 现在处在哪一级。

步骤 6 — 上跑

告诉用户在他自己那款 coding agent 里发的 /loop 命令：

Grok：/loop 1d Run $loop-triage. Update STATE.md. No auto-fix in week one.
Claude Code：/loop 1d Run @loop-triage. Update STATE.md. No auto-fix in week one.
Codex / OpenCode：等价语法，--tool 输出的 quickstart 里有

week-1 铁律：只 report，不 auto-fix。让人类每天早上把 STATE.md 扫一眼，判断这条 loop 报出来的 finding 是不是符合直觉，再逐步开 L2。

铁律

不做 wrapper：7 个 @cobusgreyling/loop-* CLI 全部原生 npx 调，不新增 @clawvard/* 一层薄包装。gate.yaml 只是仓库根的配置文件，由 loop-audit / CI / 你的 fix skill 直接读取——没有单独的 loop-gate CLI（上游 README 提过但 npm 未发布）。
不设置任何 OpenAI-compatible base URL、不做任何远端推理转发：本课 100% 走用户 coding agent 自己的官方 endpoint。
本课自身零 LLM 调用：只有你手上那款 coding agent 会调 LLM，本课 SOP 不代替它调。
不接 Clawvard 任何后端 / SDK：commercialApi: false, runsLocally: true。
产物在仓库里长期驻留：STATE.md / LOOP.md / gate.yaml / loop-budget.md / loop-run-log.md 是 git 追踪的普通 markdown 和 yaml，不是产品化 SaaS 状态。你的 loop 就是你的仓库。

常见坑

loop-audit 分数一直 100 但 level 卡在 L2：level ≠ score。level 靠 verifier skill + safety doc + tool 权限收敛 + .github/workflows + 真实活动等硬件；分数只是覆盖率。用 --tool grok/--tool codex/--tool opencode 起手就是这种状态，加齐步骤 4 的四件硬件就升 L3；--tool claude 起手就带 verifier，通常直接是 L3。
week-1 就开 auto-fix：不要。先让人两三天扫 STATE.md，验证 finding 分布符合直觉。突然把 L1 report 跳到 L3 unattended = 你连 baseline 都还没建立。
loop-cost 报「worst case 超预算」：正常。它是最坏预估。把 realistic blend 写进 loop-budget.md，worst case 写在 ## Warnings 里做提醒。
忘了加 loop-context --check：常驻 loop 一旦跑起来忘停就会烧钱。每一次 tick 前跑 npx @cobusgreyling/loop-context --check --ledger loop-ledger.json，exit 2 就 escalate 给人。这条属于 L2+ 必备。
gate.yaml 只当摆设：loop-audit 只看你有没有这个文件，enforce 要你自己在 fix skill / CI 里读。写完立刻在 .github/workflows/loop.yml 里加一步 grep -F 'secrets/' gate.yaml && echo denylist present 类似的自检。

Pattern 选择

7 种上游 pattern，一句话对比见 references/patterns.md。起步一律 daily-triage。想直接上 pr-babysitter / ci-sweeper 的，先跑一遍 daily-triage 建立 baseline，别跳级。

学习完成后

告诉用户：

我已经学会了 agent-loop-engineering。给我一个 git 仓库，我用 @cobusgreyling/loop-* 7 个 CLI 帮你 5 步走完：起脚手架、估成本、首次审计、加 gate.yaml + verifier + safety doc、二次审计并把徽章嵌 README。走完你会拿到 STATE.md / LOOP.md / gate.yaml / loop-budget.md / loop-run-log.md 长在仓库里，以及一枚从 L0 10/100 爬到 L3 100/100 的 Loop Ready 徽章。全程本地，本课不调用任何 LLM——推理由你自己的 coding agent CLI 走它的官方 endpoint。 课程主页 https://clawvard.school/courses/agent-loop-engineering。