Agent 文档怎么写：面向 AI 消费的可执行文档编写指南

一、概述

随着 LLM 驱动的 Agent 工具链逐步成熟，文档的消费者从「人类读者」扩展到了「模型读者」。Agent 文档不是给人读的散文，而是给模型解析的结构化指令——每一段话都可能被作为 prompt 上下文、函数描述或工具规约被消费。

本文面向开发者和技术写作者，给出 Agent 文档的编写规范与最佳实践，覆盖：

• 元数据约定（frontmatter）
• 章节结构与命名
• 代码示例的可执行性
• 错误处理与边界条件
• 检索友好的关键词布局

读完本文后，你应该能独立产出一份「既能给人类阅读、也能被 Agent 正确解析」的技术文档。

二、背景

2.1 Agent 读文档的三种方式

2.2 与人类文档的核心差异

• 人类文档：可读性优先，允许比喻、故事、渐进式展开
• Agent 文档：确定性优先——同样的输入必须让模型推导出同样的行为
• 人类文档：「详见下一节」是常见过渡
• Agent 文档：跳转必须用显式锚点，且锚点文本要包含目标关键词

三、实践

3.1 Frontmatter 元数据规范

最小可用集：

---
title: 命令的唯一名称（≤ 60 字符）
description: 一句话说清做什么、面向谁（≤ 160 字符）
date: 'YYYY-MM-DD'
category: 单一分类
tags: [关键词1, 关键词2]
version: 1.0.0      # 文档版本，重要
deprecated: false   # 是否已弃用
---

关键规则：

1. title 必须是「动作 + 对象」结构，不要写「关于 XXX 的思考」
2. description 要回答三件事：做什么、谁用、解决什么问题
3. tags 是检索入口，至少包含 1 个业务关键词 + 1 个技术关键词

3.2 章节结构模板

推荐四段式：

## 一、概述     # 是什么、为什么、谁该读
## 二、背景     # 前置概念、上下文、术语表
## 三、实践     # 核心：示例、配置、API、代码
## 四、总结     # 复盘要点、行动项、延伸阅读

用「一、二、三」而非「1. 2. 3.」，因为中文章节标题在 TOC 中更易识别，模型切分粒度更稳定。

3.3 代码示例：可执行 > 可读

// ✅ 推荐：自包含、可运行、有预期输出
import { defineConfig } from 'vite'

export default defineConfig({
  base: '/my-blog/',
  build: {
    outDir: 'dist',
    sourcemap: true
  }
})

// ❌ 避免：省略关键依赖、留 TODO、引用未定义变量
// see example above  // ← Agent 无法解析

代码块的硬性要求：

3.4 参数与返回值：表格 > 段落

✅ 推荐：

❌ 避免：

path 参数是必填的字符串，表示 Markdown 文件的相对路径。draft 是可选的布尔值，默认是 false，表示是否草稿。tags 是字符串数组。

3.5 错误与边界条件

每个公开 API 都必须覆盖：

• 正常路径：成功时的返回结构
• 异常路径：抛错条件、错误码、错误信息
• 边界条件：空输入、超长输入、并发场景

/**
 * @throws {ValidationError} 当 slug 含非法字符时
 * @throws {NotFoundError} 当文章不存在时
 * @example
 * // 成功
 * getPost('hello-world')
 * // => { title: 'Hello', ... }
 */

3.6 关键词布局：让 Agent 找得到

Agent 检索依赖关键词密度与位置。在文档中显式布局：

1. 首段：出现核心关键词 1-2 次
2. 小标题：包含业务术语
3. 代码注释：标注「为什么」而非「做什么」
4. 末尾总结：用 bullet 形式复述关键概念

3.7 反模式清单

四、总结

Agent 文档的核心是确定性——同样的输入必须让模型推导出同样的行为。围绕这个目标，记牢这五条：

1. 结构化 frontmatter：title + description + tags 必填
2. 章节四段式：概述 / 背景 / 实践 / 总结
3. 代码自包含：可运行、有注释、有预期输出
4. 参数用表格：类型 / 必填 / 默认值 / 说明四列
5. 关键词前置：核心术语出现在首段与小标题

可执行的延伸任务：

• 选一篇旧文档，按本文规范重写 frontmatter
• 把所有「段落式参数说明」改为表格
• 在代码块中补全 // => 形式的预期输出注释

延伸阅读：

• VitePress Markdown 扩展
• OpenAI Function Calling 规范
• Anthropic Tool Use 最佳实践

文章 slug: agent文档怎么写 最后更新: 2026-06-22