拆解但不失全貌：如何在 OpenSpec 中管理复杂 Agent 需求的演进-云帆数科

在使用 OpenSpec 驱动复杂 AI Agent如 ChatBI 的多轮澄清、错误修复机制的开发时团队常常会陷入一种进退两难的工程困境大泥球陷阱把整个业务比如整个“WHERE 澄清”的所有分支、重试保护、LLM Prompt 设计全塞进一个 Change变更里。结果导致设计文档长达千行开发周期无限拉长Code Review 根本无从下手代码冲突不断。碎片化陷阱吸取了教训开始拆分把大需求拆成了十几个细小的子模块。但由于拆得太细目录嵌套极深开发者在写代码时“见树不见林”完全不知道当前这个小模块比如 34000 维度消歧的前置依赖是什么以及它为后续哪个功能比如 34100 全量学习做铺垫。如何做到“拆解需求”的同时“不失全貌”核心解法在于用主线 Spec 维护全景图用带前缀的扁平 Change 推进增量用 Proposal 串联故事线。最佳实践 1主干与分支分离 (The Source of Truth)OpenSpec 最重要的一条原则是分离“当前是什么样”与“这次要改成什么样”。主线目录 (openspec/specs/)这是系统的“全景地图”。无论底下拆了多少个 Change当一个变更开发、测试通过并发布后它的契约增量必须合并到这里。新人看这个目录就能了解系统现在的完整能力。变更目录 (openspec/changes/)这是“施工现场”。每一个目录代表一次原子的、可独立验证的交付通常对应一个 PR。切记永远不要在changes/里的某个变更下存放系统的全量规范。变更目录里只存放Delta增量。最佳实践 2使用顺序前缀管理演进 (Sequential Prefixing)当一个大 Epic如 ChatBI 澄清重构被拆散后如果在文件系统中它们只是一堆无序的文件夹逻辑链条就断了。解法为 Change 目录增加两位数的顺序前缀。.agentic/openspec/changes/ ├── 01-foundation-chatbi-clarification/ -- 基础骨架与接口契约 ├── 02-where-clarify-34000-dim-name/ -- 依赖 01处理 34000 分支 ├── 03-where-clarify-34100-full-learning/ -- 依赖 02处理 34100 全量学习 └── 04-where-clarify-retry-guard/ -- 依赖 03增加全局重试保护通过这种方式IDE 的目录树直接变成了一本“目录手册”。谁先谁后、谁是基础谁是进阶一目了然。最佳实践 3让 Proposal 成为故事的串联者在传统开发中需求的依赖关系往往存在于 Jira 或 Jira Ticket 的 Links 里随着代码库的流转这些上下文很容易丢失。在 OpenSpec 中proposal.md不是一个走过场的空文件它的核心职责是声明依赖与边界。每个拆分后的微小 Change都必须在proposal.md中回答三个问题Context (上下文)我在哪例如我是 ChatBI 聚合查询澄清 Epic 的一部分。Dependencies (依赖关系)Depends On: 我依赖谁例如依赖01-foundation提供的 Payload 结构。Blocks: 谁依赖我例如为后续的03-full-learning提供前置的兜底路由。Scope (边界)我这次坚决不做啥防范围蔓延的最强武器。最佳实践 4保持变更目录的扁平化一旦把大需求按逻辑拆成了小的 Change就不需要在 Change 内部再维持复杂的模块嵌套了。错误示范过度嵌套changes/ └── 02-where-clarify-34000-dim-name/ └── designs/ └── chatbi-clarification/ └── where-clarification/ └── 01-design.md正确示范扁平化changes/ └── 02-where-clarify-34000-dim-name/ ├── proposal.md ├── designs/ │ └── 01-dimension-name-ambiguity-34000.md └── tasks/ └── 01-dimension-name-ambiguity-34000.md因为 Change 本身的 Scope 已经足够小其内部的designs和tasks只需要最简单的平铺开发者一眼就能找到今天该干的活。总结OpenSpec 不是为了增加文档负担而是为了把脑海里的隐性上下文变成显性的工程资产。当你发现一个 Change 变得难以描述、设计文档开始写不下去时通常意味着它太大了。果断使用顺序前缀将它拆开用proposal.md拴住它们的关联把最终的拼图放回主线specs。这就是驾驭复杂 Agent 工作流的不二法门。

企业数字化 ERP 产品动态

相关推荐

团队内部 README：在通用项目开发中使用 OpenSpec

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/3 9:59:10

【AI Engineering】项目学习新姿势：把知识管理、PRD 和 Spec 串起来

Highcharts Gantt使用符号的自定义数据标签开发甘特图示例

使用符号的自定义数据标签、带头像 Font Awesome 图标标签的甘特图代码，复制就能用！完整可运行代码（带头像图标数据标签）Highcharts.ganttChart(container, {title: {text: Highcharts Gantt Chart},subtitle: {text: With cus… · 2026/11/3 9:58:09

Chloe：基于多级向量化与控制路径缩减的全同态加密上的循环变换

一、核心问题论文的核心问题是：现有 FHE 编译器对“非平凡循环结构”的支持不足，导致 FHE 上程序表达能力和执行效率受限。具体来说：FHE 允许在密文上计算，但密文计算与明文计算行为差异很大。逻辑电路、比较、分支等非算术操作在… · 2026/11/3 10:30:56

为什么自编码器与流模型不能拆开用？RFD4-Proteína匹配检查点对机制深度解析

为什么自编码器与流模型不能拆开用？RFD4-Protena匹配检查点对机制深度解析 RFD4-Protena 是由 Baker Lab 与 NVIDIA GenAIR 联合发布的生物分子设计模型，能同时生成蛋白质序列与全原子结构。它的权重由流模型和自编码器两个检查点构成，官方强… · 2026/11/3 10:30:56

Z-Image-Turbo-FP8 原理揭秘：如何吃透 torchao 动态激活量化机制？

Z-Image-Turbo-FP8 原理揭秘：如何吃透 torchao 动态激活量化机制？ Z-Image-Turbo-FP8 是基于 torchao 动态激活量化打造的 Z-Image-Turbo 文生图模型量化仓库：它把 6B 参数的 Diffusion Transformer 以 FP8 / INT8 两种低精度方案重新打包&a… · 2026/11/3 10:30:56