开发者吐槽OpenSpec Skill：文档管理低效，建议转向Harness Skill
速览
有开发者在独立游戏开发中尝试使用OpenSpec Skill，但发现其文档架构过于平行且缺乏优先级，导致在探索上下文时过度依赖大模型的检索能力。由于Helper函数等关键信息在开发后期容易漂移，难以被准确命中，该方案被评价为差强人意。作者建议将Spec仅保留用于TDD验证，而将项目框架和具体实现细节移至Harness Skill中，以实现更有效的管理。
AI 深度解读
背景
在独立游戏开发的语境下，开发者尝试利用 OpenSpec 这一规范驱动开发（Specification-Driven Development）工具来管理项目文档。然而，在实际落地过程中，作者发现现有的 OpenSpec 工作流存在明显的局限性。主要痛点在于文档架构过于扁平化（平行结构），缺乏明确的优先级排序，导致在构建大模型（LLM）的上下文环境时，过度依赖模型的检索能力和上下文窗口大小。
具体表现为：当开发者编写了诸如“渲染并截图各个界面UI”或“统一 Address 别名入口”等辅助性（helper）功能文档后，在项目进入后期开发阶段时，这些关键信息往往因为上下文漂移（context drift）而无法被大模型准确命中或引用，从而影响了代码生成的准确性和开发效率。
核心内容
作者基于上述痛点，提出了一种改进的 AI 辅助开发工作流，核心思想是将“规范验证”与“项目框架/上下文”解耦，具体策略如下：
-
脱离平行文档，转向 Skill References： 作者认为，不再需要在项目文件夹中编写与
OpenSpec平行的冗长文档。相反，应该将项目特定的框架细节和关键逻辑点整合进Harness Skill中。通过Skill References机制，让大模型能够更精准地调用所需的专业技能或上下文。 -
OpenSpec 回归 TDD 验证本质：
OpenSpec的角色应当被重新定义，仅保留用于测试驱动开发（TDD）中的验证功能。即利用OpenSpec来定义预期行为和验收标准，确保代码符合规范，而不是用它来承载所有的项目架构信息。 -
Harness Skill 承载项目框架： 项目的整体框架、核心逻辑点以及那些容易在长上下文中丢失的辅助功能定义（如 UI 渲染截图、地址别名管理等），应放入
Harness Skill中。Harness通常指代用于控制 AI 行为、提供特定上下文或执行特定任务的技能集合。通过这种方式，可以确保关键信息在对话或代码生成过程中保持高权重和可检索性，避免上下文漂移。
简而言之，作者的建议是：Spec 管验证，Skill 管框架与上下文。
关键要点
- 痛点识别：
OpenSpec的平行文档结构缺乏优先级，导致大模型在长上下文开发中难以精准检索关键信息，出现“漂移”现象。 - 架构调整：从“平行文档”模式转向“Skill References”模式，利用技能引用机制优化上下文管理。
- 职责分离：
- OpenSpec：专注于 TDD 验证，定义规范和预期结果。
- Harness Skill：承载项目框架、核心逻辑点及易丢失的辅助功能定义。
- 目标效果：通过结构化技能引用，提高大模型在项目后期对关键上下文（如 UI 渲染、别名管理）的命中率和准确性。
意义与影响
这一分享反映了当前 AI 辅助开发领域的一个重要趋势：从单纯的“文档即代码”向“结构化技能与上下文管理”演进。
- 对 LLM 工作流的启示：单纯依赖自然语言文档（如 Markdown）来管理复杂项目规范，在面对长上下文和复杂逻辑时效率低下。引入
Skill和Harness等结构化概念，有助于将非结构化的文档转化为大模型更易理解和调用的结构化指令。 - 规范工具的重新定位：
OpenSpec等规范工具不应试图包揽所有项目信息，而应专注于其擅长的领域（如验证、合规性检查）。将上下文管理交给专门的技能系统，符合“关注点分离”的软件工程原则。 - 独立开发者的效率优化：对于资源有限的独立开发者而言，这种工作流调整可以显著降低因上下文丢失导致的返工成本，提高 AI 生成代码的可用性和一致性。
总之，作者的建议为如何在复杂项目中有效利用大模型提供了实用的工程化思路，即通过精细化的技能管理来弥补大模型在长上下文记忆和检索上的不足。