Agent Markdown 编写指南：从大模型理解机制出发
- [Agent Markdown 编写指南：从大模型理解机制出发](#Agent Markdown 编写指南：从大模型理解机制出发)
-
- [1. 首先要理解：Markdown 不是给人看的，而是给大模型建立"上下文"](#1. 首先要理解：Markdown 不是给人看的，而是给大模型建立“上下文”)
- [2. 为什么推荐使用 Markdown？](#2. 为什么推荐使用 Markdown？)
- [3. 一个标准 Agent Markdown 应包含哪些部分？](#3. 一个标准 Agent Markdown 应包含哪些部分？)
-
- （1）Role（角色定义）
- （2）Goal（目标定义）
- （3）Task（任务拆解）
- （4）Constraints（约束条件）
- （5）Knowledge（知识来源）
- [（6）Output Format（输出格式）](#（6）Output Format（输出格式）)
- [（7）Examples（Few-shot 示例）](#（7）Examples（Few-shot 示例）)
- 为什么？
- [4. 为什么不要把所有要求写成一大段文字？](#4. 为什么不要把所有要求写成一大段文字？)
- [5. Agent Markdown 编写中的常见误区](#5. Agent Markdown 编写中的常见误区)
- [6. 企业级 Agent Markdown 推荐模板](#6. 企业级 Agent Markdown 推荐模板)
- [7. 核心原则总结](#7. 核心原则总结)
- [8. 相关文档](#8. 相关文档)
Agent Markdown 编写指南：从大模型理解机制出发
1. 首先要理解：Markdown 不是给人看的，而是给大模型建立"上下文"
很多开发者认为 Prompt 就是"写一段描述"。
实际上，对于大模型来说，一个 Markdown 文件承担的是 构建 Context（上下文） 的作用，它决定了模型如何理解自己的身份、任务、边界、输出格式和决策逻辑。
可以把大模型看成一个"没有长期人格、只有当前上下文记忆"的系统：
┌─────────────────────────────┐
│ System Prompt │ ← Markdown 内容
├─────────────────────────────┤
│ Conversation History │
├─────────────────────────────┤
│ User Question │
├─────────────────────────────┤
│ Retrieved Knowledge │
├─────────────────────────────┤
│ Tool Call Results │
└─────────────────────────────┘
│
▼
LLM 基于全部上下文推理因此，一个优秀的 Agent Markdown，本质上是在塑造模型的推理空间。
2. 为什么推荐使用 Markdown？
Markdown 天然具有层级结构，而 Transformer 模型对结构化文本的理解能力明显优于无结构的长文本。
例如：
text
你是客服，你要回答问题，你不能编造答案，你需要引用知识库，你回答要简洁。相比之下：
markdown
# Role
你是一名客服机器人。
# Goal
回答用户提出的问题。
# Constraints
- 不允许编造事实。
- 优先依据知识库回答。
- 信息不足时明确说明。
# Style
- 回答简洁。
- 使用礼貌语言。第二种方式的优势在于：
- 信息边界更清晰。
- 不同语义块不会互相干扰。
- 模型更容易定位约束条件。
- 后续维护成本更低。
3. 一个标准 Agent Markdown 应包含哪些部分？
（1）Role（角色定义）
告诉模型"你是谁"。
markdown
# Role
你是一名金融投资顾问。为什么？
如果没有角色定义，模型只能依据预训练知识猜测自己的身份，容易出现风格漂移。
例如：
用户：帮我分析基金。没有 Role：
"作为 AI，我可以简单介绍......"
有 Role：
"作为专业投资顾问，我将从风险等级、历史收益和资产配置角度分析......"
角色实际上决定了模型激活哪些知识模式。
（2）Goal（目标定义）
告诉模型"最终要完成什么"。
markdown
# Goal
帮助用户制定合理的储蓄计划，并生成可执行方案。为什么？
LLM 本身没有目标函数。
如果目标不明确，模型可能：
- 解释概念；
- 介绍背景；
- 给建议；
- 聊天。
而不是完成真正需要的任务。
（3）Task（任务拆解）
复杂任务最好拆分。
例如：
markdown
# Workflow
1. 理解用户需求。
2. 判断缺失信息。
3. 必要时提出澄清问题。
4. 制定方案。
5. 输出总结。为什么？
LLM 天然擅长 Chain of Thought（逐步推理）。
明确步骤可以降低遗漏，提高稳定性。
（4）Constraints（约束条件）
告诉模型哪些事情绝对不能做。
例如：
markdown
# Constraints
- 不允许编造数据。
- 不允许假设用户年龄。
- 信息不足时主动询问。
- 不输出未经验证的结论。为什么？
模型默认倾向于"尽量回答"。
因此会出现：
用户：帮我分析今年收益。不知道数据时：
❌ 模型可能编造数字。
加入约束后：
✅ "目前缺少收益数据，请提供后再分析。"
这就是减少 Hallucination（幻觉）的重要方法。
（5）Knowledge（知识来源）
指定模型优先参考的信息。
markdown
# Knowledge Priority
1. 当前提供的数据。
2. 检索结果。
3. 系统规则。
4. 通用知识。为什么？
避免模型优先调用参数知识而忽略实时数据。
（6）Output Format（输出格式）
规定输出模板。
例如：
markdown
# Output Format
## 结论
一句话总结。
## 原因分析
- 原因一
- 原因二
## 建议
1.
2.
3.为什么？
LLM 是生成模型，不限制格式就可能每次输出不同结构。
固定模板能够：
- 方便前端解析；
- 提高一致性；
- 方便自动评测。
（7）Examples（Few-shot 示例）
例如：
markdown
## Example
用户：
制定每月存钱计划。
助手：
请提供：
- 月收入
- 月支出
- 储蓄目标为什么？
示例学习（In-Context Learning）是 LLM 最强能力之一。
相比规则描述，模型往往更容易"模仿示例"。
4. 为什么不要把所有要求写成一大段文字？
例如：
你是一个智能助手，需要专业、严谨、不能编造事实、输出 JSON、保持礼貌、先分析后回答、不能回答政治问题......这种写法的问题：
- 信息密度过高；
- 不同约束容易冲突；
- 后续修改困难；
- 模型注意力容易分散。
推荐拆分：
markdown
# Role
...
# Constraints
...
# Safety
...
# Output
...
# Examples
...这种模块化设计更符合 Transformer 对结构化上下文的处理特点。
5. Agent Markdown 编写中的常见误区
| 误区 | 表现 | 后果 | 推荐做法 |
|---|---|---|---|
| 身份定义不清 | "你是 AI 助手" | 风格不稳定 | 明确专业角色和职责 |
| 目标模糊 | "帮助用户" | 输出发散 | 定义具体可执行目标 |
| 没有边界 | 未限制编造或猜测 | 容易产生幻觉 | 增加明确约束 |
| 输出格式自由 | 每次格式不同 | 难以解析 | 提供固定模板 |
| 缺少示例 | 仅靠文字说明 | 行为不稳定 | 增加 Few-shot 示例 |
| Prompt 过长且无层次 | 信息混杂 | 理解效率下降 | 使用 Markdown 分块组织 |
| 一次放入过多规则 | 多条规则冲突 | 模型优先级混乱 | 分层组织并标注优先级 |
6. 企业级 Agent Markdown 推荐模板
markdown
# Role
定义 Agent 的身份、专业领域和职责。
# Goal
说明最终要完成的业务目标。
# Workflow
1. 理解用户需求。
2. 判断信息是否充分。
3. 必要时提出澄清问题。
4. 执行任务。
5. 输出结果。
# Constraints
- 不编造事实。
- 信息不足时说明原因。
- 不泄露敏感信息。
- 遵守业务规则。
# Knowledge Priority
1. 当前上下文
2. 检索知识
3. 工具返回结果
4. 通用知识
# Output Format
定义固定输出结构或数据格式。
# Examples
提供 2～5 个典型输入输出示例。
# Exception Handling
说明异常场景的处理方式，例如：
- 无法完成任务时如何反馈；
- 工具调用失败时如何降级；
- 用户信息不足时如何引导补充。7. 核心原则总结
从大模型理解机制来看，一个优秀的 Agent Markdown 并不是"写得越多越好"，而是要以结构化方式降低模型理解成本、明确推理目标和约束边界。实践中可以归纳为以下几个原则：
- 角色明确（Role）：让模型知道"自己是谁"，避免行为和语气漂移。
- 目标清晰（Goal）：定义需要完成的具体任务，而不是泛泛描述。
- 流程可执行（Workflow）：将复杂任务拆解为步骤，引导稳定推理。
- 约束可验证（Constraints）：明确禁止事项和处理边界，减少幻觉和错误推断。
- 输出可预期（Output Format）：统一回答结构，便于系统集成和自动解析。
- 示例驱动（Examples）：通过 Few-shot 示例强化模型行为，比单纯规则描述更有效。
- 模块化组织（Markdown 分层）：利用标题、列表和分区组织信息，提升模型对上下文的检索和理解效率。
对于企业级智能体开发而言，可以进一步概括为一句话：
Prompt Engineering 的本质不是"教模型回答问题"，而是通过结构化上下文设计，为模型建立稳定、可控、可预测的推理环境。