智能体编排 🦞

作者：Hal Labs——Hal技术栈的组成部分

你的智能体表现不佳，是因为你的提示词太糟糕。这项技能将解决这个问题。

核心问题

你这不是在写提示词。你这是在许愿。

大多数提示词都像是扔进虚空里的愿望：

❌ "Research the best vector databases and write a report"

你输入了一些合理的内容。输出结果平平无奇。你换个说法重新表述。还是平平无奇。你添加关键词。结果反而更糟。于是你责怪模型。

你其实没明白的是：语言模型是一个模式补全引擎。它会根据你的输入，生成统计学上最可能的输出。

模糊的输入 → 泛泛的输出。不是因为模型笨，而是因为当你没有给它任何具体信息时，泛泛而谈就是最可能的结果。

模型完全按照你的要求执行了。你只是没意识到自己给的信息有多么贫乏。

核心重构

提示词不是请求。提示词是契约。

每份契约都必须回答四个不容妥协的问题：

漏掉一个，模型就会用假设来填补空白。幻觉正是从这些假设中诞生的。

五层架构

有效的提示词共享一个特定的结构。这与模型实际处理信息的方式相对应。

第一层：身份

模型在这次对话中是谁？

不是"乐于助人的助手"，而是一个拥有特定专业知识的特定角色：

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.

模型并不会"变成"这个身份——它会访问不同的训练数据集群、不同的风格模式、不同的推理方法。

身份很重要。如果忽略了这一点，你得到的将是通用输出。

第二层：上下文

模型需要掌握哪些知识才能出色完成这项任务？

上下文必须：

• 有序排列——最重要的信息优先
• 范围明确——仅包含相关内容
• 标注清晰——区分规则内容、可编辑内容和历史记录

## 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的内容"，而应是精确指令：

## 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.

✅ 优秀示范：

## 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

你需要的不是答案本身，而是答案的生成逻辑。

像导演一样思考。你不是在索要一个场景——你是在指导这个场景如何构建。

第5层：输出

"完成"到底是什么样子？

如果你不指定，你就会得到模型默认的任何格式。

## 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.

缺失一层，结构就会摇晃。缺失两层，它就会坍塌。

模型选择

提示词的可移植性是个神话。

不同的模型是不同的专家。你不会给你的执行助理、设计师和后端开发人员完全相同的指令。

根据模型调整你的提示词：

• 有些偏好结构化的自然语言
• 有些需要明确的步骤序列
• 有些会在冗长提示下崩溃
• 有些会忽略约束，除非反复强调
• 有些擅长分析但缺乏创造力

掌握模型特定提示词的人，每次都会胜过只有"更好想法"的人

约束即指令

模糊不是灵活性而是怯懦

你含糊其辞是因为具体表达感觉有风险。但模型不会读心

约束不是限制。约束是指令

## 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

每次对话都从零开始。模型没有与你合作积累的上下文一致性来自指令，而非记忆

规范文档

如果没有文档，你就是在赌博。

规则是：在你的提示中引用文档。

The attached PRD is the source of truth. Do not contradict it.
The design system in /docs/design.md must be followed exactly.

若没有明确的锚定，模型会假定一切都是可变的——包括你的核心决策。

“好的提示并非写出更好的句子，而是将模型锚定在现实中。”

完整模板

## 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

拉尔夫模式

适用于首次尝试常会失败的复杂任务：

## 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文件：

## 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文件：

## 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]

角色库

构建可重用的角色定义：

# 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 的一部分 🦞

有技能想法？邮箱：halthelobster@protonmail.com

“你不是在提示，你是在祈祷。开始工程化吧。”