如何把公司文档里的经验，变成自己项目里的工程约束

这周我在规划一个基于 OpenCode 的客户端。

之前我调研过一个同类的二次开发项目。一开始我的想法很直接：把它的源码和文档找出来，看看他们怎么做的，哪些架构可以照着用，哪些功能可以直接参考。

但真正读进去以后，我发现最值得带走的并不是它的页面、目录结构或者某段实现，而是散落在使用手册、问题反馈、架构评审和复盘记录里的那些失败模式。

成功的架构图往往很整齐，踩坑记录才会告诉你系统真正贵在哪里。

公司文档不是一份可以直接照抄的答案

这次调研最先遇到的问题，是文档之间的“事实等级”并不相同。

有些是用户已经遇到过的问题，比如客户端更新中断当前任务、运行环境找不到、模型调用长时间没有响应。

有些是团队在架构评审中提出的风险，比如 Skill 的职责边界、工具数量过多可能影响模型选择。

还有一些只是候选方案，描述的是“未来可以怎么做”，并不能证明它已经上线，更不能证明它经过了生产验证。

如果把这些内容混在一起，很容易犯两个错误：

把一个历史问题当成当前版本仍然存在的问题；
把一份设计方案当成已经验证过的最佳实践。

所以我先给资料做了简单分类：

使用手册和问题反馈，用来确认真实发生过的流程与故障；
架构会议和技术评审，用来识别团队已经意识到的风险；
方案草稿，用来比较可选路径、实施成本和回滚思路。

分类以后，很多结论就不再需要争论。我们只需要明确：这是事实、判断，还是尚未验证的方案。

不复制功能，提取失败模式

读别人项目时，最容易问的是：“这个功能我们要不要也做？”

后来我发现，更有效的问题是：“他们为什么需要这个功能？它前面发生了什么？”

例如，内部文档提到客户端更新会重启程序，并可能中断正在进行的任务。

如果只复制表面功能，得到的可能只是一个“稍后更新”按钮。但真正需要解决的问题是：长任务的状态不能只存在于当前会话和进程内存里。

翻译到我们自己的项目，就是：

运行过程需要持久化 Manifest；
更新前需要建立 checkpoint；
重启后能够恢复未完成任务；
已完成阶段不能重复执行；
恢复行为必须有自动化测试。

再比如，问题反馈中经常会出现“客户端卡住了”。

但“卡住”只是用户看到的表象。背后可能是：

桌面程序没有响应；
本地运行进程退出；
工具调用超时；
模型服务过载；
模型预算耗尽；
服务端任务正在排队。

如果把这些情况统一显示成“正在处理中”，后面的客服和排障成本一定会很高。

因此，我们真正应该借鉴的不是某个错误提示，而是建立分层健康状态：桌面程序、本地运行时、工具、模型服务和业务服务端分别报告状态，让用户看到不同原因，也让程序能够采取不同的恢复动作。

还有一个很典型的例子是 Skill 的职责边界。

把 Skill 当成能力入口看起来很自然，但一旦让它承担状态同步、数据交接这类职责，马上就会遇到身份、幂等、冲突、权限、重试和断点续传。

这些能力不是多写几段提示词就能解决的。

最后提炼出的原则是：

Skill 适合作为能力入口，但不适合作为可靠状态和同步基础设施。

到了我们自己的项目里，Skill 可以负责理解用户意图和发起操作，真正的状态、协议和长期任务仍然应该由明确的数据结构、typed API 和服务端运行时承担。

经验只有变成约束和测试，才算真正融合进项目

读完一堆文档，整理出十几条“值得借鉴的经验”并不难。

难的是这些经验过两周以后还会不会影响代码。

为了避免调研报告最后只停留在文档里，我要求每条重要经验至少落到下面四种结果之一：

架构边界；
开发红线；
具体任务；
可自动执行的验收标准。

例如，“不能深度修改 OpenCode，否则以后升级困难”，不能只写成一句原则。

它需要继续变成：

自有功能只能进入隔离的业务目录；
上游代码差异必须由脚本检查；
OpenCode 当前版本和候选升级版本运行同一套合同测试；
升级失败必须能够回退；
CI 检测到非允许目录变更时直接失败。

这样，一条来自别人项目的经验，才从“建议”变成了我们项目里的工程约束。

我现在越来越倾向于把需求写成可执行合同，而不是只写功能描述。

比如更新恢复可以写成：

Given 一个任务已经完成画面生成，正在执行音频阶段
When 客户端更新并重新启动
Then 已完成阶段不会被重复执行
And 当前阶段进入明确的可恢复状态
And 最终产物的版本关系保持连续

这种描述既能指导开发，也能让 AI 自主判断任务是否完成。

没有测试标准的任务，对 AI 来说通常只是“看起来写完了”。

哪些经验适合做成 Skill

这次实践本身也可以沉淀成 Skill，但并不是所有东西都应该塞进 Skill。

适合放进 Skill 的是方法和工作流，比如如何区分事实、评审意见和候选方案，如何提取失败模式，如何把外部经验映射成当前项目的架构约束和测试合同。建立来源索引、检查重复结论、校验任务和文档之间引用关系这类确定性动作，交给脚本更合适。

但可靠队列、同步、权限、状态机和无人值守运行，仍然应该由正式程序和服务端实现。Skill 的价值是把一套经过验证的做事方法交给 AI，而不是用提示词重新实现基础设施。

我准备固定下来的检查清单

以后再调研其他团队的类似项目，我会先回答下面几个问题：

这条信息是事实、评审判断，还是尚未验证的方案？描述的是当前状态还是历史版本？
对方真正解决的是什么问题，这个问题在我们的系统中是否同样存在？
对方的实现是否依赖了我们不具备的组织和基础设施条件？
能否把结论转化为架构边界、开发任务和自动化测试？
如果两周后没人再读这份报告，代码和 CI 是否仍然会执行这些约束？

这次最大的收获，是我不再把“参考其他项目”理解成复制方案。

下一步，先把更新恢复的 Given/When/Then 合同和 CI 的非允许目录变更检查落进 OpenCode 客户端项目，让这次调研的结论从第一周就开始被执行。