49.1 为什么写作是 FDE 的核心能力

在大多数工程师的直觉里，"硬核能力"是写代码、调模型、压性能。但对 FDE（前沿部署工程师）而言，写作与文档能力是与编码同等——甚至在某些阶段更高——的核心能力。这不是修辞，而是由 FDE 的工作场景决定的。

FDE 的典型工作链条是：进入陌生客户现场 → 快速理解业务 → 把模糊痛点翻译成可执行方案 → 现场交付 → 把成果移交客户自运转。在这条链条上，几乎每一个节点的核心产出物都是文档，而不是代码。具体看四个场景：

第一，沟通靠文档。FDE 面对的读者极为异质：客户的 CXO 关心 ROI 和风险，业务部门关心流程是否被改变，IT 部门关心集成与运维，一线员工关心会不会被替代。一个 FDE 不可能把同一套说辞讲给所有人听。口头沟通一次只能覆盖几个人，且无法留痕；只有写成针对不同读者的文档，才能让信息在客户组织内部自传播。Palantir 的 FDE 传统里，"让客户内部某个人能把你的方案复述给他的老板"是项目能否存续的关键，而这几乎只可能通过一份写得好的方案文档实现。

第二，留痕靠文档。客户项目周期通常以月或年计，人员会变动——客户方的对接人调岗、FDE 自己轮换、供应商更换。如果没有可追溯的文档，三个月后没人能说清"为什么当时选了 A 不选 B""这个参数为什么是 0.7"。这类知识缺口轻则返工，重则在出问题时互相甩锅。FDE 的职业声誉很大程度上建立在"我经手的项目都有据可查"上。

第三，转移靠文档。FDE 的终极目标不是自己长期驻场，而是把系统能力和操作知识转移给客户，让客户自运转。这个转移过程的载体就是交付文档、运维手册、培训材料。一份连客户 IT 都看不懂的运维手册，等于把项目判了死刑——上线三个月后没人会重启服务、没人会换密钥、没人会处理告警。

第四，复用靠文档。FDE 跨行业、跨客户作业，今天做制造、明天做零售。每个行业的方法论沉淀、坑位记录、模板复用，都依赖文档。一个成熟的 FDE 个人知识库，往往就是几十份结构化的勘探报告、方案模板、ADR（架构决策记录）和案例笔记。这些文档是 FDE 个人资本的复利来源。

一句话：FDE 的代码决定项目能不能跑起来，FDE 的文档决定项目能不能活下去、能不能被复用、能不能在 FDE 离开后继续产生价值。

49.2 FDE 必备的九类文档

下表是 FDE 全流程交付中高频出现的九类文档，对应 CDEF 方法论的不同阶段。每一类都有明确的读者、产出时机和核心字段，下一节给出模板。

序号	文档类型	对应 CDEF 阶段	主要读者	核心产出时机
1	勘探报告（Discovery Report）	Context 勘探	CXO + 业务负责人	进场 1–2 周内
2	方案设计书（Solution Design）	Design 设计	技术 + 业务 + CXO	PoC 启动前
3	架构决策记录（ADR）	Design / Engineer	技术团队 + 后续维护者	每个关键决策点
4	周报（Weekly Status）	全程	客户项目经理 + 内部	每周固定时间
5	交付文档（Delivery Doc）	Engineer 工程	客户 IT + 接收方	上线前验收
6	运维手册（Runbook / Ops Manual）	Engineer / Feedback	客户运维 + 一线	上线时同步交付
7	培训材料（Training Material）	Feedback 反馈	客户一线员工	灰度推广阶段
8	案例沉淀（Case Study / Postmortem）	Feedback 反馈	内部知识库 + 外部营销	项目里程碑后
9	README（项目入口文档）	Engineer	任何接手代码的人	代码仓库创建即写

49.3 各类文档的模板与要点

49.3.1 勘探报告（Discovery Report）

勘探报告是 FDE 进场后的第一份正式产出，决定后续方案方向。它的核心任务不是"记录客户说了什么"，而是"结构化地呈现客户现状、痛点、约束，并给出可落地的切入点"。

模板骨架：

# [客户名] [业务域] AI 落地勘探报告
编号：DR-2026-018  版本：v1.0  日期：2026-06-15  作者：[FDE 姓名]

## 1. 勘探背景与范围
- 客户委托来源、本次勘探的业务域边界、不在范围内的事项

## 2. 客户现状（事实层）
- 组织结构（对接的关键角色及其 KPI）
- 现有系统与数据资产（系统清单、数据量、数据质量初判）
- 现有流程（用流程图或时间线呈现关键业务流）

## 3. 痛点清单（按优先级）
| 编号 | 痛点描述 | 影响范围 | 量化损失（若有） | 业务方原话 |

## 4. 约束条件
- 预算 / 时间 / 合规（数据出境、行业监管）/ 组织政治

## 5. 切入点建议
- 推荐 1–3 个 PoC 方向，每个给出：预期效果、技术可行性、数据就绪度、风险

## 6. 下一步动作
- 明确的 next steps，含负责人与截止日期

## 附录：访谈记录索引、数据样本说明

要点： 第 2 节必须用事实，不用形容词；第 3 节每条痛点要能追溯到一次访谈或一份数据；第 5 节的切入点必须可执行，不能停在"建议进一步研究"。

49.3.2 方案设计书（Solution Design）

方案设计书是 PoC 或正式项目启动前的核心文档，读者跨度最大。好的方案设计书通常拆成"执行摘要 + 技术详述"两部分，让 CXO 只读前两页就能决策。

模板骨架：

# [客户名] [项目名] 方案设计书
编号：SD-2026-018  版本：v2.1  关联勘探报告：DR-2026-018

## 执行摘要（给 CXO，≤2 页）
- 业务目标（一句话）
- 预期收益（量化，如"客服首响时间下降 40%"）
- 总投入（人月 / 许可 / 硬件）
- 主要风险与应对

## 1. 业务背景与目标
## 2. 总体架构（含架构图）
## 3. 功能模块分解
## 4. 数据流与数据治理
## 5. 技术选型与理由（引用对应 ADR）
## 6. 部署与集成方案
## 7. 安全与合规
## 8. 里程碑与验收标准
## 9. 风险登记（引用 RSK 编号）
## 附录：接口契约、数据字典、术语表

49.3.3 架构决策记录（ADR）

ADR 是 FDE 工具箱里性价比最高的一种文档。它不写"系统是什么样的"，只写"为什么我们做了一个决策"。Michael Nygard 提出的 ADR 格式已被广泛采用，FDE 应在每个关键决策点（选模型、选数据库、选集成方式、定阈值）写一条。

模板（轻量版）：

# ADR-014：选型向量数据库选用 Milvus 而非 Pinecone

状态：已接受  日期：2026-06-10  决策者：[FDE]、[客户架构师]

## 背景
本项目需要在客户私有化环境部署 RAG 系统，数据不可出内网。

## 决策
选用 Milvus 2.4 自建集群，3 节点，HNSW 索引。

## 理由
1. 私有化硬约束排除 SaaS 类（Pinecone、Weaviate Cloud）；
2. 客户已有 Kubernetes 运维能力，Milvus 部署成本低；
3. 性能基准测试（附录）显示在 1000 万向量规模下 p95 延迟 23ms，满足业务。

## 后果
- 需自维集群，运维成本增加约 0.3 人月/月；
- 牺牲了 Pinecone 的托管扩容能力；
- 未来若上公有云可重新评估。

ADR 的价值在于：三个月后有人问"为什么不用 Pinecone"，不用翻聊天记录，直接指向 ADR-014。

49.3.4 周报（Weekly Status）

周报是 FDE 与客户项目经理之间最高频的契约。差的周报是流水账，好的周报让客户在任何一周都知道"项目是否健康、风险在哪、我需要做什么"。

模板：

# [项目名] 周报 W24（2026-06-09 至 06-15）

## 本周进度（对照里程碑）
- [完成] 数据接入联调，进度 100%（计划 100%，绿）
- [进行] 模型微调，进度 60%（计划 70%，黄，延后 2 天，原因：标注返工）

## 下周计划
- 完成微调并跑离线评测
- 启动灰度环境部署

## 风险与求助
- RSK-007：客户标注团队人手不足，可能影响下周灰度，需 [客户项目经理] 协调 2 人支援

## 关键决策
- DEC-022：本周确定评测指标采用 F1 + 业务方人工抽检双轨

要点：进度必须对照计划，不能只说"做了什么"；风险必须带求助对象，不能只列问题。

49.3.5 交付文档（Delivery Doc）

交付文档是验收的依据。它要回答"交付了什么、怎么验收、怎么接收"。

骨架： 交付物清单（代码仓库与版本号、模型权重与哈希、配置文件、数据集）→ 部署与验收步骤（可复制粘贴的命令）→ 验收标准（量化指标 + 通过线）→ 接收签字栏。

49.3.6 运维手册（Runbook）

运维手册是项目能不能活过三个月的关键。它不是系统说明书，而是"出问题时照着做就能恢复"的剧本。

Runbook 条目模板：

## 告警：向量检索延迟 p95 > 200ms 持续 5 分钟

影响：RAG 召回变慢，用户体验下降。
诊断步骤：
1. 登录 Grafana 看板 RAG-001，确认是否单节点 CPU 飙高；
2. 执行 `kubectl get pods -n milvus` 检查 pod 状态；
3. 若 pod 重启次数 >3，进入恢复步骤 R-03。

恢复步骤：
- R-01：扩容查询节点 `kubectl scale ...`
- R-02：重建索引（附录脚本）
- R-03：回滚到上一版本模型（附录回滚流程）

升级路径：若 30 分钟未恢复，通知 [值班 FDE] + [客户运维负责人]。

每条 Runbook 都应在演练中被实际执行过一次，否则就是纸上谈兵。

49.3.7 培训材料

培训材料的读者是一线员工，他们的特征是：没时间、怕出错、关心自己的利益。所以培训材料要做到"图多字少、操作可照抄、明确告诉他这对他有什么好处"。一份好的培训手册开头不应是"系统架构介绍"，而应是"你每天能省 40 分钟，方法如下"。

49.3.8 案例沉淀（Case Study / Postmortem）

项目结束后的案例沉淀有两类：对外营销用的成功案例（强调效果与数据），对内复盘用的 postmortem（强调做错了什么、学到了什么）。两者不能混用——对外不能暴露客户的坑，对内不能只讲成绩。Postmortem 必须遵循无指责原则（blameless），聚焦流程与决策，不点名追责。

49.3.9 README

README 是代码仓库的入口，也是 FDE 最容易忽视的文档。一个好的 README 至少包含：这个项目解决什么问题、怎么在本地跑起来、关键依赖、目录结构、如何测试、联系人。FDE 的原则是"让一个从未见过这个项目的人，在 30 分钟内能在本地跑通"。

49.4 写给不同读者：风格差异矩阵

同一份信息，写给不同读者要换皮。下表是 FDE 常见的四类读者及其偏好：

读者	关心什么	文档风格	反例
CXO	ROI、风险、战略对齐	一页执行摘要、量化收益、风险与应对、明确决策项	通篇架构图与技术名词
技术负责人	可行性、可维护性、集成成本	架构图、接口契约、ADR、性能指标	只讲业务价值不讲实现
一线员工	会不会被替代、操作流程变不变	图文步骤手册、FAQ、明确的好处说明	抽象方法论
客户采购/合规	价格、条款、数据合规	报价单、合规清单、SLA、数据处理协议	技术细节

一个实用技巧：写完任何一份文档后，自问"这份文档的首位读者是谁？他读完能做出什么动作？"如果答不出，文档就是失败的。

49.5 可追溯性：编号体系与交叉引用

FDE 文档体系的核心健康指标是可追溯性——任何一份文档里的结论，都能追溯到上游依据；任何一次决策，都能被下游引用。实现这一点的硬手段是编号体系。

推荐采用四字母前缀 + 年份 + 序号的编码：

• PDD（Project Definition Document）—— 项目定义
• REQ（Requirement）—— 需求条目
• DEC（Decision）—— 决策记录（ADR 是其中一类）
• RSK（Risk）—— 风险登记条目
• DR（Discovery Report）—— 勘探报告
• SD（Solution Design）—— 方案设计
• RB（Runbook）—— 运维剧本

示例：RSK-2026-007 表示 2026 年第 7 号风险条目。周报里写"本周升级 RSK-2026-007"，方案设计书里写"本方案的风险登记见 RSK-2026-001 至 007"，ADR 里写"本决策关联 REQ-2026-023"。这样任何读者顺着编号都能在文档海洋里导航。

版本管理同样关键。每份正式文档应有版本号（v1.0、v1.1）和变更记录表（日期、版本、变更人、变更摘要）。重大变更必须升大版本号，并通知所有相关读者。

49.6 好文档的五个特征

判断一份 FDE 文档好不好，可对照五个特征：

1. 清晰（Clear）：结构分明，每段一个论点，术语第一次出现要解释。检验方法：让一个不熟悉项目的人读 10 分钟，能复述主线。
2. 准确（Accurate）：数据、日期、版本号、指标值必须真实可核对。任何"大约""可能"都要有依据，或明确标注为估算。
3. 可执行（Actionable）：读者读完知道下一步做什么。Runbook 的命令能复制粘贴就跑；周报的求助指名到人。
4. 可检索（Searchable）：标题、编号、关键词能让搜索引擎和同事在 30 秒内找到。避免"最终版_v3_真的最终.docx"这类命名。
5. 可维护（Maintainable）：文档与代码、系统同步更新。一旦系统变了文档没变，文档就从资产变成负债。

49.7 文档即代码：Markdown + git

FDE 应把文档当代码管理。具体做法：

• 所有文档用 Markdown（或 AsciiDoc）纯文本格式，不用 Word 二进制；
• 文档与对应代码放在同一个 git 仓库（docs/ 目录），或独立的文档仓库；
• 文档变更走 pull request 评审，与代码评审同等严肃；
• 用 CI 检查文档（链接是否失效、编号是否重复、术语是否一致）。

这种方式的好处是：版本天然可追溯、变更可 diff、多人协作有冲突解决机制、历史可回溯。客户交付时再导出 PDF 或 Word 即可。

经验法则：如果一份文档没有被 git 追踪过版本，它就不算正式文档。

49.8 用 AI 辅助写作

LLM 是 FDE 写文档的强力工具，但必须用对位置。合理用法：

• 起草：给 LLM 喂入勘探访谈记录、数据样本，让它生成勘探报告初稿；给它架构图描述，让它生成 ADR 草稿。
• 校对：让它检查术语一致性、错别字、格式规范、链接有效性。
• 改写：把一份技术文档改写成 CXO 版本；把中文译成英文交付给国际客户。
• 生成重复结构：批量生成 Runbook 条目模板、培训 FAQ。

必须人工把关的部分：

• 所有数据、日期、版本号、客户名称——LLM 会编造，必须由 FDE 核对；
• 所有结论与建议——LLM 倾向于给出"政治正确但空洞"的表述，FDE 要补上判断与锋芒；
• 所有合规与合同相关表述——必须人工复核，不能交给模型。

原则：LLM 起草，人审发布。署名是 FDE，责任也是 FDE。

49.9 反模式：文档的常见死法

最后列举 FDE 项目中文档的四种典型死法，反向警示：

第一，文档滞后。系统已经升级到 v3，文档还停留在 v1。成因是文档与代码分离管理、没有同步机制。后果是运维按旧文档操作出事。对策：文档进 git、进 CI、进 release checklist。

第二，空洞文档。通篇"提升效率""赋能业务""打造闭环"，没有一个量化指标、没有一条可执行步骤。成因是写文档的人不了解业务。后果是没人信文档。对策：每段必须能回答"so what"。

第三，不可执行文档。Runbook 写"请检查系统状态"，但不写检查哪个看板、用什么命令、阈值是多少。成因是写的人没真正演练过。后果是出事时手忙脚乱。对策：每条 Runbook 必须经过一次实战或演练。

第四，孤岛文档。文档散落在邮件、微信、个人电脑、共享盘、Confluence、飞书，没有统一索引。成因是没有文档治理。后果是新接手的人找不到任何东西。对策：建立单一文档入口（如一个 README 索引页），所有文档有编号、有归属、有版本。

49.10 一张表：FDE 文档能力自检清单

维度	自检问题
覆盖度	九类文档我是否都有现成模板？
读者适配	我是否能为一件事写出 CXO 版、技术版、一线版三份？
可追溯	我的每条结论是否能追溯到编号？
可执行	我的 Runbook 是否演练过？
版本管理	我的文档是否都在 git 里？
AI 协作	我是否在用 LLM 起草但人审发布？
更新机制	系统变了文档是否同步变？

本专题小结

写作与文档能力是 FDE 的核心能力，因为它承载了沟通、留痕、转移、复用四件事。FDE 全流程交付涉及九类必备文档：勘探报告、方案设计书、ADR、周报、交付文档、运维手册、培训材料、案例沉淀、README，每一类都有明确的读者与模板。写给 CXO、技术、一线、采购四类读者要用不同风格，但同一份信息可以换皮复用。可追溯性靠编号体系（PDD/REQ/DEC/RSK/DR/SD/RB）与版本管理实现。好文档具备清晰、准确、可执行、可检索、可维护五个特征。实践上应采用文档即代码（Markdown + git + PR 评审），并合理使用 LLM 辅助起草与校对，但所有事实与判断必须人工把关。最常见的反模式是文档滞后、空洞、不可执行、孤岛化，对应的解药是文档进 git、每段答 so what、Runbook 必演练、单一索引入口。

本专题来源

• CDEF 方法论（Context 勘探 → Design 设计 → Engineer 工程 → Feedback 反馈）各阶段交付物定义；
• Michael Nygard 提出的 ADR（Architecture Decision Record）格式与社区实践；
• Palantir、Databricks 等 FDE 型公司的内部文档传统（Echo-Delta 双人单元的留痕习惯）；
• 软件工程的"Docs as Code"运动与 GitLab、Google 等公司的文档工程实践；
• 个人驻场项目中九类文档的实际模板与踩坑复盘；
• Site Reliability Engineering（Google）中关于 Runbook 与 Postmortem 的规范；
• LLM 辅助写作实践中"起草—校对—人审"分工的工程经验。