# 让上一次交付，成为下一个客户的起点

> 约三小时写好五份文档、建好一个模板仓库，团队的经验就不会随前线部署工程师离开而流失。

原文: https://fdetimes.net/zh/guides/package-deployment-playbook-runbook-template-repo/

一次部署的最后一周往往过得很匆忙：演示、验收签字、交接，然后奔赴下一个客户。三个月后，第二个客户带着同样的问题找来，团队又从一张白纸开始。

fde.academy 上的 FDE 手册把一次部署分为六个阶段。最后一个阶段是反馈闭环：为每个客户定制的工作，逐步标准化为可复用的功能。同一网站上一篇介绍 Palantir 模式的文章说得更直接：前线部署工程师（FDE）构建的每个解决方案，都会反哺后续的产品开发。

这篇文章也点出了反面。如果不管理这个闭环，工作就会滑向纯粹的定制，变得很难规模化。因此，能否把做完的项目打包好，实际上决定了你是在为产品做贡献，还是在一个客户接一个客户地做一次性定制。

## 一个晚上能做出什么？

做完之后，你会得到一个文档目录和一个 GitHub 上的模板仓库。下面用一个例子贯穿全文：假设你刚给一家物流公司交付了一个 Agent，它读取 PDF 发票，再把数据写入对方的 ERP。这个例子是虚构的，但下面的结构适用于任何类型的项目。

你需要四样东西：一个 GitHub 账号、旧项目的仓库、部署期间的会议纪要或聊天记录，以及大约三个小时不受打扰的时间。目标结构如下（已简化）：

```text
fde-invoice-agent-template/
├── README.md            # 这个仓库解决什么问题，如何运行
├── docs/
│   ├── adr/             # 架构决策，每个决策一个文件
│   ├── runbooks/        # 操作指南：故障处理、日常运维
│   ├── explanation/     # 系统为什么这样工作
│   └── playbook.md      # 面向新客户的部署阶段
├── config/
│   └── customer.example.yaml
└── src/
```

要写的五份文档是 README、ADR、Runbook、原理说明和手册。下面的步骤逐一介绍，最后把所有内容打包进模板仓库。

## 第 1 步：趁记忆还在，记录决策

adr.github.io 上的定义很简短：架构决策记录（ADR）记录一个架构决策及其背后的理由。打开会议纪要，找出团队争论过的地方，比如用哪个 OCR、批处理还是实时、Agent 应该自行修正数据还是等人工审批。

```markdown
# ADR-003：Agent 不直接写入 ERP，而是等待人工审批

## 背景
发票格式不统一；客户的 ERP 不支持回滚。

## 决策
Agent 写入暂存表；财务审批后，数据才推送到 ERP。

## 影响
+ 错误数据不会进入账簿。
- 增加一个人工步骤；需要统计审批耗时。

## 何时重新评估
当新客户的 ERP 提供撤销 API 时。
```

“何时重新评估”是最有价值的部分。它告诉后来者：这个决策依赖旧客户的特定条件，新客户可能需要不同的方案。**检验：**把 ADR 交给一位没参与项目的同事。如果他读完还要问“为什么不直接写入 ERP？”，说明文件缺少背景。

## 第 2 步：把 Runbook 和原理说明分开

Diátaxis 对操作指南的定义是：带领读者解决一个问题或达成一个结果的指引。Runbook 应该按这个思路写：每一步都是一个动作，中间不夹解释性段落。“为什么”留给 `docs/explanation/`。

```markdown
# Runbook：发票队列卡住

目标：队列恢复运行，且不丢失任何发票。

1. 打开队列看板，记下待处理发票的数量。
2. 查看最近 15 分钟的 worker 日志，查找 OCR 超时错误。
3. 如果存在超时：将 worker 切换为逐个文件处理模式。
4. 确认待处理发票的数量在下降。
5. 如果 30 分钟后仍未下降：通知客户的值班联系人（见通讯录）。

了解原因：docs/explanation/ocr-timeouts.md
```

示例中的数字仅作演示，请替换为你系统中的真实阈值。**检验：**快速浏览一遍 Runbook。如果某一步以“注意，系统会……”开头，就把这句话挪到原理说明里。

## 第 3 步：和真正使用 Runbook 的人一起写

Google 的 SRE 一书在事故管理一章中建议提前准备：尽早制定并记录事故处理流程，并与将参与事故处理的人共同商定。在发票 Agent 的例子里，如果交接后由客户自己运维系统，这些人就是客户的 IT 团队，而不是你的团队。

所以不要一个人写完 Runbook 再用邮件发过去。约一个 45 分钟的会，让运维人员逐步操作，你坐在旁边默默观察。凡是他们需要开口问的步骤，都要重写。

## 第 4 步：按阶段整理手册

`playbook.md` 不是 ADR 的副本，而是一张地图：针对每个部署阶段，写下要问客户什么、要读哪些 ADR、要提前准备哪些 Runbook。可以用 fde.academy 手册的六个阶段作为框架，只要最后一个阶段始终是回到产品的反馈闭环。

```markdown
## 阶段：数据集成
- 询问客户：ERP 是否支持撤销？（→ ADR-003）
- 准备：runbooks/queue-stuck.md
- 为上一个客户做的定制：针对自定义发票模板的解析器
  → 可纳入产品的候选（已通知核心团队）
```

最后一行才是 Palantir 式闭环真正发生的地方：一线的解决方案经核心团队评审，变成产品能力。每写下一次“可纳入产品的候选”，就把项目从纯定制的陷阱里拉出来一次。

## 第 5 步：建模板仓库，不要 fork

GitHub 文档说明，任何有模板仓库访问权限的人都可以用它创建新仓库。这样创建的仓库从单个 commit 开始。fork 则不同：它会带上完整的历史。

对 FDE 来说，这个区别很重要。旧项目的提交历史里可能有客户名称、内部 endpoint，或者有人误提交后又删除的示例 CSV 文件。

最干净的做法是：新建一个仓库，只拷入清理过的代码，用 `customer.example.yaml` 替换所有客户专属的值，然后在仓库设置中开启模板模式。

**要点:** 只有当下一个客户比上一个起步更快时，一个项目才算真正完成。

**检验：**用模板创建一个测试仓库，打开提交历史，确认只有一个 commit。然后在整个代码库中搜索旧客户的名称、域名以及“prod”之类的词，结果应该为空。

## 让文档失去作用的三个错误

第一个错误是把 Runbook 当成教科书。SRE 一书在培训值班工程师的章节中，把只靠流程、检查清单和手册来培训列为反模式。

Runbook 帮助人们执行正确的步骤；`explanation/` 目录帮助他们理解原因。当事故与任何已写好的步骤都对不上时，只有这种理解能救场。

第二个错误是为了省时间直接 fork 旧客户的仓库，把整段历史一起拖过来。第三个错误是只记录“做了什么”，跳过“为什么”。没有 ADR，下一个客户就会继承一些只在旧客户的情境下才合理的决策。

## 招聘中哪里会考察这项能力？

阅读 FDE 岗位描述时，你可能会以不同的说法遇到上面的反馈闭环。留意那些提到把一线经验带回产品团队、或构建跨客户复用资产的段落：这说明公司需要的正是这项能力。

简历上不要只写“为客户 Y 部署了系统 X”，要写得更具体，比如：“把项目打包为模板仓库、ADR 和 Runbook；下一个客户直接复用，无需从零重写”。条件允许的话，附上一个清理过的公开模板仓库链接。面试时，挑一份 ADR，讲讲它背后的争论。

到新客户的第一天，先打开的应该是上一个项目的 `playbook.md`，而不是 IDE。交付的项目只有在下一个人能复用时，才会成为团队的资产。

**本周动手试试:**

- 拿出最近交付的一个项目，为争议最大的三个决策各写一份 ADR
- 写一份故障处理 Runbook，然后和一位在该系统值过班的人逐步过一遍
- 按本文的目录结构建一个模板仓库，把链接加到简历上，并配一句话说明

## 信源

- [The Forward Deployed Engineer Playbook: How Top FDEs Approach a New Deployment](https://fde.academy/blog/forward-deployed-engineer-playbook)

- [How Palantir Invented the Forward Deployed Engineer Model and Why AI Startups Are Adopting It](https://fde.academy/blog/how-palantir-invented-the-forward-deployed-engineer-model)

- [Managing Incidents (Google SRE book, ch. 14)](https://sre.google/sre-book/managing-incidents/)

- [Chapter 28 - Accelerating SREs to On-Call and Beyond](https://sre.google/sre-book/accelerating-sre-on-call/)

- [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)

- [How-to guides](https://diataxis.fr/how-to-guides/)

- [Architectural Decision Records (ADRs)](https://adr.github.io/)
