# Agent Spec：如何用自然语言定义一个可执行系统

作者：Hex4C59 · 发布于 2026-04-04

原文：https://hex4c59.cc/agent/agent-spec-design/


如果你会写简单的循环和条件判断，也写过提示词（Prompt），可以把 Agent Spec 理解为一份任务规范：它告诉 Agent 要完成什么、按什么步骤做、遇到什么情况重试，以及何时停止。

本文以整理文档为例，说明怎样把这些要求写进自然语言指令。这里的“可执行系统”指模型与运行程序按规范共同完成任务；规范本身不会自动执行工具、保存状态或强制停止循环。

---

## 先给结论

1. **Agent Spec 用自然语言约定任务如何执行。** 它写清当前做到哪一步、下一步由什么条件决定，作用类似状态机中的状态与转移规则。状态机就是把“当前阶段”和“允许进入的下一阶段”明确列出来。
2. **本文用 6 个方面检查规范是否完整：** 目标（Goal）、工作流（Workflow）、迭代机制（Iteration）、约束规则（Rules）、拆解能力（Decomposition）与输出规范（Output Contract）。简单任务可以不需要循环或拆分，但应明确这一点。
3. **循环需要终止条件。** 只要求“继续改进”，却不说明何时停，Agent 就可能重复修改或推翻已有结果。轮数上限能限制执行次数，不能保证每轮判断都正确。
4. **设计时可以沿用程序化思维：** 拆出步骤，写明判断和循环条件，限制允许的操作，再规定输出结构。

---

## Agent Spec 的 6 大核心组件

下面按六个方面检查一份 Agent Spec。每一项都应让执行者知道自己要做什么，也让调用方知道如何验收：

### 1. Goal（目标）

定义任务"最终要达成什么"。
好的目标必须是**可验证**的，并且有明确的**终态**（done condition）。

**常见的错误写法（太模糊）：**
```text
帮我优化一下这些文档
```

**工程化的写法：**
```text
将输入的散乱文档集合，重构为结构清晰、命名规范统一的工程文档体系，包含功能说明、API 接口和部署指南三部分。
```

### 2. Workflow（工作流）

工作流定义任务“怎么做”：把处理过程排成有先后关系的步骤，前一步的结果供后一步使用。这样的连续处理也叫 pipeline（流水线）。

一个清晰的 workflow 可能长这样：
`遍历 → 分析 → 修改 → 迭代 → 输出`

每一步都要说明**处理什么、做什么、产生什么结果**。例如“分析”应交代分析哪些文档、找哪些问题，否则模型仍要猜测你的要求。

### 3. Loop / Iteration（迭代机制）

这里要回答：系统是否需要根据上一步的结果，再做一次审查或修改？如果需要，就要把重复执行的规则写出来。

你必须在 Spec 中定义：
- 是否需要循环？
- 循环的条件是什么？
- 终止条件（收敛机制）是什么？

例如：
```text
重复审查和优化文档内容，直到无法提出实质性改进或经过 3 轮优化为止。
```
这条指令同时给出内容标准和次数上限：没有实质改进时提前结束，否则最多做三轮。运行程序还需记录轮数并执行停止规则，不能只依赖模型自行记住上限。

### 4. Rules / Constraints（约束规则）

约束规则说明允许怎样处理任务，以及哪些操作不能做。主要包括：

- **风格约束**：使用工程化语言，保持简洁。
- **行为约束**：如果判断条件满足，直接执行无需反复确认。
- **安全约束**：不允许覆盖未备份的原始数据。

### 5. Decomposition（拆解能力）

输入较多或任务包含不同类型的工作时，可以拆成较小单元逐个处理。拆分后仍需说明各部分如何合并，否则局部修改可能互相冲突。规范需要交代：
- 如何拆任务
- 如何拆文档
- 如何拆模块

### 6. Output Contract（输出规范）

如果后续程序要读取结果，就需要约定输出格式，例如 JSON 字段或 Markdown 结构。这就是 Output Contract：输出方和接收方共同遵守的格式要求。模型若返回一段自由文本，接收方可能找不到所需字段，因而无法继续处理。

假设任务是整理前面提到的文档，规范可以要求按功能说明、API 接口和部署指南分组；每组先检查命名，再修改内容，最后按约定目录输出。若某轮仍发现问题，但已达到三轮上限，就停止并报告未解决项。这样，目标、步骤、循环和输出便对应到同一个任务。

---

## 编排工作流的 4 步设计法

在编写 Agent Spec 时，可以遵循这个实用的"4步法"：

### Step 1：把任务"程序化"

在写每一段描述时，先问自己：**如果这是代码，我会怎么写？**

当你脑海中有了类似这样的伪代码：
```python
for file in folder:
    optimize(file)
    while can_improve:
        refine(file)
```
再把这段逻辑翻译成严谨的自然语言指令。

### Step 2：加入"智能体能力"

在流程中写明哪些情况需要判断，以及判断后分别执行什么：
- 增加判断条件（if）
- 控制循环流（while）
- 细化任务拆分（split）
- 引入思考空间（decide）

### Step 3：加入约束（防止失控）

补齐各种边界情况的防御：
- "当遇到未知术语时，不要自行编造，应保持原文标注。"
- "命名必须遵守驼峰规范。"
- "输出过程中不要产生解释性废话。"

### Step 4：定义终止条件

补齐终止条件：达到验收标准时结束；仍未达到标准但已用完轮数或预算时，也要停止，并说明剩余问题。这里的“收敛”就是让重复执行最终停在一个可检查的结果上。

---

## Agent Spec 通用模板

下面的模板汇总了前面六项要求。按任务填写，删去确实不需要的部分：

```text
# Goal
<定义最终目标，必须有明确终态>

# Workflow
1. <可执行步骤 1>
2. <可执行步骤 2>
...

# Iteration
- 循环执行 <某步骤>
- 直到满足：
  <明确的终止条件>

# Decomposition
- 当满足以下条件时拆分：
  <拆分规则>
- 对拆分后的单元重复执行本流程

# Rules
- <约束准则 1>
- <约束准则 2>

# Naming / Structure (optional)
- <命名规范要求>
- <目录/输出结构规范>

# Output Contract
最终输出必须满足：
- <条件 1>
- <条件 2>
- <格式定义，如 JSON Schema>
```

---

## 设计质量的 5 个评判标准

写完一个 Agent Spec 后，试着用这 5 个维度来评判它是否优秀：

1. **可执行性（Executable）**：指令是不是悬在空中的？能不能直接按步骤跑下来（甚至是由人脑对照模拟执行）？
2. **收敛性（Convergence）**：循环是否有可检查的停止条件和次数上限？停止时能否说明哪些要求已经满足、哪些仍未满足？
3. **可控性（Controllability）**：它会不会乱改不该改的数据？有没有输出无法解析的内容？
4. **可扩展性（Scalability）**：如果以后要加新规则，能不能在当前的流程结构中平滑插入？
5. **可组合性（Composable）**：其他任务能否按约定提供输入并使用结果？如果要把它交给多 Agent 系统中的一个执行者，就需要清楚的输入要求和输出格式。

---

## 绝不能犯的错误

下面这些缺口会让执行过程难以控制：

- ❌ **没有终止条件**：AI 可能会陷入自我推翻的死循环，一直改下去。
- ❌ **目标太模糊**：执行者不知道什么结果算完成，调用方也难以验收。
- ❌ **全开放无约束**：模型可能处理不该修改的内容，或返回后续程序无法使用的结果。
- ❌ **将一次性任务包装为 Agent**：如果一次提示就能完成任务，也不需要保存进度或根据结果决定下一步，就没有必要增加循环和调度逻辑。
- ❌ **缺乏输出结构设计**：导致下游系统无法对接使用。

---

## 进阶：你可以做得更远

把目标、判断、循环和验收写清楚后，你就在设计 Agent 的工作流程了。下面是本文用来区分工作内容的示意分层，并非通用能力评级：

| Level | 能力定位 |
| ----- | ------------------ |
| L1    | 普通问答使用 |
| L2    | Prompt Engineering (提示词工程师) |
| L3    | **Agent Spec 设计 (当前层级)** |
| L4    | Multi-Agent 架构 |
| L5    | Autonomous 甚至通用认知系统 |

下一步，可以把这份 Spec 转成 Python Agent 脚本，例如用 LangChain 或自行编写的运行循环来执行。先让程序实际记录进度、检查输出并限制轮数，再考虑把子任务交给多个 Agent。若要加入自动评分，也需要先说明评分依据：它检查的是格式、事实还是任务完成情况，以及评分结果会触发重试还是停止。

---

*上一篇：[Human-in-the-Loop：Agent 什么时候应该停下来问你](https://hex4c59.cc/agent/human-in-the-loop/)*