海松知道 | 文章

Agentsmd介绍

Mon, 10 Aug 2026 18:33:18 GMT

AGENTS.md介绍

AGENTS.md概述

AGENTS.md 是项目给 Codex 的一份“工作说明书”。
它通常放在仓库根目录或某个子目录中，用来明确说明这个范围内代码的协作规则、实现约束、常见操作方式，以及在执行任务时应优先遵守的工程约定。

在多人协作项目中，人类成员会通过开发规范、目录约定、评审标准来降低沟通成本；而在引入 Codex 后，AGENTS.md 的作用就是把这些隐性经验显式化，让 Codex 在生成代码、修改文件、运行命令和编写文档时，尽量贴合团队的真实工作方式。

TIP

可以把 AGENTS.md 理解成“面向 Codex 的项目内操作手册”。它不是业务代码的一部分，但会直接影响 Codex 的输出质量和执行边界。

问题描述

如果项目没有清晰的 AGENTS.md 约束，Codex 往往只能依据通用经验工作，这会带来几个典型问题：

实现风格不一致
比如项目要求不使用某个框架特性、必须沿用已有分层结构、接口命名需要遵循团队规范，但这些规则如果没有写出来，Codex 就可能给出“能跑但不符合团队习惯”的方案。
容易触碰隐性禁区
例如不能改动某些基础模块、不能直接执行破坏性命令、不能引入新依赖、不能修改数据库结构。如果这些约束只存在于团队口头约定中，Codex 无法稳定遵守。
重复解释成本高
每次都要重新告诉 Codex “这个项目不用 Lombok”“先读文档再改代码”“提交信息必须按某种格式写”，会显著增加交互成本，也不利于批量复用。
结果可控性不足
同样一个任务，不同轮次得到的结果可能差异较大。缺少稳定规则时，Codex 输出会更依赖即时上下文，而不是项目长期约定。

本质上，问题不是 Codex “不会做”，而是项目没有把“应该怎么做”描述清楚。

总体思想

设计 AGENTS.md 的核心思想，不是罗列越多规则越好，而是把最影响结果质量的约束沉淀下来，让 Codex 在执行任务时形成稳定判断。

可以按下面三个层次来组织：

1. 先定义边界

先告诉 Codex 什么能做、什么不能做，例如：

哪些目录可以修改，哪些目录禁止改动
是否允许新增依赖、修改数据库、执行脚本
是否必须先阅读某些文档或接口定义再开始改动

这一步的目标，是先保证“不要做错”。

2. 再定义规则

在边界明确后，再补充项目的具体工程规则，例如：

代码分层和目录约定
命名规范、注释规范、提交规范
测试要求、文档要求、错误处理方式

这一步的目标，是让 Codex “按团队方式做对”。

3. 最后定义优先级

当不同规则发生冲突时，需要明确优先顺序，例如：

先遵守安全和破坏性操作限制
再遵守项目编码规范
最后再考虑生成效率和简洁性

这一步的目标，是让 Codex 在复杂场景下也能稳定决策。

TIP

一个好的 AGENTS.md，重点不是“大而全”，而是“高频、关键、可执行”。优先写那些最容易出错、最影响交付质量、最值得长期复用的规则。

AGENTS.md实践

Mon, 10 Aug 2026 00:00:00 GMT

AGENTS.md实践

相关知识点：“Harness Engineering 里面的“上下文工程（Context Engineering）”

总体原则：保持AGENTS.md简洁，不要超过200行。

AGENTS.md介绍

AGENTS.md分级

组织级（公司或者团队） 放在 ~/.codex/AGENTS.md
    ↓
项目级， 放在 project/AGENTS.md
    ↓
模块级， project/backend/AGENTS.md

组织级 AGENTS.md管理

创建独立的代码仓库 team-ai-agent-guidelines/

├── AGENTS.md
│
├── coding/
│    ├── java.md
│    ├── react.md
│    └── database-design.md
│    └── database-migration.md
├── security/
│    ├── secure-coding.md
│
├── architecture/
│    ├── microservice.md
│
└── templates/
     ├── ADR.md
     ├── Epic.md
     ├── UserStory.md
     └── Task.md

保持AGENTS.md简洁，在AGENTS.md中引用其他文件

# XX团队编码规范
 
## 所有AI开发必须遵循：
 
1. 编码规范
2. 架构规范
3. 安全规范
 
## 编码规范
 
java项目遵循 @coding/java.md
react项目遵循 @coding/react.md
数据库设计遵循 @coding/database-design.md
数据库升级遵循 @coding/database-migration.md
 
## 架构规范
 
微服务设计准许 @architecture/microservice.md
 
## 安全规范
 
安全编码遵循 @security/secure-coding.md
支付安全规范 @security/payment-security.md

项目级引用团队级规范

示例：CRM项目/AGENTS.md

## 引用团队级规范
 
本项目后端遵循团队级java规范 @team-ai-agent-guidelines/coding/java.md
本项目前端遵循团队级react规范 @team-ai-agent-guidelines/coding/react.md
本项目无支付功能，**不遵循**支付安全规范 @security/payment-security.md

项目级AGENTS.md结构

project/
├── AGENTS.md
│
├── docs/
│    ├── AGENTS.md
│    ├── user_stories/
│    └── ADRs/
│
├── backend/
│    ├── AGENTS.md
│    └── tests/
│         └── AGENTS.md
│
├── frontend/
│    ├── AGENTS.md
│    └── tests/
│         └── AGENTS.md

AGENTS.md示例1 - 项目级AGENTS.md

根目录的AGENTS.md

# AGENTS.md
 
## 适用范围
 
本文件适用于当前仓库根目录及全部子目录。
 
## 修改约束
 
- 不要执行破坏性 Git 命令
- 不要随意新增第三方依赖
- 修改前优先阅读 README 和接口定义
 
## 编码规则
 
- 后端保持现有分层结构
- 公共方法命名要与现有风格一致
- 关键逻辑变更后补充最小必要测试
 
## 输出要求
 
- 先说明改动思路，再实施修改
- 输出中明确列出变更文件
- 提交信息使用 Conventional Commits 风格

AGENTS.md示例2 - 模块级AGENTS.md

backend/AGENTS.md

## 适用范围
 
本文件适用于当前仓库backend目录及全部子目录。
 
## 后端
 
必须：
 
- Controller直接引用Service层，Service层引用Repository层，Repository层操作数据库
 
禁止：
 
- Controller直接引用Repository层
 
## Database
 
必须:
 
- 使用数据库结构迁移脚本
 
禁止:
 
- 直接连接生产数据库
- 禁止产生多对多关联，多对多关联必须拆分成一个一对多关联和一个多对一关联，并且关联表必须有业务含义，有自己的主键
 
推荐:
 
- repository pattern

AGENTS.md示例3 - 工作流

处理一项任务

## Scope
 
When receiving a task, follow the workflow below:
 
## Task Execution
 
When receiving a task:
Step 1
Read: TASK.md
 
Step 2
Inspect: related code
 
Step 3
Propose the core design
 
Step 4
Implement
 
Step 5
Test
Run tests, lint checks, and other validations after implementation is complete
 
Step 6
Update task status in `TASK.md`

AI-Agent 工程体系演进路线

Sun, 09 Aug 2026 00:00:00 GMT

AI-Agent 工程体系演进路线

TIP

这些概念是现在很热门的词汇，并不代表有长期的生命力
对待这些概念需要了解，但不能迷信

AI-Agent 工程体系 演进路线重点看五个概念：

Prompt Engineering
Context Engineering
Harness Engineering
Loop Engineering
Graph Engineering

它们是层层递进的关系，而是从“会回答问题”逐步走向“能长期、稳定、可治理地完成复杂软件任务”的演进过程。

TIP

Prompt 解决“怎么说清楚”，Context 解决“知道什么”，Harness 解决“如何工作”，Loop 解决“如何自我修正”，Graph 解决“如何组织多步骤、多角色流转”。

1. 一张图看懂演进路线

Prompt -> Context -> Harness -> Loop
                     |
                     +-> Graph

更准确地说：

Prompt 是起点，负责把任务说清楚。
Context 让 AI 不再只看一句话，而是理解项目背景。
Harness 把 AI 纳入一个可管理的工程系统。
Loop 让 AI 在“执行 -> 验证 -> 修复”中形成闭环。
Graph 不是简单排在最后的一层，而是 AI-Agent 进入复杂协作阶段后，用来描述执行流的关键结构。

2. 第一阶段：Prompt Engineering

核心问题

如何把任务描述清楚，让 AI 一次性给出更高质量的输出？

这是最早期、也是最直观的 AI 使用方式。

普通提示：

帮我写一个用户登录接口

优化后的提示：

你是一名资深 Java 后端工程师。
 
请使用 Spring Boot 3 + MyBatis Plus 实现用户登录接口。
 
要求：
1. 使用 JWT 认证
2. 密码使用 BCrypt 加密
3. 做参数校验
4. 返回统一 Result 结构
5. 增加异常处理

Prompt 工程关注什么

维度	说明
角色	你是谁
任务	要完成什么
约束	不能做什么
上下文	当前任务背景
输出格式	要怎么呈现
示例	参考什么风格

局限性

Prompt 工程可以提升单次回答质量，但有天然边界：

AI 不知道项目历史
AI 不知道之前做过什么
AI 不知道团队规范
AI 不知道当前任务处于什么阶段

所以，当任务从“问一个问题”变成“持续开发一个系统”时，仅靠 Prompt 不够。

3. 第二阶段：Context Engineering

核心问题

如何让 AI 不只是理解一句话，而是理解整个项目环境？

Prompt 是一句指令，Context 是一组工作背景。

例如，在开发一个 CRM 系统时，与其只说：

帮我开发客户跟进模块

不如把这些内容一起交给 AI：

项目结构：
 
docs/
  ├── PRD.md
  ├── ARCHITECTURE.md
  ├── user_stories/
  ├── ADRs/
  └── tasks/
 
backend/
  └── tests/
frontend/
  └── tests/
 
技术栈：
Spring Boot 3
PostgreSQL
Redis
React
 
当前任务：
TASK-023 跟进记录自动提醒

Context 工程解决什么

1. 长期记忆

例如 docs/ADRs/ADR-001-customer-state-machine.md：

ADR-001
 
Title:
客户状态机设计
 
Date:
2026-07-01
 
Decision:
客户状态采用有限状态机。
 
Context:
避免状态判断逻辑分散在多个服务中。

这样 AI 下次回来时，不会重新发明一套方案。

2. 项目知识库

例如 AGENTS.md：

规则：
 
修改数据库必须：
1. 创建 migration
2. 更新 schema
3. 添加测试

这相当于把团队规范变成 AI 可消费的工程规则。

3. 当前任务上下文

例如 docs/tasks/TASK-001.md：

目标：
实现登录
 
输入：
用户名和密码
 
输出：
JWT Token
 
验收：
自动化测试通过

局限性

Context 工程让 AI “知道得更多”，但它仍然往往只是一个被动执行者。

也就是说：

你给什么，它看什么
你问一步，它答一步
它还没有被纳入可持续的软件交付体系

于是就进入下一阶段。

4. 第三阶段：Harness Engineering

核心问题

如何把 AI 从“会做事的模型”升级为“可管理、可验证、可持续协作的工程 Agent”？

Harness 可以理解为“缰绳”或“工作控制系统”。

重点不再是“如何提示 AI”，而是“如何为 AI 设计一个可靠的工作环境”。

Harness 的本质

如果说：

Prompt 像告诉一个新人“你现在做什么”
Context 像把项目资料交给他

那么 Harness 更像是给这个新人配齐：

工作制度
任务流转规则
检查点
状态记录
自动验证机制

一个典型的 Harness 项目

project/
├── AGENTS.md
├── docs/
│   ├── PRD.md
│   ├── ARCHITECTURE.md
│   ├── user_stories/
│   ├── ADRs/
│   └── tasks/
├── backend/
│   └── tests/
├── frontend/
│   └── tests/
├── feature_list.json
├── PROGRESS.md
└── scripts/
    ├── init.sh
    ├── test.sh
    └── run.sh

在 Harness 中，AI 如何工作

读取 AGENTS.md
-> 读取 PRD / user_story / ADR / task
-> 修改代码
-> 执行测试脚本
-> 更新 PROGRESS.md
-> 输出结果

Harness 解决什么

1. 防止 AI“失忆”

依靠：

PROGRESS.md
docs/ADRs/
docs/tasks/

2. 防止 AI“乱改”

依靠：

AGENTS.md
任务约束
自动化测试

3. 支持长期任务

例如一个 CRM 项目持续开发半年，AI 每次回来都可以先读取：

当前状态：
已完成客户管理、联系人管理
 
下一步：
开发销售机会评分

这样它就不是一次性的回答器，而是可持续协作的 Agent。

5. 第四阶段：Loop Engineering

核心问题

如何让 AI 不只是执行任务，而是在反馈中持续修正，直到达到目标？

Loop Engineering 的重点是闭环。

传统开发常常是线性的：

需求 -> 编码 -> 测试 -> 人工检查 -> 发布

Loop 模式则是：

需求
-> AI 规划
-> AI 编码
-> 自动测试
-> 分析失败原因
-> AI 修复
-> 再次测试
-> 直到通过

一个典型示例

任务：

实现用户登录

第一次执行：

写代码

测试返回：

失败
原因：JWT 过期时间配置错误

随后 Agent 继续：

修改代码
重新测试
直到通过

Loop 工程依赖什么

1. 自动测试

mvn test
npm test
pytest

2. 自动反馈

test result
error log
coverage

3. 状态管理

TASK-001
 
status: implementing
test: failed
reason: jwt config error

本质变化

到这一步，AI 不再只是“帮你写代码”，而是开始具备“遇错修正、逐步收敛”的工程行为。

6. Graph Engineering：复杂 Agent 系统的执行结构

为什么 Graph 会出现

当 AI-Agent 的工作流越来越复杂时，流程就不再是简单直线，而更像一张图。

例如“开发 CRM 的退款审批功能”这类任务，真实过程往往是：

需求分析
-> 架构检查
-> 任务拆解
-> 编码
-> 测试
-> 判断是否通过
   |- 通过 -> 提交
   |- 不通过 -> 修复 -> 回到测试

这已经不是单链路，而是多节点、多分支、多回路结构。

Graph 的核心组成

Graph Engineering 把 Agent 工作流表示为：

Node：谁来执行
Edge：下一步去哪里
State：共享状态是什么
Decision：在什么条件下跳转

例如：

PRD 分析 Agent
    ->
任务拆解 Agent
    ->
Coding Agent
    ->
Testing Agent
    ->
pass?
 |- yes -> Review / Merge
 |- no  -> Debug Agent -> 回到 Testing

Graph 和 Harness 的关系

这里最容易混淆。

可以这样理解：

Harness 是外部工程治理系统
Graph 是内部执行流编排结构

也就是说：

Harness 负责规定“AI 应该如何工作”
Graph 负责定义“AI 下一步该由谁做、怎么流转”

关系可以表示为：

Harness
  └── Graph
       └── Loop

这也是为什么 Graph 往往不是单独存在，而是嵌入在 Harness 中，服务于 Loop。

一个 Graph 示例

nodes:
  - name: planner
    agent: requirement-agent
  - name: architect
    agent: architecture-agent
  - name: coder
    agent: coding-agent
  - name: tester
    agent: test-agent
 
edges:
  planner:
    next: architect
  architect:
    next: coder
  coder:
    next: tester
  tester:
    success:
      next: done
    failed:
      next: coder

这个配置本质上就是把“谁先做、失败后回哪一步”显式地工程化了。

7. 五个概念放在一起怎么看

从能力层级看

Prompt Engineering
        ->
Context Engineering
        ->
Harness Engineering
        ->
Loop Engineering
 
Graph Engineering 作为执行流结构，通常嵌入 Harness，并支撑 Loop

从解决的问题看

概念	主要解决的问题	类比
Prompt	怎么把任务说清楚	沟通技巧
Context	怎么让 AI 知道背景	给新人做项目培训
Harness	怎么让 AI 在工程里可靠工作	项目管理体系
Loop	怎么让 AI 自动纠错迭代	持续集成与反馈闭环
Graph	怎么组织多角色、多步骤流转	工作流引擎

从软件公司的类比看

概念	对应公司里的什么
Prompt	领导下达的一条需求
Context	公司的知识库和历史资料
Harness	公司的制度、流程和协作规范
Graph	组织内部的任务流转图
Loop	复盘、质检和改进机制

8. 一个真实的 AI-Agent 工程落地路径

假设开发一个 CRM 系统，可以把整个过程理解为四步升级。

第一步：只有 Prompt

设计客户跟进模块

结果通常是：AI 能给方案，但不了解你的真实项目。

第二步：加入 Context

把这些资料交给 AI：

PRD.md
ARCHITECTURE.md
docs/user_stories/
docs/ADRs/
docs/tasks/

结果是：AI 开始理解业务、架构和历史决策。

第三步：建立 Harness

再加入：

AGENTS.md
feature_list.json
PROGRESS.md
scripts/test.sh

结果是：AI 可以在明确规则下持续开发，而不是一次性回答。

第四步：引入 Loop 和 Graph

此时系统开始形成：

任务拆解
-> 编码
-> 测试
-> 失败分析
-> 修复
-> 回归测试

如果进一步使用多个 Agent 协作，还会变成：

Planner Agent
-> Task Agent
-> Coding Agent
-> Review Agent
-> Test Agent
-> Merge

这时，AI 才真正从“聊天机器人”演进为“软件工程 Agent 系统”。

9. PRD、Feature、TASK、PROGRESS 在这条路线中的位置

这是很多人研究 Harness 时最容易问到的问题。

推荐理解为：

产品需求
-> PRD.md
-> Feature 拆解
-> feature_list.json
-> TASK 拆解
-> Agent 执行 TASK
-> Loop 验证
-> 更新 PROGRESS.md

它们分别承担不同职责：

PRD：描述要做什么
Feature：描述要拆成哪些能力块
TASK：描述当前要执行的具体工作单元
PROGRESS：描述当前做到哪里、下一步做什么

这四者共同构成了 Harness 的核心骨架。

10. 总结：AI-Agent 工程体系真正的竞争点

AI 软件开发的重点是设计出更合适的 AI-Agent 工程体系。

可以把全文收束成五句话：

Prompt 是指令设计
Context 是知识注入
Harness 是工作系统
Loop 是自动反馈闭环
Graph 是执行流编排结构

一个由 Context、Harness、Graph、Loop 共同驱动的可持续 AI-Agent 软件工程系统

ai-agent-graph-engineering

Sun, 09 Aug 2026 00:00:00 GMT

ai-agent-graph-engineering

定义

AI Agent Graph Engineering 不是简单地“把多个 agent 连起来”，而是把一个复杂 agent 系统显式建模为状态图或控制流图：

节点表示可命名的工作单元
边表示状态跃迁或路由规则
图状态表示系统在整个执行过程中的共享上下文
图运行时负责分支、回环、暂停、恢复、并行与持久化

如果说 loop engineering 关注的是“单个闭环如何反复工作”，那么 graph engineering 关注的是“多个闭环、多个阶段、多个角色如何组成一个可治理的整体流程”。

它的核心不是让 agent 更像人，而是让系统结构更像一个可审计、可恢复、可演化的业务流程控制面。

核心结论

1. Graph engineering 解决的是复杂控制流显式化

很多 agent 系统在早期都能靠一个 while 循环或一个大 prompt 勉强工作，但一旦进入真实业务场景，就会出现下面几类需求：

不同条件走不同路径
某些步骤需要重试，某些步骤不能重试
某些节点必须人工审批
某些子任务可以并行
某些状态要持久化，数小时后继续
某些失败要回退到特定节点，而不是整个流程重来

这些需求本质上不是“提示词优化”问题，而是控制流建模问题。Graph engineering 的价值，就是把这些本来藏在 prompt、if-else 和临时代码里的逻辑，提升为显式的系统结构。

2. Graph 比 loop 更适合表达“多阶段、多分支、多角色”

Loop 的基本单位是“做一步，再决定下一步”；Graph 的基本单位是“在多个节点之间做状态跃迁”。

因此：

loop 更像一个局部执行器
graph 更像一个总控调度器

一个成熟的 agent 系统往往不是二选一，而是：

图的每个节点内部可能运行一个 loop
图负责决定这些 loop 何时开始、何时切换、何时暂停、何时汇合

所以可以把 graph engineering 理解为：对 loops 的更高一层编排工程。

3. Graph engineering 的价值不在“多 agent”，而在“显式状态机”

不少人把 graph engineering 等同于 multi-agent orchestration，这只说对了一半。

真正关键的不是 agent 数量，而是流程是否被建模成：

有类型的 state
有命名的 nodes
有明确的 edges
有可解释的 route function
有持久化和恢复点
有可追踪的执行轨迹

即使只有一个 agent，只要它需要经过“检索 -> 判断证据是否足够 -> 不足则再检索 -> 足够则生成 -> 高风险则人工审核 -> 审核后输出”这样的流程，它就已经更适合 graph，而不再只是一个简单 loop。

Graph 的最小工程骨架

一个可落地的 agent graph，至少包含 5 个基本构件：

1. State Schema

这是 graph engineering 的第一性对象。

State 不只是“聊天历史”，而是整个执行系统的共享状态。常见字段包括：

用户输入
当前阶段
中间结果
检索证据
工具输出
风险评分
错误计数
重试次数
审批状态
最终产物

好的 graph 系统里，状态应尽量类型化、字段化，而不是全部塞进自由文本。

2. Nodes

Node 是图中的工作单元。一个 node 最好满足三个特征：

语义独立
输入输出清晰
值得在 trace、审计日志和重试策略里单独出现

一个简单判断标准是：

如果某一步值得被单独观察、单独重试、单独统计或单独审批，它就应该成为一个 node。

3. Edges

Edge 表示节点之间的跃迁关系，通常分成两类：

Unconditional edge：固定流转
Conditional edge：根据当前 state 决定下一跳

真正体现 graph engineering 水平的，通常不是 node 本身，而是 route 逻辑是否明确、稳定、可解释。

4. Runtime

Graph 不是静态图纸，而是一个运行时系统。成熟 runtime 通常要支持：

conditional routing
retries
interrupts
checkpoints
resume
streaming
tracing
parallel fan-out / fan-in

这也是为什么 LangGraph 这类框架的价值主要不在“多一个 DSL”，而在“提供长流程 agent 的控制平面”。

5. Observability

没有可观测性，图只会比 loop 更难调试。

至少应记录：

走过哪些节点
每次路由为什么这样决定
哪些状态字段发生了变化
哪一步失败
为什么重试
人工在哪个点介入
最终在哪个条件下终止

图越复杂，observability 越不是附属品，而是主体设计。

Graph 与 Loop 的关系

最容易混淆的地方，是把 graph 和 loop 写成同一个东西。

更准确的关系应该是：

Loop engineering 解决局部闭环执行
Graph engineering 解决全局结构编排

可以把它们理解成两个层级：

1. Loop 是局部控制单元

例如一个“检索不足就再搜一轮”的 evidence loop，本质上是 loop。

2. Graph 是上层调度结构

例如：

先做问题分类
再进入不同子流程
某条子流程内部执行检索 loop
之后进入风险评估节点
高风险时暂停等待人工审批
审批通过后恢复执行

这整个东西更适合建成 graph。

一句话说：

loop 负责反复做对，graph 负责把不同的“做对方式”组织成系统。

为什么图比链或 DAG 更合适

很多人一开始会用 chain 或普通 workflow，但真实 agent 运行一段时间后会发现不够用。

原因在于 graph 往往同时支持：

回环
条件分支
状态持久化
中断恢复
并行汇合

而普通线性链更适合：

固定顺序
短流程
无需恢复
无需复杂状态跃迁

因此，graph engineering 的关键判断不在于“流程是不是多步”，而在于“流程是否具有复杂状态跃迁特征”。

schema lookup
retrieve evidence
grade evidence
generate draft
validate result
request approval
resume after approval

如果一个步骤对产品行为有意义，它通常就值得成为 node。

2. Route function 保持小而明确

路由逻辑最好只做“状态判断”，不要承担大段业务生成逻辑。

错误做法是：

在 route function 里隐藏复杂 prompt 推理
用大量隐式规则决定下一跳

正确做法是：

先由节点产出结构化判断信号
再由路由器基于该信号做简单选择

Control state：当前节点、重试次数、审批状态、暂停标志、错误码
Domain state：用户请求、证据、摘要、分析结果、最终结论

3. 为路由保留显式字段

不要让路由器去解析一大段自然语言。应该提前写入结构化字段，例如：

risk_level
needs_human_review
evidence_quality
retry_count
task_status

多领域问答
多工单类型处理
多策略执行入口

2. Retry / Repair Pattern

执行后先验证，失败则回到修复节点或重新规划节点。

适合：

SQL 生成
代码修复
检索纠偏

3. HITL Pattern

在高风险节点 interrupt，等待人工输入，再 resume。

适合：

审批
合规
医疗/法律/HR 高风险场景

4. Supervisor Pattern

由一个 supervisor 根据 state 把任务分配给不同 specialist。

适合：

研究、写作、分析、审校分工
多 agent 协作系统

5. Fan-out / Fan-in Pattern

并行跑多个节点，再在 join 节点汇总。

适合：

多来源检索
多候选方案生成
多评分器评估

低层 orchestration runtime
用于 long-running、stateful agents
强项在 durable execution、human-in-the-loop、persistence、streaming 和 tracing

这说明它解决的是图运行时问题，而不是替你决定业务图应该怎么设计。

换句话说：

LangGraph 提供的是控制平面能力
Graph engineering 决定的是你的系统结构是否合理

一个实用判断标准

评估一个 agent graph 是否成熟，可以直接问 8 个问题：

state schema 是否清晰且结构化
每个 node 是否有明确职责
路由规则是否显式可测
是否支持局部重试而非全局重跑
是否支持暂停与恢复
是否能解释任意一次状态跃迁
是否有关键节点的审计轨迹
是否真的比线性流程更合适

如果前 7 项里有 3 项以上回答不清楚，这通常还不是 graph engineering，只是把复杂 if-else 画成了框图。

参考来源

一句话判断

AI agent graph engineering 的本质，是把复杂 agent 系统的状态、节点、分支、暂停、恢复和协作方式显式建模成一个可运行、可追踪、可治理的状态图系统。

ai-agent-loop-engineering

Sun, 09 Aug 2026 00:00:00 GMT

ai-agent-loop-engineering

定义

AI Agent Loop Engineering 不是“把提示词写得更好”，而是把模型放进一个可重复执行、可观测、可终止、可纠错的运行闭环中。

核心对象不再是单次回答，而是整条执行轨迹：

读取当前状态
选择下一步动作
调用工具或执行操作
获取外部反馈
判断是否继续、回退、反思或停止

因此，真正决定 agent 上限的，往往不是模型本身，而是环路外面的工程脚手架：目标定义、工具接口、验证器、上下文管理、记忆系统、预算控制与安全边界。

核心结论

1. Loop 比 Prompt 更接近真实工程对象

Prompt engineering 的关注点是“这一轮怎么说”；loop engineering 的关注点是“下一轮为什么还能继续做对”。

在复杂任务里，单轮输出是否完美并不关键，关键是系统能否：

发现错误
获得外部证据
在下一轮修正策略
在满足完成条件时稳定退出

这也是 ReAct、Reflexion、Plan-and-Execute 这类模式持续有效的原因。

2. 最小可用 agent loop 本质上是 `Observe -> Think -> Act -> Verify`

从工程视角看，一个最小可用 loop 不需要“多智能”，但必须完整：

Observe：读取文件、网页、数据库、测试结果、系统状态
Think：决定当前最值得做的一步
Act：执行工具调用、代码修改、API 请求、消息发送
Verify：通过测试、规则检查、评审器、环境反馈判断结果

没有 Verify 的 loop，本质上不是工程闭环，而是连续猜测。

3. 好的 loop 依赖外部反馈，而不是自我感觉良好

大量资料都指向同一个事实：agent 的自我修正只有在“有真实反馈信号”时才可靠。

ReAct 的价值，在于让 reasoning 和 action 交替进行，并把 observation 重新喂回模型
Reflexion 的价值，不是“让模型自我夸赞”，而是把失败后的外部反馈压缩成可复用经验
Claude Code 团队的 loop 实践，也强调停止条件、可验证目标、技能化检查和明确 turn cap

所以，loop engineering 的第一原则不是“多想一步”，而是“让每一步都能被环境纠偏”。

最小工程骨架

一个可落地的 agent loop，至少应当包含以下构件：

1. Goal

目标必须写成可验证条件，而不是模糊意图。

差的写法：

“优化首页体验”

好的写法：

“将首页 Lighthouse 分数提升到 90 以上，最多尝试 5 轮”
“收集 5 个竞品的价格与来源链接，字段完整后停止”

2. Settings

Settings 是运行前相对稳定的控制面，应与运行时状态分离。通常包括：

system instruction
tool schema
权限边界
预算上限
最大轮数
停止条件
memory 策略
evaluator / verifier 配置

它回答的问题是：这个 agent 被允许如何运行

3. States

States 是 loop 每一轮持续变化的数据面，通常包括：

当前目标进度
本轮观察结果
工具返回值
中间计划
错误记录
当前上下文摘要
历史反思

它回答的问题是：这个 agent 此刻处于什么位置

4. Action Layer

Action 层不应只是“给模型几个函数名”，而应具备：

清晰的输入输出 schema
可机器校验的参数格式
幂等性或重试策略
明确的失败返回
可并行时支持并行

tool design 越含糊，loop 的误差传播越快。

5. Evaluator / Verifier

这是 loop engineering 里最容易被低估、但最关键的一层。

推荐拆成两类：

Verifier：规则型校验，如测试是否通过、JSON 是否合法、页面是否打开成功
Evaluator：质量型判断，如摘要是否完整、方案是否满足约束

常见顺序是：

先用 rule-based check 快速挡掉结构性错误
再用 LLM judge 或独立 critic 判断质量

6. Memory

记忆不应被泛化理解为“把历史全塞回上下文”。

更有效的划分通常是：

Scratchpad：当前任务即时推理轨迹
Working memory：最近几轮关键上下文
Episodic memory：失败经验、反思摘要、过去案例
Long-term memory：稳定规则、知识、偏好、策略模板

真正重要的不是“记得更多”，而是“记住以后真的会改变决策的东西”。

一个通用 loop 模板

while not done:
  observe()
  update_state()
  choose_next_action()
  act()
  verify()
 
  if verified_success:
    done = true
  elif recoverable_failure:
    reflect_and_retry()
  elif budget_exhausted or stop_condition_hit:
    stop()