A Practical Guide to Loop Engineering: Automating AI Workflows with Markdown

1. Loop Implementation Requires Three Markdown Files

To run a Loop, you need exactly three Markdown files—no more, no less:

AGENTS.md / CLAUDE.md : the "constitution" that tells the Agent the project rules, safety boundaries, and commands to execute.

STATE.md : the "memory" that records the last run, discovered items, and next steps.

SKILL.md : the "skill cards" that encapsulate concrete abilities (triage, fix, verification) which the Agent loads on demand.

The division of labor is: AGENTS.md constrains the loop, SKILL.md defines what the loop can do, and STATE.md tracks progress.

2. AGENTS.md / CLAUDE.md – The Loop Constitution

This top‑level configuration file is read by the Agent at every start. It defines the loop mode, safety rules, and verification requirements.

# CLAUDE.md — 项目循环配置

## 循环模式
- 初始阶段：L1 报告模式（只汇报，不改代码）
- 读完 STATE.md 再开始分诊
- 每次跑完更新 STATE.md

## 安全规则
- 不自动合并代码，不经人工审批不能推送
- 禁止修改 .env、auth/、payments/、credentials/
- 每次改代码必须用 git worktree 隔离
- 同一个问题最多尝试 3 次，超限升级给人

## 验证要求
- 任何代码改动必须由独立的验证者子 Agent 检查
- 必须跑项目测试，不能只看代码
- 验证结果写回 STATE.md

The same structure can be used for OpenAI Codex with a file named .codex/AGENTS.md and its own set of rules (daily triage, work‑tree policy, token budget, etc.).

3. STATE.md – The Loop Memory

Because the loop is not a one‑off run, STATE.md remembers where the loop left off.

# Loop State — {{你的项目名}}

上次运行: (每次循环自动更新)

## 高优先级（循环正在处理或等人决策）
<!-- 格式:
- [ ] ID — 一句话描述
  循环操作: 上次做了什么
  人工决策: (如果有)
-->

## 观察列表
<!-- 暂时不动但持续关注 -->

## 本次忽略的噪音
<!-- 持续出现噪音说明需要调整分诊规则 -->

---
运行记录: (时间戳) | 发现 N 项 | 处理 N 项 | 升级 N 项

The file is updated by SKILL.md implementations according to the rules below.

4. SKILL.md – Defining Loop Capabilities

Each SKILL.md contains a YAML front‑matter and a Markdown body. The Agent loads the file progressively:

Level 1 (≈100 tokens) : only the name and description fields are read to decide whether the skill should be invoked.

Level 2 : after the decision, the full body is loaded.

The description is crucial—if it is vague the Agent will never trigger the skill.

Good description example (loop‑triage):

---
name: loop-triage
description: >
  分诊最近 24 小时的 CI 失败、Issue 和提交。
  产出结构化的优先级报告供循环消费。
  将输出写入 STATE.md.
user_invocable: true
---
# Loop Triage Skill

你是分诊 Agent。产出结构化的优先级列表。

## 输入（循环会提供）
- 最近 24 小时 CI/测试失败
- 负责人名下的 Open Issue
- 最近 24‑48 小时 main 分支提交
- 当前 STATE.md

## 输出格式
### 1. 高优先级（立即处理）
- 一句话描述
- 为什么重要（影响/风险）
- 建议循环下一步操作
- 预估工作量

### 2. 观察项（监控但不处理）
- 同上格式，但优先级低

### 3. 噪音/忽略
- 看了但不值得处理的

### 4. 状态更新
- 循环下次需要记住的事实

## 规则
- 只有工程师今天会关心的才放"高优先级"
- 不确定的放"观察"或"噪音"，不要制造工作
- 分诊只做信号，不做架构设计

Bad description example (triage):

---
name: triage
description: 帮助分析项目状态
---

Because the description does not specify *what* the skill does, the Agent will never call it.

Other essential skills shown in the article: minimal-fix: produce the smallest code diff that fixes a given problem without touching unrelated files. loop-verifier: an independent validator that rejects changes unless evidence is sufficient; it runs tests and checks scope.

5. Prompt Writing – /loop and /goal

The core prompt is /loop. Its syntax determines what the loop does and how it does it.

L1 Report Mode (read‑only):

/loop 1d 跑 loop‑triage Skill。先读 STATE.md。把高优先级项追加到 STATE.md。只报告，不修代码。

L2 Triag​e + Small Fix (automatic repair of simple issues):

/loop 1d 跑 loop‑triage Skill。高优先级中小修小补的：开工作树 → 跑 minimal‑fix → 跑 loop‑verifier → 验证通过的开 PR。中高风险升级给人。更新 STATE.md。

L3 Near‑Unattended (tight limits, human approval for risky changes):

/loop 2h 跑 loop‑triage。可自动修复标了 quick‑win 标签的问题。其他按优先级排序。依赖升级只修低风险 CVE。合代码前必须人工 approve。每天 token 上限 100k。

The /goal command runs the loop until a concrete, verifiable condition is met, e.g. all tests pass or a migration is complete.

# 持续跑直到测试全绿
/goal "test/ 目录下所有测试通过，lint 干净"

# 持续跑直到完成重构
/goal "计费模块全部迁移到新 API，旧 API 零调用"

# 持续跑直到文档写完
/goal "README.md 覆盖所有 API 端点，每个端点含示例代码"

When writing goals, the article stresses three rules: the goal must be objectively verifiable, its scope must be limited, and the description should state *what* to achieve, not *how*.

6. LOOP.md – Optional Loop Configuration

Beyond the three core files, a LOOP.md can describe how the loop itself is scheduled, its budget, and manual gates.

# Loop 配置

## 活跃循环
| 模式 | 频率 | 阶段 | 触发命令 |
|------|------|------|---------|
| 每日分诊 | 1d | L1 报告模式 | /loop 1d |
| PR 保姆 | 手动 | L2 | /loop run pr-babysitter |

## 人工关口
- L2 之前不做自动修复
- 安全/支付/基础设施路径必须人工审查
- 自动合并仅限低风险依赖更新

## 预算
- 每日分诊上限 100k tokens
- PR 保姆每次上限 200k tokens
- 每个子 Agent 最多产生 2 个
- 预算耗尽切为报告模式

## 关闭开关
- 给项目打 `loop-pause-all` 标签 → 暂停所有调度
- 给项目打 `loop-resume` 标签 → 恢复调度

7. From Zero to a Working Loop

Copy the STATE.md template to the project root.

Create .claude/CLAUDE.md (or .codex/AGENTS.md) and write the project rules and safety boundaries.

Place the

loop‑triage

SKILL.md

under .claude/skills/loop‑triage/SKILL.md.

Run the loop in Claude Code:

/loop 1d Call $loop‑triage. Read STATE.md first. Append findings. Report only, no fixes.

After a week, review STATE.md and tune the triage rules.

In the second week, add minimal‑fix and loop‑verifier skills to enable automatic small fixes.

/loop 1d Call $loop‑triage. For high‑priority items that look like small bugfixes: open worktree → $minimal‑fix → $loop‑verifier → on approve, open PR. Update STATE.md.

Continue iterating; most users stop at L2, while L3 (near‑unattended) requires weeks or months of trust building.

The guide concludes that reaching L2 already yields a dramatic efficiency boost over manual prompting, whereas L3 demands extensive validation and monitoring.