FDE 利器：用 Forma 管理客户项目上下文的全生命周期

从上一篇为一家商标事务所提供服务的项目开始，我们在实际交付中逐渐重视一种工作方式：让前置部署工程师（Forward Deployed Engineer，FDE）在客户真实环境中持续理解问题、推进实施并验证结果。

之后，我们一边在自己的项目中实践，一边把 FDE 的概念和做法介绍给其他客户。这个过程也让我们越来越清楚地看到，FDE 要持续发挥作用，除了工程能力，还需要一个能够承载客户项目上下文的工作环境。

FDE 这个角色经常出现在人工智能（AI）产品和企业软件的讨论中。有人把 FDE 理解成“在客户现场写代码的人”，有人把它当作实施顾问，也有人把它等同于高级技术支持。这些理解都触及了 FDE 工作的一部分，却没有说明这个角色为什么需要一套不同于普通开发或支持工作的工作方式。

这篇文章先说明 FDE 是什么、通常做什么，以及它和其他技术角色有什么不同。然后跟随一个具体的客户接口问题，看看没有共同工作环境时，FDE 和智能体（Agent）会在哪里反复消耗时间，再说明 Forma 如何参与工作开始、调查判断、实施验证和后续交付。

FDE 到底是什么

FDE 通常站在产品团队和客户真实环境的交界处。他不只是把一套已经固定的产品说明交给客户，也不只是等问题出现之后处理工单，而是要把产品带进一个具体、复杂、经常不完整的客户环境，让它真正解决客户的问题。

这里的“前置”不是简单地指工程师去了客户所在地，而是指工程工作被前置到了产品和客户需求之间。FDE 需要理解客户想达成的结果，检查现有系统和环境，判断产品能力与现场条件之间的差距，再通过配置、集成、代码、流程调整或产品反馈，把这段差距尽量缩小。

不同公司的 FDE 职责边界会不同。有的 FDE 更接近解决方案工程师，负责集成和部署；有的更接近产品工程师，直接修改代码和框架；有的还要参与客户培训、技术决策和交付沟通。共同点是：他们不能只依赖一份标准说明书，而要在不确定的真实环境中持续调查、判断和交付。

所以，FDE 既不是普通销售的技术附属，也不是把所有问题都接过来的支持人员。这个角色需要同时具备工程判断、客户沟通和现场推进能力，并且要对“产品在客户环境中最终能不能工作”负责一部分结果。

FDE 做什么，也不做什么

不同公司的 FDE 职责范围会有差异，下面的对照不是一份固定的岗位说明，而是帮助理解这个角色工作边界的参照：

一次 FDE 工作如何推进

FDE 通常从客户提出的目标或问题开始，但不会停在“给出一个答案”。以一个接口在测试环境正常、在正式环境返回不同结果的情况为例，工程师需要沿着一条完整的工作链推进：

• 理解目标：确认客户真正想要的结果、影响范围和紧迫程度，区分现象描述与已经确认的需求。
• 调查环境：核对系统版本、部署方式、接口、认证、网络、数据和最近发生的变更，找出当前环境的特殊条件。
• 形成判断：判断问题来自配置、产品行为、集成方式、环境限制，还是客户对目标结果的理解还没有对齐。
• 实施处理：修改代码或配置，调整集成方案，补充操作步骤，或者把需要产品团队处理的部分明确记录下来。
• 验证结果：通过测试、命令输出、环境对比或客户确认，证明处理结果满足了什么条件，仍然有哪些限制。
• 完成沟通：向客户说明采取了什么方案、为什么这样处理、哪些内容只在当前条件下成立，以及下一步由谁负责。
• 留下上下文：把事实、决定、任务状态和验证证据写回项目，使下一次工作不必从口头回忆开始。

这些动作会反复循环：FDE 可能上午排查系统问题，下午确认需求范围，晚上整理客户团队可以继续使用的操作方案。工作环境还应帮助 FDE 更快开始、减少重复调查、验证结果，并为下一次工作留下入口。

客户：我不是已经和你说过了吗？

客户说：“我不是已经和你说过了吗？”

这句话不一定意味着上次的工作没有完成。更常见的情况是：问题当时解决了，但解决问题所依赖的环境、判断和限制没有留在一个可以继续工作的地方。

FDE 打开了代码仓库，也找到了接口实现，却还要回到工单、聊天记录和会议纪要中，确认当时的环境、客户真正确认的目标，以及上次为什么没有采用看起来更简单的方案。智能体也能读代码，却不知道哪个端点不能直接调用，不知道需求确认到哪一步，更不知道某个决定是否只适用于当前客户。

客户认为自己已经完成了沟通，FDE 面对的却是分散在不同系统中的记录；智能体更无法仅凭一句对话判断这条信息是不是当前项目仍然有效的事实。于是，原本的信息组织问题，很容易被双方体验成“你没有听见我说的话”。

在没有 Forma 这样的共同工作环境时，这不是因为代码仓库、工单系统或沟通工具没有价值。代码仓库记录实现，工单系统记录正式请求，沟通工具保留即时讨论；问题在于，FDE 需要的是把这些信息组织成当前项目可以继续执行的状态，而这些信息往往没有进入同一个工作环境。

没有这层组织，工作会在几个地方反复出现断裂：

很多时候，FDE 先付出的成本并不是写代码，而是恢复上下文。项目越复杂、参与者越多、客户环境越特殊，这个成本就越容易被误认为是“现场工作的正常部分”。

Forma 如何参与一次 FDE 工作

在进入具体工作流程前，先把 Forma 的几个基本概念说清楚：

• 一切都是 Markdown

  Forma 的知识条目以 Markdown（纯文本标记语言）文件存在。它们可以被人直接阅读和修改，也能被 Git（分布式版本管理工具）、智能体和其他工具引用、检查和继续处理。代码、配置和测试仍然是普通仓库文件，不需要被塞进某个封闭数据库。

• 知识需要有形状

  团队可以根据业务定义结构定义（schema）、模板（template）和目录约定，让环境事实、客户要求、决定、任务和验证证据各自保持清晰的结构。这些不是 Forma 固定的行业分类，而是项目可以按需裁剪和扩展的定义。

• Guideline as Skill

  工作指引（guideline）不是只供人阅读的说明，而是人类和智能体都可以遵守的规则，也可以作为 Skill 被智能体加载和执行。它规定开始工作前读什么、哪些动作需要确认、完成后要留下什么证据。

• 不必全搬，但要留好索引

  工单、即时通信（IM）、邮件、会议系统和客户代码仓库不必全部迁移到 Forma；在本团队实践中，可以在工作区建立索引条目（index entry），记录来源、维护人、访问方式和关联关系。这样，外部系统仍然是事实来源，团队成员和智能体也不会失去进入这些信息的路径；确认后的结论再写入项目条目。

这几项能力共同说明 Forma 在 FDE 工作中的位置：它组织项目上下文，但不替代外部系统。

Forma 不替代 Git、持续集成（CI）、客户工单系统或沟通工具，而是把项目事实、判断和约束组织成可读取、可检查、可继续使用的 workspace。Markdown 条目可以和基础技术架构代码、配置、测试及部署脚本放在同一仓库；代码仍由 Git、CI 和团队规范约束。

Forma 也不要求搬入所有外部信息。工单、代码仓库、会议系统等仍是事实来源；工作区只保留索引条目，记录来源、维护人、访问方式和关联关系。索引不复制原文，也不授予新的访问权限，实际读取仍取决于外部系统授权和相应工具。

需要先说明这篇文章的实践边界：我们已经在使用 Forma 管理知识，也用模板和工作指引规范工程实践；本文关于如何把客户交付单元（engagement）组织成完整 FDE 工作环境的部分，是基于这些经验做出的设计推演，不是一份已经完成的 FDE 落地复盘。这里说的“全生命周期”，指上下文从开始调查、实施验证到交接继续使用的连续过程，不等于完整的项目管理或客户服务平台。下面讨论的是可以被验证的工作方式，不把推演写成已经取得的结果。

Forma 不会替 FDE 判断客户环境，也不会自动保证智能体理解正确；它把事实、规则、状态和证据放在共同边界里，让问题更早暴露、正确的工作更容易重复。forma check --json 检查结构和引用，forma view render --json 提供状态投影，forma workspace health --json 暴露健康缺口；这些结果不能证明项目完成，也不能替代工程师确认。

客户项目工作环境

这里把客户交付称为客户交付单元。它可以是一项集成、一段部署支持、一轮系统改造，也可以是持续几周或几个月的技术合作。重要的不是规模，而是它需要一组相对完整的上下文才能继续推进。

在 Forma 中，客户交付单元可以从独立工作区开始。概念上，它需要客户与环境、需求、问题、方案、决定、任务、沟通、操作步骤和工作规则等记录，外加普通的代码、测试和脚本；这些分区是工作场景的约定，不是 Forma 固定提供的行业结构。

这份概念结构不要求和每个仓库逐字一致。当前仓库的可运行客户项目示例把稳定记录类型拆成独立的 Forma content groups：overview、customers、communications、asks、issues、proposals、decisions、tasks、runbooks、guidelines、engineering 和 verifications。每个 group 都有自己的 include pattern、schema、create template 和分区指引；这些 group 名称和分区规则仍然是团队约定，不是 Forma 的行业内置类型。

在这个示例中，概念结构里的 systems 角色被拆到 customers（客户与环境事实）、engineering（代码、配置和测试的 Markdown 上下文）以及 verifications（可复核的命令结果）中；这只是当前团队的分区选择，不是 Forma 对 systems 的特殊映射。

src、tests 和 scripts 是普通工程资产，与 Markdown 条目、配置和工作指引一起由 Git、测试、CI 和人工评审管理；架构决策、使用边界和验证结果再以 Markdown 记录。FDE 也不应每次从空目录开始：经过验证的技术骨架可以作为新项目可选择、需按当前环境调整的起点。

其中，systems 往往是 FDE 工作里最容易被低估、却最有价值的一类知识。它不只是系统名称和访问地址，还应该记录版本、环境差异、部署限制、认证方式、已知故障和不能直接套用的操作步骤。

可运行示例：客户项目工作环境

为了把上面的工作方式落到可运行的资产上，仓库提供了一个客户项目工作环境示例。它用项目事实、外部沟通索引、项目条目和普通工程文件串起从调查到验证的流程；其中的资料是示例数据，不是生产客户资料，也不是一次真实客户交付的复盘。guidelines/partition-contracts.md 说明各分区的用途、字段和人工边界，也可以作为 Agent Skill 读取。

要开始体验，先按照仓库中的 Installing Forma 安装已发布的 Forma CLI，并确认命令可用：

forma --version

然后从上面的 GitHub 页面获取示例项目并进入 examples/fde-customer-project-workspace 目录。这个示例是根据我们团队在客户项目中的经验整理出的参考实现，不是可以直接复制的标准模板；请根据自己的客户边界、内容分区、字段、验证方式和外围系统调整，或者从零开始构建一个适合自己的最小工作区。

浏览示例时，VS Code 扩展是可选的：可以安装 Forma for VS Code；如果不安装扩展，就在示例目录中运行 forma serve，通过 webapp 浏览和维护工作区。

接着用你熟悉的 Agent 打开示例项目。如果 Agent 尚未安装 forma-cli skill，可以先查看 skills.sh 上的 forma-cli skill 页面，或在示例目录中运行：

npx skills add https://github.com/choral-io/choral-forma --skill forma-cli

安装完成后，让 Agent 先按项目中的分区指引读取工作区，然后发送下面的提示词：

请先读取当前工作区的 Forma 配置、入口条目和分区指引，简短介绍这个客户项目工作环境：它解决什么问题、主要分区分别负责什么、哪些内容是团队约定，以及我可以从哪里开始。只读，不修改文件。

示例中的 content group、业务分区、分区契约、人工确认和 fixture 目录是团队约定；Forma 提供的是 workspace/config、schema、template、view 和 guideline/Skill 等结构能力。外部工单、代码托管、通知、凭证、项目管理、跨工作区协作和自动脱敏仍由外部系统、权限或产品能力负责。

把一次客户工作落回项目条目

以刚才的接口问题为例，FDE 先把客户目标、现象和影响记录到 asks 或 issues，再读取 customers 的环境事实，并结合 engineering 和 verifications 核对接口、认证、最近变更和实际结果。环境差异应作为调查线索，目标不清时则留下待确认问题。

原因和处理方向清楚后，候选方案及其适用条件进入 proposals，确认后的取舍进入 decisions，代码、配置和部署验证产生的命令输出与客户确认写入 verifications，并成为任务证据、状态更新或 runbooks 素材。

最后，FDE 向客户说明处理结果和适用边界，并把这次工作留下的事实、决定和验证依据写回对应条目。这样，工作环境记录的就不只是“问题已解决”，而是问题为什么这样判断、采取了什么行动，以及下一次遇到相似情况时从哪里开始。

外部沟通如何进入项目上下文

FDE 工作中的重要信息，往往最先出现在即时通信（IM）、邮件和会议记录里。把这些信息整理进工作区，并不意味着把所有聊天记录复制成文档，也不意味着让智能体把一句未经确认的话直接升级成正式决定。更稳妥的做法，是保留来源，提取候选信息，经过确认后再写入项目条目。

这个过程可以由一套简单的工作指引约束：

• 先索引来源：在 communications 中创建一个 Markdown 索引条目，记录外部系统、原始链接、维护人、时间范围、访问限制和关联项目条目。
• 再提取候选：把沟通中值得进入项目的内容分别整理为 asks、issues、proposals 或 tasks 的候选，不把整段对话直接当成长期知识。
• 保留来源关系：候选条目应当链接回沟通索引，索引也应当说明它对应哪些外部记录。需要引用原话时，只保留足以支持判断的最小片段。
• 经过确认再生效：客户目标、环境事实、候选方案、正式决定和交付承诺，需要由负责成员或客户确认后，才从候选状态进入项目的有效状态。
• 持续检查变化：外部记录发生更新、链接失效、权限变化或沟通结论被推翻时，及时更新索引和受影响的项目条目。

例如，communications/customer-a-api-issue.md 可以是一个项目约定的索引条目，内容大致包括：

# 客户 A API 问题沟通索引

- 原始来源：客户工单、IM 讨论、项目会议
- 参与者与时间：客户接口负责人、FDE；2026-08-02
- 原始链接：外部系统中的稳定链接
- 关键内容：客户描述了正式环境中的异常响应；邮件确认了预期结果
- 已关联条目：`customers/c-017.md`、`asks/acknowledgement-window.md`
- 待确认事项：上线窗口和回滚责任人
- 访问限制：需要客户工单系统权限

这个条目是导航和溯源记录，不是外部系统的副本。经过确认的环境事实、客户要求、正式决定和任务，仍然应当分别写入对应的项目条目。

以接口问题为例，即时通信中可能出现客户对现象的描述，邮件中可能确认预期结果，会议中可能讨论上线窗口。它们可以分别保留在外部系统中；工作区只需要记录这些来源的索引，并把已经确认的内容关联到 customers、asks、decisions、tasks 和 verifications。这样，FDE 下次处理问题时，能够从项目条目看到当前状态，也能沿着来源链接回到完整沟通记录。

智能体可以帮助完成检索、摘要、候选条目创建和关联检查，但不应自行决定一段沟通是否构成正式承诺。工作指引可以要求它在写入 decisions、customers 或 engineering 前检查来源、时间、确认状态和适用范围；信息不足时先保留为待确认事项，并请求团队成员处理。

工作指引即 Skill：让规则进入实际工作

Forma 还可以把客户项目中的工程实践编码到模板和工作指引中。

面向客户的工作区模板可以自带基础开发框架、目录约定、检查脚本和必要说明，让工程资产和项目知识一起版本管理、复核和继续使用。文档不必等代码完成后再补上，而是工作环境的一部分。

工作指引是团队成员可以评审的维护规范，也是智能体执行一类工作前可以加载的 Skill：它说明开始前读什么、哪些动作需要确认、何时必须停下、完成后运行哪些检查，以及结果写回哪里。

在客户项目示例中，分区契约本身就是一个 section-projected Skill。Agent 加载它时可以直接看到 customers/、asks/、issues/、decisions/、engineering/ 和 verifications/ 等分区的用途，再用 workspace explain 确认具体条目实际选中的 content group、schema、template 和 guideline。

结构定义（schema）让同类内容保留关键字段，模板（template）让新项目从正确形状开始，视图（view）呈现待处理事项，工作指引则把结构转化为工作动作；它们组合起来才形成可运行的工作环境。

这也是 Forma 与许多传统知识库使用方式的差别：后者常常先解决“资料是否被保存”，而 FDE 工作环境还要让人和 Agent 能基于这些内容继续工作。

当然，工作指引不是强制执行代码规则的替代品。硬约束仍然应该由持续集成、测试、权限系统和客户环境本身负责。工作指引的作用是提供共同的工作方式和停止边界，让智能体与人先理解规则，再进入这些确定性工具保护的执行环节。

Forma 给 FDE 带来的直接价值

把 Forma 放进 FDE 工作环境，价值不在于多保存文件，而在于改变上下文流动方式：工程师从项目状态、环境事实和待确认事项开始，事实、决定、限制和证据有明确归属；智能体在当前边界内按约定动作并在不确定时停下；代码、配置、测试和 Markdown 一起演进，交付结果留下验证证据、适用条件和限制。

这些价值不会因为建立一个工作区就自动出现。团队仍然需要维护结构、更新工作指引、确认事实，并对敏感信息和正式决定承担责任。Forma 提供的是一个让这些工作可以被组织、检查和持续改进的边界。

Forma 不负责什么

Forma 不替代 Git、CI、客户工单、沟通和会议工具：它们继续负责版本、构建、正式请求、即时协作和会议记录；Forma 组织需要长期理解、复核和继续使用的工程上下文。

Forma 目前不负责主动提醒、客户侧实时聊天、凭证管理或访问权限；客户仓库权限、智能体工具范围、备份、数据处理和人员责任仍由外围工具与组织约定负责。

从客户交付单元开始试用

FDE 团队不需要一开始就设计完整的平台。更实际的起点，是从正在进行、但上下文已经开始分散的客户项目开始。

先定义最小工作区：保留 customers、communications、asks、issues、decisions、tasks、engineering 和 verifications，为每类内容设置最少的结构定义和模板，再写几条团队与智能体共同遵守的工作指引：开始工作前先读什么，会议结束后必须留下什么，工作完成前必须检查什么。

然后让另一名工程师或智能体尝试执行一项低风险任务。不要只问“觉得好不好”，而是观察它能否找到当前阻塞、理解环境限制、区分已确认的决定和待确认的要求，并在不重新询问原作者的情况下完成一次工作。

如果结果不理想，不要急着增加更多字段。先判断缺的是事实、结构、状态、规则，还是项目本身没有形成决定。Forma 能让这些缺口更容易暴露，却不能替团队凭空补出不存在的客户事实。

可以从下面这句话开始与智能体协作：

请先检查当前 Forma 工作区的结构和健康状态，读取分区契约以及与客户项目工作和敏感信息处理有关的工作指引。然后根据当前项目中的 customers、communications、asks、issues、decisions、tasks、engineering 和 verifications，向我生成一份只读的工作摘要：当前状态、已确认事实、未决事项、环境限制、下一步建议和需要人工确认的风险。不要修改文件。

这条提示词的重点不是让智能体“总结所有资料”，而是要求它围绕一次真实的工程动作工作。团队也可以据此继续调整结构定义、模板和工作指引，直到成员或智能体能够稳定完成相同的工作流程。

回到 FDE 的日常工作

回到 FDE 的日常工作，真正有用的变化并不是工程师从此不需要沟通，也不是智能体从此不会犯错。

变化在于，客户项目的环境事实、未决需求、已确认决策、排查证据和工作规则有了共同入口；工程师可以从状态开始，智能体可以从规则行动，并在不确定时停下。对 FDE 和团队来说，这减少了恢复上下文的时间，也让项目成为可以维护、复核和交接的工作环境。

Forma 目前仍处于公开预览（Public Preview）阶段，更适合内部试用、评估和反馈。对于 FDE 团队，合理的起点不是把它直接包装成面向客户的成熟产品，而是在真实客户交付单元中验证：工程师是否更容易从项目状态开始工作，调查和实施过程是否更容易留下证据，工作是否更容易由另一位成员继续，以及客户边界是否更清晰。

想了解 Forma 的产品文档、设计决策和实际工作区，可以从 Forma GitHub 仓库 开始。

相关内容可以继续阅读 《从 knowledge-workflow 到 Forma：为不同领域定义知识的形状》 和 《从文档到知识资产：让团队在工作中持续积累专业知识》。