AI 编程助手的幻觉问题：如何用 OpenSpec 实现规范驱动开发

AI 编程助手的幻觉问题如何用 OpenSpec 实现规范驱动开发AI 编程助手虽然强大但常常生成不符合实际需求、违反项目规范的代码。本文分享 HagiCode 项目如何通过 OpenSpec 流程实现规范驱动开发用结构化的提案机制显著减少 AI 幻觉风险。背景用过 GitHub Copilot 或 ChatGPT 写代码的同学可能都有过这样的经历AI 生成的代码看起来很漂亮但真正用起来却问题百出。可能是用错了项目里的某个组件可能是忽略了团队的编码规范也可能是基于一些不存在的假设写了大段逻辑。这就是所谓的AI 幻觉问题——在编程领域它表现为生成看似合理但实际上不符合项目实际情况的代码。其实这事儿也挺无奈的。AI 编程助手越来越普及这个问题也就越发严重了。毕竟AI 缺乏对项目历史、架构决策和编码规范的理解而自由度过高又容易让它创造性地生成不符合实际的代码。这和写文章倒是挺像的没有章法就容易写得天马行空可实际上并不是那么回事儿。为了解决这些痛点我们做了一个大胆的决定不是试图让 AI 更聪明而是给它套上一个规范的笼子。这个决定带来的变化可能比你想象的还要大——稍后我会具体说。关于 HagiCode本文分享的方案来自我们在 HagiCode (https://hagicode.com) 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目致力于通过结构化的工程实践来解决 AI 编程中的实际问题。AI 幻觉的根源在深入解决方案之前咱们先看看问题到底出在哪。毕竟知己知彼方能百战不殆只是这话用在 AI 身上好像也有点意思。上下文缺失AI 模型训练时用的是公开的代码库但你的项目有它自己的历史、约定和架构决策。这些隐性知识 AI 没法直接获取所以生成的代码往往和项目实际情况脱节。这也不能全怪 AI毕竟它又没在你们项目待过哪知道你们那些江湖规矩呢就像新来的实习生不懂规矩也正常只是代价可能有点大罢了。自由度过高当你问 AI帮我实现一个用户认证功能时它可能生成任何形式的代码。没有明确的约束AI 就会按照它认为合理的方式去实现而不是按照你项目的要求。这就像是让一个从未学过你项目规范的人自由发挥能不出问题吗其实也不是它不负责任只是它压根不知道什么是责任。缺乏验证AI 生成代码后如果没有经过结构化的审查流程那些基于错误假设的代码就会直接进入代码库。等到测试甚至生产环境才发现问题代价就太大了。这无异于亡羊补牢只是羊都已经跑光了补牢又有什么用呢这道理谁都懂可真正做起来又总觉得麻烦。毕竟在事情变坏之前谁愿意多花时间呢OpenSpec规范驱动开发的答案HagiCode 选择 OpenSpec 作为解决方案核心思路是所有代码变更必须通过结构化的提案流程把抽象的想法转化为可执行的实施计划。这话说得挺高大上的其实就是让 AI 在写代码之前先把需求文档写好罢了。毕竟凡事预则立不预则废古人诚不我欺。什么是 OpenSpecOpenSpec 是一个基于 npm 的命令行工具fission-ai/openspec它定义了一套标准的提案文件结构和验证机制。简单说就是让 AI 在写代码之前先写好需求文档。三步流程防幻觉OpenSpec 通过一个三步流程来确保提案质量Step 1初始化提案- 设置会话状态为 OpenspecingStep 2中间处理- 保持 Openspecing 状态逐步完善工件Step 3完成提案- 转换到 Reviewing 状态这个设计有个很巧妙的细节第一步使用的是ProposalGenerationStart类型完成后不会触发状态转换。这确保了整个多步流程完成前不会过早进入审查阶段。其实这个细节也挺有意思的就像做菜一样火候没到就揭锅盖肯定是什么都做不好的。只有耐心一点一步一步来最后才能做出一道好菜。csharp // HagiCode 项目中的实现 public enum MessageAssociationType { ProposalGeneration 2, ProposalExecution 3, /// summary /// 标记三步提案生成流程的开始 /// 完成后不会转换到 Reviewing 状态 /// /summary ProposalGenerationStart 5 }标准化的文件结构每个 OpenSpec 提案都遵循相同的目录结构Plain Text openspec/ ├── changes/ # 活跃和归档的变更 │ ├── {change-name}/ │ │ ├── proposal.md # 提案描述 │ │ ├── design.md # 设计文档 │ │ ├── specs/ # 技术规范 │ │ └── tasks.md # 可执行任务清单 │ └── archive/ # 归档的变更 └── specs/ # 独立的规范库根据 HagiCode 项目的统计目前已经有 4000 个归档变更和 15 万 行规范文件。这些历史积累不仅让 AI 有章可循也为团队提供了宝贵的知识库。这就像是古人留下的典籍读多了自然就能悟出点门道来。只是现在这典籍不是写在竹简上而是存放在文件里罢了。多层验证机制系统实现了多层验证来确保提案质量csharp // 验证必需文件存在 ValidateProposalFiles() // 验证执行前提条件 ValidateExecuteAsync() // 验证启动条件 ValidateStartAsync() // 验证归档条件 ValidateArchiveAsync() // 提案名称格式验证kebab-case ValidateNameFormat()这些验证就像是层层把关的守门人只有真正合格的提案才能通过。虽然看起来繁琐可总比让糟糕的代码进入代码库要强吧Prompt 模板约束HagiCode 中的 AI 执行时使用预定义的 Handlebars 模板这些模板包含明确的步骤指导和保护措施。比如禁止在未理解用户意图时继续禁止生成未验证的代码要求在名称无效时重新提供如果变更已存在建议使用继续命令而不是重新创建这种带着脚镣跳舞的方式反而让 AI 更聚焦于理解需求和生成符合规范的代码。其实约束这东西也不一定是坏事毕竟自由过头了就容易乱套。实践如何在项目中使用 OpenSpec安装和初始化bash npm install -g fission-ai/openspec1 openspec --version # 验证安装在项目根目录会自动创建openspec/文件夹结构。这步其实也没什么好说的安装工具嘛大家都懂。只是记得用fission-ai/openspec1这个版本新版本可能有坑毕竟稳定压倒一切。创建提案在 HagiCode 的对话界面中使用快捷命令Plain Text /opsx:new或者指定变更名称和目标仓库Plain Text /opsx:new add-user-auth --repos repos/web创建提案这事儿就像写文章列提纲一样有了提纲后面就好写了。只是很多人喜欢直接开始写写到一半才发现思路不通那才叫头疼。生成工件使用/opsx:continue逐步生成所需的工件proposal.md (http://proposal.md)- 描述变更的目的和范围markdown # Proposal: Add User Authentication ## Why 当前系统缺少用户认证功能无法保护敏感 API。 ## What Changes - 添加 JWT 认证中间件 - 实现登录/注册 API - 更新前端集成design.md (http://design.md)- 详细的技术设计markdown # Design: Add User Authentication ## Context 当前使用公开 API任何人均可访问... ## Decisions 1. 选择 JWT 而非 Session... 2. 使用 HS256 算法... ## Risks - 令牌泄露风险... - 缓解措施...specs/- 技术规范和测试场景markdown # user-auth Specification ## Requirements ### Requirement: JWT Token Generation 系统 SHALL 使用 HS256 算法生成 JWT 令牌。 #### Scenario: Valid login - WHEN 用户提供有效凭据 - THEN 系统 SHALL 返回有效的 JWT 令牌tasks.md (http://tasks.md)- 可执行的任务清单markdown # Tasks: Add User Authentication ## 1. Backend Changes - [ ] 1.1 创建 AuthController - [ ] 1.2 实现 JWT 中间件 - [ ] 1.3 添加单元测试这些工件其实就像是写文章的草稿草稿写好了正文自然就顺畅了。只是很多人不喜欢写草稿觉得浪费时间可实际上草稿才是最能理清思路的地方。审查和应用完成所有工件后Plain Text /opsx:applyAI 会读取所有上下文文件按照 tasks.md (http://tasks.md) 中的清单逐步执行任务。这时候因为有了清晰的规范生成的代码质量会高很多。其实到了这一步事情就已经成了一半了。有了明确的任务清单剩下的就是按部就班地执行罢了。只是很多人跳过了前面的步骤直接到这里那质量自然就难以保证了。归档变更完成后Plain Text /opsx:archive将完成的变更移动到archive/目录方便以后查阅和复用。归档这事儿挺重要的就像把写完的文章好好收起来一样。以后遇到类似的问题翻一翻以前的记录可能就有答案了。只是很多人懒得做觉得麻烦可实际上这些积累才是最宝贵的财富。注意事项和最佳实践提案命名规范使用 kebab-case 格式以字母开头仅包含小写字母、数字和连字符✅add-user-auth❌AddUserAuth❌add--user-auth命名规范这东西说起来也没啥大不了的只是统一一点总归是好的。毕竟代码这事儿 consistency 很重要只是很多人不在意罢了。避免常见错误在三步流程的步骤 1 使用错误的类型- 会过早转换状态忘记在最后一步触发状态转换- 会卡在 Openspecing 状态跳过审查直接执行- 应该先验证所有工件完整这些错误其实都是新手容易犯的老手自然知道怎么避免。只是新手总有变老手的一天走了弯路也就罢了只希望不要走太多弯路就好。多变更管理OpenSpec 支持同时管理多个提案这在处理大型功能时特别有用bash # 查看所有活动变更 openspec list # 切换到特定变更 openspec apply add-user-auth # 查看变更状态 openspec status --change add-user-auth多变更管理这事儿就像同时写几篇文章一样需要一点技巧和耐心。只是习惯了就好了毕竟人嘛总能适应的。会话状态机理解了解状态转换有助于排查问题Plain Text Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → ArchivedOpenspecing生成规划中Reviewing审查中可反复修改工件Executing执行中应用 tasks.md (http://tasks.md)状态机这东西说白了就是一套规则。规则这东西有时候挺烦人的但更多时候是有用的。毕竟没有规矩不成方圆这话古人早就说过了。总结通过 OpenSpec 流程HagiCode 项目在解决 AI 幻觉问题上取得了显著效果减少幻觉- AI 必须遵循结构化规范不能随意生成代码提高质量- 多层验证确保变更符合项目标准加速协作- 归档的变更为后续开发提供参考可追溯性- 每个变更都有完整的提案、设计、规范和任务记录这套方案不是让 AI 变聪明而是给它套上规范的笼子。实践证明带着脚镣跳舞反而跳得更好。其实这道理也简单约束不一定是什么坏事。就像写文章有了格式的约束反而更容易写出好东西来。只是很多人不喜欢约束觉得限制了自己的创造力可实际上创造力也需要土壤才能开花结果。如果你也在使用 AI 编程助手并且遇到过类似的问题不妨试试 OpenSpec。规范驱动开发可能看起来多了一些步骤但这些前期投入会在代码质量和维护效率上得到数倍的回报。毕竟慢一点有时候反而是快一点。只是很多人不明白这个道理罢了…参考资料OpenSpec npm 包www.npmjs.com/package/fission-ai/openspec (https://www.npmjs.com/package/fission-ai/openspec)HagiCode 项目地址github.com/HagiCode-org/site (https://github.com/HagiCode-org/site)HagiCode 官网hagicode.com (https://hagicode.com)观看 30 分钟实战演示www.bilibili.com/video/BV1pirZBuEzq/ (https://www.bilibili.com/video/BV1pirZBuEzq/)Docker Compose 一键安装docs.hagicode.com/installation/docker-compose (https://docs.hagicode.com/installation/docker-compose)Desktop 桌面端快速安装hagicode.com/desktop/ (https://hagicode.com/desktop/)如果本文对你有帮助欢迎来 GitHub 给个 Star。HagiCode 公测已开始现在安装即可参与体验。这文章写得也差不多了其实也没什么特别高深的东西只是把一些实践经验总结了一下罢了。希望对大家有用毕竟分享这东西自己学到了也让别人学到了两全其美何乐而不为呢只是文章终究是文章真正有用的还是实践。毕竟纸上得来终觉浅绝知此事要躬行古人诚不我欺…原文与版权说明感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。本文作者: newbe36524 (https://www.newbe.pro)原文链接: https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development%2F (https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development%2F)版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!