介绍
# Agent Orchestration 🦞
**作者：Hal Labs** — Hal Stack 的一部分
你的智能体失败是因为你的提示词太烂。这项技能能解决这个问题。
---
## 核心问题
你不是在写提示词。**你在祈祷。**
大多数提示词只是扔进虚空里的愿望：
``` ❌ "Research the best vector databases and write a report" ```
你输入了一些看似合理的内容。输出结果平平。你重新措辞。还是平平。你加了关键词。不知为何变得更糟了。你怪罪模型。
你不明白的是：**语言模型是一个模式补全引擎。** 它根据你的输入生成统计概率最高的输出。
模糊的输入 → 通用的输出。这不是因为模型笨。是因为当你没有给它具体的材料时，通用就是概率最高的结果。
**模型完全响应了你的要求。你只是没有意识到你给得太少了。**
---
## 核心重构
提示词不是请求。**提示词是合约。**
每个合约必须回答四个不可协商的要素：
| 要素 | 问题 | |---------|----------| | **角色** | 模型正在扮演谁？ | | **任务** | 它必须确切完成什么？ | | **约束** | 必须遵循什么规则？ | | **输出** | “完成”看起来是什么样？ |
漏掉一个，模型就会用假设来填补空白。假设正是幻觉诞生的地方。
---
## 五层架构
有效的提示词共享特定的结构。这与模型实际处理信息的方式相吻合。
### 第一层：身份
在这个对话中，模型是谁？
不是“乐于助人的助手”，而是具有特定专业知识的特定角色：
```markdown You are a senior product marketer who specializes in B2B SaaS positioning. You have 15 years of experience converting technical features into emotional benefits. You write in short sentences. You never use jargon without explaining it. ```
模型并不会真的“变成”这个身份——它访问的是不同的训练数据集群、不同的风格模式和不同的推理方法。
**身份很重要。** 错过这一层，你得到的就是通用的输出。
### 第二层：上下文
模型需要知道什么才能出色地完成这项任务？
上下文必须是： - **有序的** — 最重要的在前 - **有范围的** — 仅限相关内容 - **有标签的** — 区分规则、可编辑内容和历史记录
```markdown ## Context
### Rules (never change) - Design system: Tailwind, shadcn components - Voice: Professional but warm, never corporate
### Current State (may evolve) - Landing page exists at /landing - Using Next.js 14 with App Router
### Historical (for reference) - Originally built with Create React App, migrated Jan 2025 ```
**没有标签，模型会将所有内容视为同样可选项。** 然后它会在中途重写你的核心逻辑。
### 第三层：任务
必须采取什么具体行动？
不是“写点关于 X 的东西”，而是精确的指令：
```markdown ## Task Produce a 500-word product description that: - Emphasizes time-saving benefits for busy executives - Opens with the primary pain point - Includes 3 specific use cases - Ends with a clear call to action ```
你定义任务越精确，模型执行得就越精确。
### 第四层：过程 ⚡
**这是大多数提示词失败的地方。**
你在索要输出。你应该索求的是**输出是如何形成的。**
❌ 坏示例： ``` Write me a marketing page. ```
✅ 好示例： ```markdown ## Process 1. First, analyze the target audience and identify their primary pain points 2. Then, define the positioning that addresses those pain points 3. Then, write the page 4. Show your reasoning at each step 5. Do not skip steps 6. Audit your work before reporting done ```
**你不想要答案。你想要的是答案是如何形成的。**
像导演一样思考。你不是在要求一个场景——你是在指导这个场景是如何构建的。
### 第五层：输出
“完成”实际上看起来是什么样？
如果你不指定，你就会得到模型默认的任何格式。
```markdown ## Output Format Return a JSON object with: - `headline`: string (max 60 chars) - `subheadline`: string (max 120 chars) - `body`: string (markdown formatted) - `cta`: string (action verb + benefit)
Do not include explanations, notes, or commentary. Only the JSON. ```
**漏掉一层，结构就会摇晃。漏掉两层，它就会崩塌。**
---
## 模型选择
**提示词可移植性是个神话。**
不同的模型是不同的专家。你不会给你的执行助理、设计师和后端开发完全相同的指令。
| 模型类型 | 最适用于 | 注意事项 | |------------|----------|---------------| | Claude Opus | 复杂推理、细腻写作、长上下文 | 昂贵，可能比较啰嗦 | | Claude Sonnet | 平衡的任务、代码、分析 | 创造力不如 Opus | | GPT-4 | 广泛的知识、结构化输出 | 可能会奉承 | | 较小的模型 | 快速任务、简单查询 | 推理深度有限 |
**针对每个模型调整你的提示词：** - 有些偏好结构化的自然语言 - 有些需要明确的步骤排序 - 有些在冗长的提示词下会崩溃 - 有些除非重复否则会忽略约束 - 有些擅长分析但搞砸创意
**编写特定模型提示词的人，每次都会击败那些有“更好点子”的人。**
---
## 约束即指令
模糊不是灵活。**它是懦弱。**
你模棱两可是因为具体化感觉有风险。但模型不会读心。
**约束不是限制。约束是指令。**
```markdown ## Constraints - Never alter the existing design system - Always maintain the established voice/tone - Never change the data model without explicit approval - Max 3 API calls per operation - If unsure, ask rather than assume ```
每次对话都从零开始。模型并没有积累与你合作时的上下文。**一致性来自指令，而非记忆。**
---
## 规范文档
如果你没有文档，你就是在赌博。
| 文档 | 目的 | |----------|---------| | PRD | 我们在构建什么以及为什么 | | 设计系统 | 视觉规则和组件 | | 约束文档 | 什么绝不能改变 | | 上下文文档 | 当前状态和历史 |
**规则：** 在你的提示词中引用文档。
```markdown The attached PRD is the source of truth. Do not contradict it. The design system in /docs/design.md must be followed exactly. ```
没有明确的锚定，模型会假设一切都是可变的——包括你的核心决策。
> “好的提示词不是写出更好的句子。它是将模型锚定在现实中。”
---
## 完整模板
```markdown ## Identity You are a [specific role] with [specific expertise]. [Behavioral traits and style]
## Context
### Rules (never change) - [Constraint 1] - [Constraint 2]
### Current State - [Relevant background]
### Reference Docs - [Doc 1]: [what it contains] - [Doc 2]: [what it contains]
## Task [Specific, measurable objective]
## Process 1. First, [analysis step] 2. Then, [planning step] 3. Then, [execution step] 4. Finally, [verification step]
Show your reasoning at each step.
## User Stories 1. As [user], I want [goal], so that [benefit] 2. As [user], I want [goal], so that [benefit]
## Output Format [Exact specification of deliverable]
## Constraints - [Limit 1] - [Limit 2] - [What NOT to do]
## Error Handling - If [situation]: [action] - If blocked: [escalation]
## Before Reporting Done 1. Review each user story 2. Verify the output satisfies it 3. If not, iterate until it does 4. Only then report complete ```
---
## Ralph 模式
对于初次尝试经常失败的复杂任务：
```markdown ## Mode: Ralph Keep trying until it works. Don't give up on first failure.
If something breaks: 1. Debug and understand why 2. Try a different approach 3. Research how others solved similar problems 4. Iterate until user stories are satisfied
You have [N] attempts before escalating. ```
**何时使用：** - 包含多个组件的构建任务 - 集成工作 - 任何一次尝试很难成功的任务
---
## 智能体跟踪
**每个生成的智能体都会被跟踪。没有孤儿。**
维护 `notes/areas/active-agents.md`：
```markdown ## Currently Running
| Label | Task | Spawned | Expected | Status | |-------|------|---------|----------|--------| | research-x | Competitor analysis | 9:00 AM | 15m | 🏃 Running |
## Completed Today
| Label | Task | Runtime | Result | |-------|------|---------|--------| | builder-v2 | Dashboard update | 8m | ✅ Complete | ```
**心跳检查：** ``` 1. Run sessions_list --activeMinutes 120 2. Compare to tracking file 3. Investigate any missing/stalled agents 4. Log completions to LEARNINGS.md ```
---
## 学习循环
每个智能体的结果都是数据。捕获它。
维护 `LEARNINGS.md`：
```markdown ## What Works - User stories + acceptance loop - Ralph mode for complex builds - Explicit output formats - Process layer with reasoning steps
## What Doesn't Work - Lazy task dumps - Missing success criteria - No scope limits - Vague constraints
## Experiment Log ### [Date]: [Agent Label] **Approach:** [What you tried] **Outcome:** [What happened] **Lesson:** [What you learned] ```
---
## 角色库
构建可重用的角色定义：
```markdown # Role Library
## Research Analyst You are a senior research analyst with 10 years experience in technology markets. You are thorough but efficient. You cite sources. You distinguish fact from speculation. You present findings in structured formats with clear recommendations.
## Technical Writer You are a technical writer who specializes in developer documentation. You write clearly and concisely. You use examples liberally. You assume the reader is smart but unfamiliar with this specific system.
## Code Reviewer You are a senior engineer conducting code review. You focus on correctness, maintainability, and security. You explain your reasoning. You suggest specific improvements, not vague feedback. ```
---
## 快速参考
### 四个不可协商要素 1. **角色** — 模型是谁？ 2. **任务** — 它必须做什么？ 3. **约束** — 适用什么规则？ 4. **输出** — 完成看起来是什么样？
### 五层架构 1. **身份** — 特定的角色和专业知识 2. **上下文** — 有序、有范围、有标签 3. **任务** — 精确的目标 4. **过程** — 如何处理（最容易被忽视！） 5. **输出** — 精确的格式规范
### 生成前检查清单 - [ ] 分配身份了吗？ - [ ] 上下文打标签了吗（规则/状态/历史）？ - [ ] 任务具体且可衡量吗？ - [ ] 描述过程了吗（不仅仅是输出）？ - [ ] 定义用户故事了吗？ - [ ] 指定输出格式了吗？ - [ ] 约束明确吗？ - [ ] 包含错误处理了吗？ - [ ] 添加到跟踪文件了吗？
---
## 最终真理
“AI 对我不起作用”和卓越结果之间的差距不在于智力或权限。
**一类人把提示词当作对话。另一类人把它当作编写系统指令。**
模型匹配你的严谨程度。
- 模糊的输入 → 通用的输出 - 结构化的输入 → 结构化的输出 - 清晰的思考 → 清晰的结果
你不需要更聪明。你需要更清晰。
**清晰度是一个系统，而不是天赋。**
---
*Hal Stack 的一部分 🦞*
---
**有技能想法？** 邮箱：[email protected]
---
*“你不是在写提示词，你是在祈祷。开始工程设计吧。”*