Loop Engineering Playbook

把 Loop Engineering 从概念变成可执行、可验证、可复用的工程工作流。

A practical playbook for building agentic loops that discover, act, verify, persist, and run again.

项目定位

这个项目不是一个万能 agent 平台，也不是 prompt 合集。它是一套轻量的工程手册和模板库，用来帮助你设计会自己转动、但仍然受工程判断约束的 AI 工作流。

Loop Engineering 的核心不是让 agent 多跑几次，而是把一次运行扩展成一个有状态系统：

1. 发现值得做的任务。
2. 把任务隔离交给执行者。
3. 用独立验证者说“不”。
4. 把状态写到聊天窗口之外。
5. 在下一轮自动接上。

为什么需要它

Prompt engineering 解决的是“这句话怎么写”。Context engineering 解决的是“这一轮该给模型看什么”。Harness engineering 解决的是“单次运行怎么配工具、权限和完成条件”。Loop engineering 再往上一层：它解决“如何让系统自己发现、执行、验证、记住并再次运行”。

生成正在变便宜，判断正在变稀缺。这个项目的目标是把判断力写进工作流，而不是把判断力交给一个会点头的循环。

项目内容

• docs/：Loop Engineering 的概念、五动作、六组件、反模式和落地路线。
• site/：中英对照 HTML 课件版本，可直接用浏览器打开。
• principles.md：构建 loop 时必须遵守的技术原则。
• checklists/：first loop、安全门、token 预算和人工审查检查清单。
• templates/：AGENTS.md、SKILL.md、generator/evaluator/reviewer、状态文件模板。
• workflows/：GitHub Actions 与 Codex automation 草案。
• examples/：只读 repo triage loop 示例。
• assets/：项目配图和配图说明。

推荐阅读顺序

1. 概念总览
2. 快速开始
3. 使用场景
4. 五个动作
5. 六个组件
6. 生成者与验证者
7. 架构
8. 反模式
9. 运营纪律
10. 采用路线

Quickstart

运行一个只读 repo triage demo：

python3 scripts/read_only_repo_triage.py --repo .

它只读取仓库结构和 git 状态，输出：

• state/triage.md
• state/inbox.md

不会修改代码、不会提交、不会推送、不会调用外部 API。

Bilingual HTML Courseware

打开本地课件首页：

open site/index.html

内容包括概念总览、快速开始、五个动作、六个组件、生成者与验证者、架构六个模块，配套手绘解释图和中英对照说明。

First Loop 最小闭环

第一条 loop 不应该从自动改代码开始。推荐从只读 repo triage 开始：

1. 定时读取 CI、issue、recent commits 和上次状态。
2. 写入 state/triage.md。
3. 对高价值问题生成建议。
4. 独立 evaluator 检查建议是否可执行。
5. 不自动 merge，不自动 push，不删除文件。

最小目标是证明系统能稳定发现问题、记录状态、拒绝坏建议，而不是证明它能一次做很多事。

安全边界

默认边界：

• 不自动 merge。
• 不自动删除。
• 不自动发布。
• 不自动提交敏感数据。
• 不把密钥、token、cookie 或私人资料输入第三方网页。
• 每个无人值守 loop 必须有预算帽、重试上限和人工审查点。

适用场景

• GitHub PR 初筛与 repo triage。
• Obsidian 教学笔记整理。
• 医学教学资料生成前的材料检查。
• 文献日报或公开网页监控。
• 微信文章生产包的结构化校验。
• 本地工具故障排查的只读报告。

更多示例见 使用场景。

Roadmap

下一步计划见 ROADMAP.md。

来源说明

本项目由本地技术文档 Loop-Engineering-IEEE.pdf 的概念脉络转化而来，内容为原创化整理和工程化模板，不复制原文长段落。核心思想包括四层栈、五动作、六组件、generator/evaluator 分离、反模式与 first-loop checklist。