企业官网建设流程全解析

• 后端
• 前端
• 企业应用
• 运维
• 网络安全

导读

本文以 Fleet 官方架构决策记录 ADR-0010: OpenSpec Adoption 为核心，完整还原了 Fleet 团队评估并拒绝将 OpenSpec 可选工具目录、.claude/CLAUDE.md 与 PR 模板 等源码证据，深入剖析 Fleet 现有 AI 辅助开发工作流为何能替代一套独立的规范文件体系。读完本文，你将理解：spec-driven 框架在大型开源仓库中的落地成本（评审负担、规范漂移、小改动开销）、Fleet 以"GitHub Issue 为单一事实来源 + AI 生成 PR 描述 + 项目级 Agent 约定"三条支柱构成的结构化思考机制，以及 OpenSpec 这类工具在当前阶段的适用边界。

一、背景：ADR 是什么，为何 Fleet 要评估 OpenSpec

1.1 Fleet 的架构决策记录机制

Fleet 仓库在 docs/Contributing/adr/ 目录维护着一套完整的 Architecture Decision Records（ADR）体系，已有 0010、0011、0012 等多份决策记录。每份 ADR 遵循 template.md 定义的标准结构：

1. Title：描述性标题
2. Status：Proposed / Accepted / Rejected / Deprecated / Superseded
3. Context：促成该决策的上下文与问题陈述
4. Decision：最终决策及其理由
5. Consequences：决策带来的正面与负面影响
6. References：相关 issue、文档链接

ADR-0010 的Status 为Rejected（2026-05-21），属于"评估后否决"型决策记录——这类记录的价值恰恰在于：即使不采纳，也把评估过程、否决理由和未来复审条件沉淀为团队知识，防止未来重复论证。

1.2 评估对象：OpenSpec 是什么

原 ADR 开篇定义了评估对象 OpenSpec（由 Fission AI 出品）：

• 它是一个spec-driven development（规范驱动开发）框架；
• 团队将 Markdown 规范文件提交到仓库的openspec/目录；
• 每个功能或变更对应一个文件夹，内含 proposal（提案）、design doc（设计文档）、task list（任务清单）以及delta specs（采用 Given/When/Then 场景格式的增量规范）；
• 变更发布后，deltas 会被归档并合并进一个描述系统当前状态的"spec library"（规范库）。

其核心目标有两个：其一，在生成代码之前让 AI 编码代理与人类开发者对齐"要构建什么"；其二，在代码之外维护一份随系统演进的、可执行的系统行为"活规范"。

Fleet 团队因此发起评估：是否应在仓库中引入openspec/目录并开始提交 spec 文件？

二、决策：不采用 OpenSpec，以现有工作流替代

2.1 最终决定

Fleet 决定不采用 OpenSpec。理由非常直接：现有工作流已经提供了 OpenSpec 所追求的结构化思考收益，不需要再引入一套并行的规范层。

2.2 现有工作流的"三条支柱"

原 ADR 明确指出，Fleet 现有的三项机制已经覆盖了 OpenSpec 想解决的问题：

仓库中的 PR 模板 印证了第二支柱：模板要求 PR 描述必须包含 Related issue、Testing、Frontend、Database migrations、GitOps 设置、fleetd/orbit 兼容性等多个固定小节，并明确要求 AI 代理填写## AI段（注明工具与模型 ID）。这意味着结构化思考被内建在 PR 流程本身，而非依赖额外的规范文件。

而 .claude/CLAUDE.md 则印证了第三支柱：它明确规定了后端请求流HTTP request → server/service/handler.go 路由 → endpoint 解码 → service 业务逻辑 → datastore SQL → 响应，以及 Fleet 特定的代码注释风格、错误处理、术语（"Teams"→"Fleets"、"Queries"→"Reports"）等约定。AI 代理在写代码前就被引导到正确的模式上。

2.3 关键论断：Issue 是单一事实来源

ADR 的核心判断是：GitHub Issue 仍然是每次变更的 source of truth。规范、验收标准、设计上下文都存在于 Issue 中，并直接关联到实现它的 PR。而采用 OpenSpec 会创建一个并行的规范层，它：

• 大体上只是重复 Issue 中已有的内容；
• 以提交到仓库的文件形式存在，需要持续维护；
• 容易同时偏离 Issue 与实际实现（spec drift）。

换言之，规范文件增加的是"第三份需要同步的副本"，而不是"更清晰的第一份定义"。

三、后果分析：否决决策带来的正面与负面影响

原 ADR 将决策后果分为三类，逐一保留并展开：

3.1 正面后果（Positive）

• PR 评审表面积不变：不引入额外的规范文件，PR 的 diff 不会被成百上千行 spec Markdown 污染；
• 零维护负担：无需专门维护 spec 文件与代码库的同步；
• 无工具依赖风险：不依赖一个年轻、单维护者的工具（评估时 OpenSpec 仍处于早期阶段）。

3.2 负面后果（Negative）

• 放弃标准化的机器可读规范格式：未来 AI 代理可能从中受益的标准化上下文缺失；
• 没有集中的"spec library"：描述系统当前行为的职责仍由用户故事和文档承担，结构化程度较低；
• 代理获取历史决策上下文的成本升高：AI 代理要了解之前的决策，需要调用gh api查询 Issue，而不是直接读取本地可读的设计/业务逻辑决策日志——这一点原 ADR 特别强调，会削弱"防止产品在无意图情况下被改动"的能力。

3.3 未来复审条件（Future considerations）

ADR 明确列出了三个"何时重新考虑"的触发条件，这也是决策记录中最具操作价值的部分：

1. 当前工作流在规模化后失效——当 PR 描述 + Issue 的模式无法承载变更复杂度时；
2. OpenSpec 增加"从规范到实现的自动化验证"——即把 spec 变成可强制执行的检查（enforceable checks），而不仅仅是文档；
3. 工具显著成熟——API 稳定、维护者基础扩大。

四、备选方案评估：为什么其他路径也不被采纳

原 ADR 评估了三个备选方案，每个都有明确的否决理由，这是全文最有工程参考价值的部分。

4.1 方案一：全面采用 OpenSpec

向仓库提交完整的openspec/目录（spec library + 每次变更的产物）。被否决的原因有三：

• 代码评审负担（Code review burden）：每个 PR 都要附带数百行额外的 spec Markdown。评审者要么逐一核对 spec 与实现是否一致（评审工作量翻倍），要么跳过核对（spec 沦为未经验证的装饰）。而评审吞吐量本就是团队的瓶颈；
• 规范漂移（Spec drift）：保持 spec 准确需要每次变更后运行openspec archive，并在实现中途转向时同步更新 spec——两步都是强依赖全体贡献者纪律的手动步骤。一旦漂移发生，对账工作就会与发布新功能竞争资源；
• 小改动的开销不成比例（Overhead for small changes）：社区经验表明，OpenSpec 即使对简单的 bug 修复也会生成大量产物。Fleet 的变更集是琐碎改动与复杂改动混合的，对前者而言开销过高。

4.2 方案二：仅对大型功能采用 OpenSpec

选择性使用，多组件大功能用、小改动不用。被否决的原因：

• 采用不一致造成困惑：何时需要 spec 的规则不清晰；
• 大功能恰恰是规范漂移最快的场景：多组件功能在实现过程中，spec 最容易被实现偏离；
• 规范库只覆盖系统子集：作为 source of truth 的价值大打折扣。

4.3 方案三：在 PR 描述中强制"Approach"结构化小节

为复杂变更的 PR 描述增加轻量模板（Problem / Change / Why this layer / What I considered）。未被作为正式流程采纳，因为 AI 生成的 PR 描述在无强制格式的情况下已经覆盖得足够好——这正是"以工具能力替代流程强制"的典型例证。

五、仓库证据：OpenSpec 在 Fleet 中的"降级"形态

5.1 一个矛盾但自洽的现实

尽管 ADR 拒绝将 OpenSpec 作为正式政策，仓库根目录下却真实存在 openspec/ 目录——这正是决策的另一面：工程师个人可以将 OpenSpec 作为本地思考与规划工具（原 ADR 明确允许），只是不强制、不纳入正式流程。

该目录中的 README 定位写得很清楚：

OpenSpec 在本仓库中是opt-in 工具，不是开发流程的必需部分。团队未将其采纳为政策，没有任何 PR 被要求使用它。

5.2 OpenSpec 目录的实际内容与工作流

• openspec/README.md：工具定位、安装方式、四步流程与目录约定；
• openspec/config.yaml：项目上下文与规则配置，指向.claude/CLAUDE.md作为权威项目指南。

其四步流程explore → propose → apply → archive如下：

1. /opsx:explore— 思考想法，不写代码、默认不生成产物；
2. /opsx:propose— 在openspec/changes/<change-name>/下生成proposal.md（是什么 & 为什么）、design.md（怎么做）、tasks.md；
3. /opsx:apply— 实现任务，传变更名（如/opsx:apply add-foo）或由上下文推断；
4. /opsx:archive— 合并后把变更移入openspec/changes/archive/并更新openspec/specs/下的规范。

openspec/README.md 还给出了明确的使用边界，与原 ADR 的否决理由一一对应：

• 值得用：跨 datastore / service / endpoint / UI 的横切功能；触及多文件且需要先对齐形状的重构；想与人或 AI 协作评审的 RFC 式设计；
• 跳过：bug 修复、小功能、依赖升级、文档调整——"如果一次变更能装进一个 PR 描述里，那就写 PR 描述"；
• 产物即文档，非契约：代码评审仍然是 source of truth。

5.3 不可手工编辑的 vendored 文件

openspec/README.md 特别警告：openspec update会覆盖本地改动，因此以下目录由 OpenSpec CLI 托管、禁止手工编辑：

• .claude/skills/openspec-*/
• .claude/commands/opsx/

需要定制时应改 openspec/config.yaml；若确需分叉某个 skill，应复制为新名字以避免被 updater 覆盖。

六、延伸对照：Fleet 对"通信/规范新机制"的取舍模式

将 ADR-0010 放在 Fleet 的决策序列中，可以清晰看到一种一致的工程取舍哲学。例如已获批准的 ADR-0011: Agent WebSocket transport 在"引入新传输机制"时同样做了大量备选方案评估（long polling、SSE、gRPC streaming、ETag conditional requests），最终只选择"与现有轮询协议互补"的方案，并明确要求轮询保留为兜底基线。

映射到 ADR-0010：Fleet 对待 OpenSpec 的态度与对待 WebSocket 的态度如出一辙——新的规范/通信机制只能作为增量优化（opt-in、可回退），绝不取代现有可靠基线（Issue + PR + 轮询协议）。这也是理解这份拒绝型 ADR 的最重要视角：否决不是排斥新工具，而是拒绝让新工具成为必须维护的"第二套事实来源"。

七、实践建议：什么情况下值得重新评估

综合原 ADR 的 Future considerations 与仓库现状，可以给出以下可操作的判断清单（均基于本仓库可见的事实，不构成对未来的预测）：

1. 先量化维护成本：如果团队发现 PR 描述 + Issue 无法承载复杂变更（评审反复澄清、实现偏离验收标准），说明结构化程度不足——这正是 ADR 列出的触发条件一；
2. 关注工具的"可执行化"进展：若 OpenSpec 演进到能自动验证 spec 与实现一致（而非纯文档），其价值主张会从"额外负担"转为"自动检查"，触发条件二成立；
3. 观察工具成熟度：stable API、多维护者基础（触发条件三）；
4. 在采用前做小规模试点：用 openspec/ 目录里已配置好的 opt-in 工作流（/opsx:propose等）对单个大型重构做试点，实测"多出的维护工时"是否小于"评审节省的工时"，再决定是否提交正式 ADR 修改该决策。

八、结论

ADR-0010 是一份教科书式的"拒绝型架构决策记录"：它清晰地定义了评估对象、给出了可验证的否决理由（评审负担、规范漂移、小改动开销、工具不成熟）、量化了正负后果，并保留了未来复审的触发条件。同时，仓库中 openspec/ 目录的 opt-in 形态完美地演示了"组织不采纳某流程，但允许个体将其作为思考工具"的工程管理艺术。

对正在评估 spec-driven 开发框架（OpenSpec 或其他类似工具）的团队，这份 ADR 的价值在于：在引入任何"第二套规范层"之前，先确认现有的 Issue + PR + Agent 约定体系是否已经提供了足够的结构化思考；若已具备，新增规范文件的边际收益将远小于其维护成本。而"Issue 是唯一事实来源"这一原则，正是 Fleet 保持 AI 辅助开发流程与人工评审流程不脱节的基石。

延伸阅读（仓库内）

• ADR-0010 原文
• ADR 目录与索引
• ADR 模板
• OpenSpec 可选工具说明
• OpenSpec 项目配置
• AI 代理项目指南
• PR 描述模板
• ADR-0011: Agent WebSocket transport（对照参考）

• 后端
• 前端
• 企业应用
• 运维
• 网络安全