在使用 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 工作流的不二法门。
在使用 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 工作流的不二法门。
