面向 Agent 工程的结构化技术写作
本节目标
AI Agent 工程师写的文档会被人、脚本和模型共同读取。本节不是教“写得正式”，而是教你让读者能执行、审查和复现：目标清楚，输入输出可检查，命令与证据分开，风险和未验证项不被藏起来。
从读者任务开始
动笔前回答四个问题：
- 谁来读：第一次接触项目的学习者、维护者，还是值班人员？
- 读完要完成什么：理解概念、运行命令、排查故障，还是做决策？
- 允许做什么：只读检查、本地写入、外部 API 调用，还是生产变更？
- 什么算完成：文件生成、测试通过、人工批准，还是指标达到阈值？
如果这些问题没有答案，增加标题和 callout 只会让模糊内容排版得更漂亮。
一篇可执行文档的最小结构
| 部分 | 必须回答 | 常见失败 |
|---|---|---|
| 目标与非目标 | 做什么、不做什么 | 把范围留给读者猜 |
| 前置条件 | 环境、权限、版本如何确认 | 只写“安装 Python” |
| 输入输出契约 | 格式、大小、敏感级别、失败形式 | 只有一个成功样例 |
| 操作步骤 | 当前目录、目的、命令、停止条件 | 复制一串无解释命令 |
| 验证 | 什么证据证明成功 | 把预期输出写成实测 |
| 故障处理 | 现象、原因、诊断、安全恢复 | 只写“重试” |
| 安全边界 | 凭据、隐私、外部副作用 | 示例中出现真实数据 |
| 来源与版本 | 依据、核对日期、易变项 | 用记忆代替当前文档 |
命令、输出与证据分层
以下是教学命令，不是本库实际执行记录：
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt紧接着应写边界：
- 工作目录：示例项目根目录；
- 副作用：创建本地
.venv并安装依赖； - 仓库规则：不得提交
.venv； - 预期：命令退出码为
0； - 实测：本课程未执行，因为没有对应示例项目和依赖文件。
如果实际执行，则另写证据：日期、环境、完整命令、退出码和必要的精简输出。不要用“应该没问题”“已验证可用”代替可复核记录。
占位符要有语法
占位符必须能被读者识别且不会误执行：
<PROJECT_ROOT> 由读者替换的绝对项目目录
<YOUR_API_KEY> 仅说明需要密钥，文档中不得填真实值
example.invalid 保留给文档示例的域名在命令前列出替换规则。不要混用 {path}、YOUR_PATH、xxx 而不解释；也不要把尖括号占位符直接交给 PowerShell，因为 <、> 可能有语法含义。
需要密钥时给 .env.example：
MODEL_API_KEY=replace-with-your-own-key这只是字段模板。真实 .env 应被忽略并受访问控制，示例不能包含可用 token、长度特征或内部地址。
为 Agent 写清输入、指令与工具边界
Markdown 标题和围栏可以帮助人或模型辨认区域：
## 任务
从用户提供的会议文本中提取行动项。
## 不允许
- 不发送邮件；
- 不访问网络；
- 不把文本写入长期存储。
## 用户数据
```text
这里放不可信输入。
```
## 输出契约
返回 `owner`、`action`、`due_date`；无法确定时使用 `null`。但围栏只是表示结构，不是安全边界。不可信输入也可以包含标题、反引号或类似指令；真正的保护来自权限最小化、schema 验证、工具白名单、人工审批和副作用控制。详细方法分别进入 提示词工程、上下文工程 与 Agent 核心。
五类高频文档
README：让人找到正确入口
README 应优先回答项目用途、快速开始、最小示例、目录入口和支持边界。不要把全部设计历史塞进首页；链接到专门文档。
Runbook：让人安全完成操作
运行手册按依赖顺序写步骤，包含停止条件、回滚或安全恢复、验证和升级路径。若操作会发消息、删除数据或产生费用，必须在命令前说明并要求适当确认。
ADR / 设计决策：让选择可追溯
记录背景、约束、候选方案、决定、理由、后果和重新评估条件。不要把“团队决定”写成技术事实；证据不足时明确是判断。
实验记录：让结论可复现
记录假设、数据版本、配置、命令、随机性、指标定义、结果文件和失败尝试。只贴最终分数会隐藏选择偏差和运行条件。
工具契约：让 Agent 不靠猜
对 Tool Calling 或 MCP 工具说明：用途、输入 schema、输出 schema、错误、幂等性、副作用、授权和示例。文档示例不能替代运行时验证。后续见 MCP 与 Agent Skills。
图、表与正文各司其职
- 流程或调用关系：Mermaid。
- 字段、版本或方案对比：表格。
- 依赖顺序：编号列表。
- 因果、边界和取舍：完整段落。
- 必须复制执行的内容：代码围栏。
图中节点不应塞进整段说明，表格也不适合长叙事。视觉结构必须帮助读者回答问题，而不是展示工具熟练度。
证据等级写法
| 表述 | 证据状态 | 合适写法 |
|---|---|---|
| 已执行 | 有命令、环境、时间和结果 | “在 Python 3.11.9 下运行 12 项测试，退出码 0” |
| 官方事实 | 有当前一手来源 | “官方文档截至核对日说明……” |
| 工程建议 | 基于约束的选择 | “本项目建议使用完整路径链接，因为同名入口很多” |
| 合理推断 | 证据不完整 | “根据日志只能推断超时发生在请求阶段” |
| 未知 | 尚未检查 | “未在 Obsidian Reading View 验证” |
精确表述通常比绝对表述更可信。不要把“当前测试通过”写成“永远不会失败”，也不要把单个平台行为推广到所有 Markdown 渲染器。
评审一篇 Agent 工程文档
按以下顺序审查：
- 范围：标题和第一屏能否说清任务与非目标？
- 可执行性：初学者能否知道从哪个目录、以什么权限运行？
- 契约：输入、输出、失败和副作用是否可检查？
- 证据：实测、预期、建议和未知是否分开？
- 安全：是否泄露凭据，是否隐藏外部写入、费用或审批？
- 导航：所有活动链接是否真实、明确且无歧义？
- 维护：版本、来源、变更与重新核对条件是否存在？
- 渲染：源文本、目标阅读视图和导出环境是否分别抽查？
先修错误和缺失，再做措辞与样式优化。
动手练习：写一页工具说明
为虚构的 extract_actions 工具写一页说明：
- 输入：不可信的本地会议文本；
- 输出：行动项 JSON；
- 限制：不联网、不发送、不长期保存；
- 错误：空输入、超长输入、无法解析日期；
- 副作用：无；
- 人工确认：输出只是草稿。
必须包含目标/非目标、输入输出表、一个成功示例、两个失败示例、安全 warning、自测问题和来源日期。交换给另一位读者，让对方只看文档回答“工具会不会发邮件、何时返回错误、输出能否直接执行”。答不出来就继续修订。
常见误区
- 只写 happy path：真实维护成本通常在错误和恢复路径。
- 把全部细节放一个表格：长步骤和理由会失去层级。
- 用“显然”“简单”跳过前置知识：初学者无法补全隐含步骤。
- Markdown 分区等于 prompt 安全：结构化显示不能替代权限控制。
- 复制日志越多证据越强：应保留必要证据并去除敏感信息和噪声。
- 来源链接存在就永远准确：动态技术要记录核对日期和适用版本。
自测与掌握标准
- 什么让运行手册“可执行”而不仅是“可读”？
- 占位符为什么要定义替换规则？
- Markdown 围栏为何不是安全边界？
- 实测、官方事实、工程建议和推断应如何区分？
- README、runbook、ADR、实验记录和工具契约各解决什么问题？
- 能为初学者写出目标、前置条件、步骤、验证和故障处理。
- 能定义输入输出、失败、副作用和审批边界。
- 能在文档中明确区分预期与实测。
- 能审查活动链接、凭据、版本与未验证项。
上一节：Properties、Callouts 与可复用笔记。
下一节：综合写作练习与 Mermaid 排错。
参考资料
核对日期：2026-07-14。