# 数据放在哪没问清，三周代码白写了

> 在客户网络里开发的 FDE，花两天写一页设计文档，就能趁分歧还好改时把它暴露出来。

原文: https://fdetimes.net/zh/guides/design-doc-ai-app-customer-infrastructure/

设想你在一家银行的第一周。你做了一个查询内部规章流程的助手原型，在笔记本上运行顺畅，通过公共 API 调用模型。到了第三周，银行安全团队告诉你，内部文档不得离开他们的网络。几乎所有集成工作都得推倒重来。

这类风险是这份工作自带的，因为前线部署工程师（FDE）是在别人家里干活。Anthropic 的 FDE 招聘启事写明了一项核心职责：在客户系统内部，用 Claude 模型构建生产环境应用。你的代码必须适配客户的网络、审批流程和运维团队。

所以，想做 FDE，值得早学的不只是提示词和检索增强生成（RAG），写代码前先写设计文档也是一项。道理很简单：花两天写一页纸，成本远低于三周走错方向的代码。

## 一页纸，让分歧浮出水面

设计文档不会规定每个函数。在 Google，设计文档记录总体实现策略和关键设计决策，重点是考虑过的权衡。它回答三个问题：我们要做什么？怎么做？为什么这么做？

把方案写下来，是检验大家是否真正达成一致的最快办法。The Pragmatic Engineer 的 Gergely Orosz 观察到，如果团队对方案本来就有共识，写下来只是件小事。分歧往往在写的过程中冒出来。这页纸让分歧提早暴露，趁改动成本还低。

共享文档还能明确责任。Orosz 认为，它几乎总能促成考虑更周全的决策。对 FDE 来说，好处很实际：关于数据或范围的决策一旦写成文字、客户也读过，日后双方各执一词的空间就小了。

不过并非每项任务都需要文档。文档长度要与工作复杂度相称。Orosz 调研过的公司，通常只在范围广、复杂度高的项目、全公司范围的技术要求以及 API 变更上使用 RFC。

## 从现状出发

问“标准流程是什么”，你得到的是一份整洁的文档；问“上次你要查某个流程时，是怎么做的”，你得到的才是实情。2024 年至 2026 年担任 FDE 的 Pooya Golchian 把这条原则概括为：问现在实际怎么做，而不是按规定应该怎么做。

在银行的例子里，答案可能是：员工在共享文件夹里翻找，找不到就给一位老员工发消息。这个细节应该写进文档的第一节。

它告诉你，真正的竞争对手是在聊天软件上回答问题的同事。系统的回答必须够快，引用来源也要充分，用户才会信任。

然后才写目标。紧接着目标的，是新人最常跳过的一节。

## 非目标：划定边界的地方

非目标不是换成否定句的目标。“系统不能慢”其实是变相的目标。Google 的指南把非目标定义为：本可以合理地作为目标、却被刻意排除的事项。

对银行的助手来说，真正的非目标可能是：暂不回答外部客户的问题，暂不处理扫描图片格式的 PDF，暂不支持索引实时更新。这三项都合理，迟早有人会提，而每一项都是有意排除的。

不必列出所有排除项。只需写下那些合理的、在评审中被提出过的，或者再争论一次代价很高的事项。Joshka 对“记录有意为之的非目标”这一模式就是这样描述的。

如果省掉这一节，三个月后客户那边会有人问，系统为什么读不了扫描文件，一个划定范围的决定就会被当成疏漏。

**要点:** 今天写下一条非目标，就能省掉三个月后的一场争论。

## 客户的基础设施从哪里进入设计？

Uber 的 RFC 模板包含服务 SLA、依赖、负载与性能测试、安全、指标与监控等章节。对部署在客户基础设施中的 AI 应用来说，每一节都会变成一组写代码前必须问清的问题。

以前面的银行为例，这些问题是：数据可以放在哪里，只能在内网，还是可以放在经批准的云区域？模型运行在客户本地部署的 GPU 上，还是调用外部服务？安全评审要多久，谁来签字？还有最常被遗忘的一个：交接之后，谁来运维集群？

SLA 一节应包含故障场景。例如，GPU 集群过载时，系统降级到较小的模型，回答更短、细节更少，但仍附引用；模型完全宕机时，系统只返回相关文档列表。提前写明这些，客户就清楚自己签下的是什么。

接下来是“备选方案”。列出能达到类似效果的其他设计，让评审者看清其中的权衡。对这家银行，对比可能如下：

| 方案 | 收益 | 代价 |
|---|---|---|
| 通过云 API 调用模型 | 部署快，质量高 | 可能与“数据不得出网”的规定冲突 |
| 在客户本地 GPU 上运行开源模型 | 数据留在内部 | 客户需要有人运维 GPU |
| 只做检索，不生成回答 | 简单，容易通过安全评审 | 用户仍得自己读文档 |

这张表不会替你做决定。它让与客户的会议聚焦在真实的权衡上，而不是技术偏好。

## 设计文档骨架

把这些部分拼起来，银行助手的初稿不到两页就能写完：

```
# 内部流程查询助手 — 设计文档 v0.1

## 现状
- 员工在共享文件夹里翻找；找不到就问老员工

## 目标
- 回答内部流程相关问题，始终注明来源文档

## 非目标（附理由）
- 暂不服务外部客户：有法律风险，需要单独审批
- 暂不读取扫描版 PDF：需要 OCR，基础设施尚未就绪

## 基础设施约束
- 数据可以放在哪里 / 模型运行在哪里
- 谁审批安全，需要多久
- 交接后谁来运维系统

## 拟定设计
- 在本地 GPU 上运行开源模型，检索共享文件夹，
  每条回答都链接到来源文档中的对应段落
- 待安全团队确认：数据不离开内网

## 备选方案
- 云 API / 本地开源模型 / 只做检索（见权衡对比表）

## SLA、依赖与故障场景
- GPU 过载：降级到较小的模型，仍附引用

## 测试与上线
- 先在一个部门找 10 名员工试用 2 周，再扩大范围

## 指标与监控
- 引用正确的回答占比，用户反馈有误的回答数量

## 交接：运维手册 + 评测集
- 评测集：取自员工不得不发消息问老员工的
  那些问题，附正确答案和对应文档
- 每当模型变更或文档更新，银行运维团队
  重新运行评测
- 运维手册：GPU 过载、索引过期、回答缺少引用
```

## 写给运维系统的人，而不是自己

检验设计文档的最终标准，是客户团队能否独立运行这套系统。Golchian 正是这样定义 FDE 的：在客户公司内部构建软件，直到对方团队能自己运行它。在他描述的交接中，客户的工程师凭借一份运维手册和一套评测集接手系统。

因此，文档的最后一节不该空到最后一周。就像上面的骨架那样，从 v0.1 开始就写明：评测集由哪些问题集组成，客户那边由谁来运行，运维手册覆盖哪些故障。

做过几个项目后，这副骨架会逐渐充实，成为一项资产。Anthropic 的招聘启事也要求 FDE 识别并沉淀可复用的部署模式，并反馈给产品团队。一份在三个客户那里打磨过的设计文档模板，正是这样的模式。

## 常见错误

第一个错误是写完代码再写文档，文档就沦为对既成决策的图解。第二个错误是非目标只是对目标的否定，比如“不慢”“不出错”，什么也没排除。

第三个错误是备选方案一节塞满稻草人方案，摆出来只是为了被否决。客户方的评审一眼就能看穿，而你恰恰在最需要对方签字时失去了信誉。第四个错误是为一个小改动写一份长文档，团队里没人愿意读。

最后一个错误代价最高：不问你离开后由谁来运维系统。这个问题的答案几乎决定了上面所有的基础设施选择。

如果想在求职时展示这项能力，可以把一份去除敏感信息的设计文档放进作品集。阅读岗位描述时，留意 Anthropic 招聘启事中“work within customer systems”（在客户系统内工作）这类表述。招聘经理会看到，你先考虑客户的系统，再考虑模型。

笔记本上的原型证明一个想法行得通。设计文档证明，在你离开客户的办公楼之后，它仍然行得通。

**本周动手试试:**

- 挑一个你做过的 AI 功能，按上面的骨架把它的设计文档重写成一页，至少包含三条附理由的非目标。
- 针对当前项目，列出四个基础设施问题（数据可以放在哪里、模型运行在哪里、谁审批安全、交接后谁来运维），标出哪些还没有答案。
- 写一节“备选方案”，列出三个真实可行的方案，分别说明收益和代价。

## 信源

- [Design Docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/)

- [Scaling Engineering Teams via RFCs: Writing Things Down](https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/)

- [Companies Using RFCs or Design Docs and Examples of These](https://blog.pragmaticengineer.com/rfcs-and-design-docs/)

- [Forward Deployed Engineer (Anthropic, via General Catalyst job board)](https://jobs.generalcatalyst.com/companies/anthropic/jobs/89778489-forward-deployed-engineer)

- [forward deployed engineering](https://pooyagolchian.com/forward-deployed-engineering/)

- [Document Intentional Non Goals](https://www.joshka.net/practice/patterns/document-intentional-non-goals/)
