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

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

AI 编程助手虽然强大，但常常生成不符合实际需求、违反项目规范的代码。本文分享 HagiCode 项目如何通过 OpenSpec 流程实现"规范驱动开发"，用结构化的提案机制显著减少 AI 幻觉风险。

背景

用过 GitHub Copilot 或 ChatGPT 写代码的同学可能都有过这样的经历：AI 生成的代码看起来很漂亮，但真正用起来却问题百出。可能是用错了项目里的某个组件，可能是忽略了团队的编码规范，也可能是基于一些不存在的假设写了大段逻辑。
这就是所谓的"AI 幻觉"问题——在编程领域，它表现为生成看似合理但实际上不符合项目实际情况的代码。
其实这事儿也挺无奈的。AI 编程助手越来越普及，这个问题也就越发严重了。毕竟，AI 缺乏对项目历史、架构决策和编码规范的理解，而自由度过高又容易让它"创造性"地生成不符合实际的代码。这和写文章倒是挺像的，没有章法就容易写得天马行空，可实际上并不是那么回事儿。
为了解决这些痛点，我们做了一个大胆的决定：不是试图让 AI 更聪明，而是给它套上一个"规范"的笼子。这个决定带来的变化，可能比你想象的还要大——稍后我会具体说。
关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，致力于通过结构化的工程实践来解决 AI 编程中的实际问题。
AI 幻觉的根源

在深入解决方案之前，咱们先看看问题到底出在哪。毕竟知己知彼，方能百战不殆，只是这话用在 AI 身上，好像也有点意思。
上下文缺失

AI 模型训练时用的是公开的代码库，但你的项目有它自己的历史、约定和架构决策。这些"隐性知识" AI 没法直接获取，所以生成的代码往往和项目实际情况脱节。
这也不能全怪 AI，毕竟它又没在你们项目待过，哪知道你们那些江湖规矩呢？就像新来的实习生，不懂规矩也正常，只是代价可能有点大罢了。
自由度过高

当你问 AI"帮我实现一个用户认证功能"时，它可能生成任何形式的代码。没有明确的约束，AI 就会按照它"认为"合理的方式去实现，而不是按照你项目的要求。
这就像是让一个从未学过你项目规范的人自由发挥，能不出问题吗？其实也不是它不负责任，只是它压根不知道什么是责任。
缺乏验证

AI 生成代码后，如果没有经过结构化的审查流程，那些基于错误假设的代码就会直接进入代码库。等到测试甚至生产环境才发现问题，代价就太大了。
这无异于亡羊补牢，只是羊都已经跑光了，补牢又有什么用呢？这道理谁都懂，可真正做起来，又总觉得麻烦。毕竟在事情变坏之前，谁愿意多花时间呢？
OpenSpec：规范驱动开发的答案

HagiCode 选择 OpenSpec 作为解决方案，核心思路是：所有代码变更必须通过结构化的提案流程，把抽象的想法转化为可执行的实施计划。
这话说得挺高大上的，其实就是让 AI 在写代码之前，先把需求文档写好罢了。毕竟凡事预则立，不预则废，古人诚不我欺。
什么是 OpenSpec

OpenSpec 是一个基于 npm 的命令行工具（@fission-ai/openspec），它定义了一套标准的提案文件结构和验证机制。简单说，就是让 AI 在写代码之前，先"写好需求文档"。
三步流程防幻觉

OpenSpec 通过一个三步流程来确保提案质量：
Step 1：初始化提案 - 设置会话状态为 Openspecing
Step 2：中间处理 - 保持 Openspecing 状态，逐步完善工件
Step 3：完成提案 - 转换到 Reviewing 状态
这个设计有个很巧妙的细节：第一步使用的是 ProposalGenerationStart 类型，完成后不会触发状态转换。这确保了整个多步流程完成前，不会过早进入审查阶段。
其实这个细节也挺有意思的，就像做菜一样，火候没到就揭锅盖，肯定是什么都做不好的。只有耐心一点，一步一步来，最后才能做出一道好菜。

1. // HagiCode 项目中的实现
2. public enum MessageAssociationType
3. {
4.     ProposalGeneration = 2,
5.     ProposalExecution = 3,
7.     /// <summary>
8.     /// 标记三步提案生成流程的开始
9.     /// 完成后不会转换到 Reviewing 状态
10.     /// </summary>
11.     ProposalGenerationStart = 5
12. }

复制代码

标准化的文件结构

每个 OpenSpec 提案都遵循相同的目录结构：

1. openspec/
2. ├── changes/                    # 活跃和归档的变更
3. │   ├── {change-name}/
4. │   │   ├── proposal.md        # 提案描述
5. │   │   ├── design.md          # 设计文档
6. │   │   ├── specs/             # 技术规范
7. │   │   └── tasks.md           # 可执行任务清单
8. │   └── archive/               # 归档的变更
9. └── specs/                     # 独立的规范库

复制代码

根据 HagiCode 项目的统计，目前已经有 4000+ 个归档变更和 15 万+ 行规范文件。这些历史积累不仅让 AI 有章可循，也为团队提供了宝贵的知识库。
这就像是古人留下的典籍，读多了自然就能悟出点门道来。只是现在这典籍不是写在竹简上，而是存放在文件里罢了。
多层验证机制

系统实现了多层验证来确保提案质量：

1. // 验证必需文件存在
2. ValidateProposalFiles()
4. // 验证执行前提条件
5. ValidateExecuteAsync()
7. // 验证启动条件
8. ValidateStartAsync()
10. // 验证归档条件
11. ValidateArchiveAsync()
13. // 提案名称格式验证（kebab-case）
14. ValidateNameFormat()

复制代码

这些验证就像是层层把关的守门人，只有真正合格的提案才能通过。虽然看起来繁琐，可总比让糟糕的代码进入代码库要强吧？
Prompt 模板约束

HagiCode 中的 AI 执行时使用预定义的 Handlebars 模板，这些模板包含明确的步骤指导和保护措施。比如：

• 禁止在未理解用户意图时继续
  
• 禁止生成未验证的代码
  
• 要求在名称无效时重新提供
  
• 如果变更已存在，建议使用继续命令而不是重新创建
  

这种"带着脚镣跳舞"的方式，反而让 AI 更聚焦于理解需求和生成符合规范的代码。其实约束这东西，也不一定是坏事，毕竟自由过头了就容易乱套。
实践：如何在项目中使用 OpenSpec

安装和初始化

1. npm install -g @fission-ai/openspec@1
2. openspec --version  # 验证安装

复制代码

在项目根目录会自动创建 openspec/ 文件夹结构。
这步其实也没什么好说的，安装工具嘛，大家都懂。只是记得用 @fission-ai/openspec@1 这个版本，新版本可能有坑，毕竟稳定压倒一切。
创建提案

在 HagiCode 的对话界面中，使用快捷命令：

1. /opsx:new

复制代码

或者指定变更名称和目标仓库：

1. /opsx:new "add-user-auth" --repos "repos/web"

复制代码

创建提案这事儿，就像写文章列提纲一样，有了提纲后面就好写了。只是很多人喜欢直接开始写，写到一半才发现思路不通，那才叫头疼。
生成工件

使用 /opsx:continue 逐步生成所需的工件：
proposal.md - 描述变更的目的和范围

1. # Proposal: Add User Authentication
3. ## Why
4. 当前系统缺少用户认证功能，无法保护敏感 API。
6. ## What Changes
7. - 添加 JWT 认证中间件
8. - 实现登录/注册 API
9. - 更新前端集成

复制代码

design.md - 详细的技术设计

1. # Design: Add User Authentication
3. ## Context
4. 当前使用公开 API，任何人均可访问...
6. ## Decisions
7. 1. 选择 JWT 而非 Session...
8. 2. 使用 HS256 算法...
10. ## Risks
11. - 令牌泄露风险...
12. - 缓解措施...

复制代码

specs/ - 技术规范和测试场景

1. # user-auth Specification
3. ## Requirements
5. ### Requirement: JWT Token Generation
6. 系统 SHALL 使用 HS256 算法生成 JWT 令牌。
8. #### Scenario: Valid login
9. - WHEN 用户提供有效凭据
10. - THEN 系统 SHALL 返回有效的 JWT 令牌

复制代码

tasks.md - 可执行的任务清单

1. # Tasks: Add User Authentication
3. ## 1. Backend Changes
4. - [ ] 1.1 创建 AuthController
5. - [ ] 1.2 实现 JWT 中间件
6. - [ ] 1.3 添加单元测试

复制代码

这些工件其实就像是写文章的草稿，草稿写好了，正文自然就顺畅了。只是很多人不喜欢写草稿，觉得浪费时间，可实际上草稿才是最能理清思路的地方。
审查和应用

完成所有工件后：

1. /opsx:apply

复制代码

AI 会读取所有上下文文件，按照 tasks.md 中的清单逐步执行任务。这时候因为有了清晰的规范，生成的代码质量会高很多。
其实到了这一步，事情就已经成了一半了。有了明确的任务清单，剩下的就是按部就班地执行罢了。只是很多人跳过了前面的步骤，直接到这里，那质量自然就难以保证了。
归档

变更完成后：

1. /opsx:archive

复制代码

将完成的变更移动到 archive/ 目录，方便以后查阅和复用。
归档这事儿挺重要的，就像把写完的文章好好收起来一样。以后遇到类似的问题，翻一翻以前的记录，可能就有答案了。只是很多人懒得做，觉得麻烦，可实际上这些积累才是最宝贵的财富。
注意事项和最佳实践

提案命名规范

使用 kebab-case 格式，以字母开头，仅包含小写字母、数字和连字符：

• ✅ add-user-auth
  
• ❌ AddUserAuth
  
• ❌ add--user-auth
  

命名规范这东西，说起来也没啥大不了的，只是统一一点总归是好的。毕竟代码这事儿， consistency 很重要，只是很多人不在意罢了。
避免常见错误

• 在三步流程的步骤 1 使用错误的类型 - 会过早转换状态
  
• 忘记在最后一步触发状态转换 - 会卡在 Openspecing 状态
  
• 跳过审查直接执行 - 应该先验证所有工件完整
  

这些错误其实都是新手容易犯的，老手自然知道怎么避免。只是新手总有变老手的一天，走了弯路也就罢了，只希望不要走太多弯路就好。
多变更管理

OpenSpec 支持同时管理多个提案，这在处理大型功能时特别有用：

1. # 查看所有活动变更
2. openspec list
4. # 切换到特定变更
5. openspec apply "add-user-auth"
7. # 查看变更状态
8. openspec status --change "add-user-auth"

复制代码

多变更管理这事儿，就像同时写几篇文章一样，需要一点技巧和耐心。只是习惯了就好了，毕竟人嘛，总能适应的。
会话状态机理解

了解状态转换有助于排查问题：

1. Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → Archived

复制代码

• Openspecing：生成规划中
  
• Reviewing：审查中（可反复修改工件）
  
• Executing：执行中（应用 tasks.md）
  

状态机这东西，说白了就是一套规则。规则这东西，有时候挺烦人的，但更多时候是有用的。毕竟没有规矩不成方圆，这话古人早就说过了。
总结

通过 OpenSpec 流程，HagiCode 项目在解决 AI 幻觉问题上取得了显著效果：

• 减少幻觉 - AI 必须遵循结构化规范，不能随意生成代码
  
• 提高质量 - 多层验证确保变更符合项目标准
  
• 加速协作 - 归档的变更为后续开发提供参考
  
• 可追溯性 - 每个变更都有完整的提案、设计、规范和任务记录
  

这套方案不是让 AI 变聪明，而是给它套上"规范"的笼子。实践证明，带着脚镣跳舞，反而跳得更好。
其实这道理也简单，约束不一定是什么坏事。就像写文章，有了格式的约束，反而更容易写出好东西来。只是很多人不喜欢约束，觉得限制了自己的创造力，可实际上创造力也需要土壤才能开花结果。
如果你也在使用 AI 编程助手，并且遇到过类似的问题，不妨试试 OpenSpec。规范驱动开发可能看起来多了一些步骤，但这些前期投入会在代码质量和维护效率上得到数倍的回报。
毕竟，慢一点，有时候反而是快一点。只是很多人不明白这个道理罢了......
参考资料

• OpenSpec npm 包：www.npmjs.com/package/@fission-ai/openspec
  
• HagiCode 项目地址：github.com/HagiCode-org/site
  
• HagiCode 官网：hagicode.com
  
• 观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
  
• Docker Compose 一键安装：docs.hagicode.com/installation/docker-compose
  
• Desktop 桌面端快速安装：hagicode.com/desktop/
  

如果本文对你有帮助，欢迎来 GitHub 给个 Star。HagiCode 公测已开始，现在安装即可参与体验。
这文章写得也差不多了，其实也没什么特别高深的东西，只是把一些实践经验总结了一下罢了。希望对大家有用，毕竟分享这东西，自己学到了，也让别人学到了，两全其美，何乐而不为呢？
只是文章终究是文章，真正有用的还是实践。毕竟纸上得来终觉浅，绝知此事要躬行，古人诚不我欺......
原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
  
• 原文链接: https://docs.hagicode.com/go?platform=cnblogs&target=%2Fblog%2F2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development%2F
  
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！