AI 程式設計助手的幻覺問題：如何用 OpenSpec 實作規範驅動程式開發

2026年4月2日

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 型別，完成後不會觸發狀態轉換。這確保了整個多步流程完成前，不會過早進入審查階段。

其實這個細節也挺有意思的，就像做菜一樣，火候沒到就揭鍋蓋，肯定是什麼都做不好的。只有耐心一點，一步一步來，最後才能做出一道好菜。

// HagiCode 项目中的实现
public enum MessageAssociationType
{
    ProposalGeneration = 2,
    ProposalExecution = 3,

    /// <summary>
    /// 标记三步提案生成流程的开始
    /// 完成后不会转换到 Reviewing 状态
    /// </summary>
    ProposalGenerationStart = 5
}

標準化的檔案結構

每個 OpenSpec 提案都遵循相同的目錄結構：

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

根據 HagiCode 專案的統計，目前已經有 4000+ 個歸檔變更和 15 萬+ 行規範檔案。這些歷史積累不僅讓 AI 有章可循，也爲團隊提供了寶貴的知識程式庫。

這就像是古人留下的典籍，讀多了自然就能悟出點門道來。只是現在這典籍不是寫在竹簡上，而是存放在檔案裏罷了。

多層驗證機制

系統實作了多層驗證來確保提案質量：

// 验证必需文件存在
ValidateProposalFiles()

// 验证执行前提条件
ValidateExecuteAsync()

// 验证启动条件
ValidateStartAsync()

// 验证归档条件
ValidateArchiveAsync()

// 提案名称格式验证（kebab-case）
ValidateNameFormat()

這些驗證就像是層層把關的守門人，只有真正合格的提案才能透過。雖然看起來繁瑣，可總比讓糟糕的程式碼進入程式碼程式庫要強吧？

Prompt 範本約束

HagiCode 中的 AI 執行時使用預定義的 Handlebars 範本，這些範本包含明確的步驟指導和保護措施。比如：

• 禁止在未理解使用者意圖時繼續
• 禁止產生未驗證的程式碼
• 要求在名稱無效時重新提供
• 如果變更已存在，建議使用繼續命令而不是重新建立

這種”帶着腳鐐跳舞”的方式，反而讓 AI 更聚焦於理解需求和產生符合規範的程式碼。其實約束這東西，也不一定是壞事，畢竟自由過頭了就容易亂套。

實踐：如何在專案中使用 OpenSpec

安裝和初始化

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

在專案根目錄會自動建立 openspec/ 檔案夾結構。

這步其實也沒什麼好說的，安裝工具嘛，大家都懂。只是記得用 @fission-ai/openspec@1 這個版本，新版本可能有坑，畢竟穩定壓倒一切。

建立提案

在 HagiCode 的對話界面中，使用快捷命令：

/opsx:new

或者指定變更名稱和目標存放庫：

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

建立提案這事兒，就像寫文章列提綱一樣，有了提綱後面就好寫了。只是很多人喜歡直接開始寫，寫到一半才發現思路不通，那才叫頭疼。

產生工件

使用 /opsx:continue 逐步產生所需的工件：

proposal.md - 描述變更的目的和範圍

# Proposal: Add User Authentication

## Why
当前系统缺少用户认证功能，无法保护敏感 API。

## What Changes
- 添加 JWT 认证中间件
- 实现登录/注册 API
- 更新前端集成

design.md - 詳細的技術設計

# Design: Add User Authentication

## Context
当前使用公开 API，任何人均可访问...

## Decisions
1. 选择 JWT 而非 Session...
2. 使用 HS256 算法...

## Risks
- 令牌泄露风险...
- 缓解措施...

specs/ - 技術規範和測試場景

# user-auth Specification

## Requirements

### Requirement: JWT Token Generation
系统 SHALL 使用 HS256 算法生成 JWT 令牌。

#### Scenario: Valid login
- WHEN 用户提供有效凭据
- THEN 系统 SHALL 返回有效的 JWT 令牌

tasks.md - 可執行的任務清單

# Tasks: Add User Authentication

## 1. Backend Changes
- [ ] 1.1 创建 AuthController
- [ ] 1.2 实现 JWT 中间件
- [ ] 1.3 添加单元测试

這些工件其實就像是寫文章的草稿，草稿寫好了，正文自然就順暢了。只是很多人不喜歡寫草稿，覺得浪費時間，可實際上草稿纔是最能理清思路的地方。

審查和應用

完成所有工件後：

/opsx:apply

AI 會讀取所有上下文檔案，按照 tasks.md 中的清單逐步執行任務。這時候因爲有了清晰的規範，產生的程式碼質量會高很多。

其實到了這一步，事情就已經成了一半了。有了明確的任務清單，剩下的就是按部就班地執行罷了。只是很多人跳過了前面的步驟，直接到這裏，那質量自然就難以保證了。

歸檔

變更完成後：

/opsx:archive

將完成的變更移動到 archive/ 目錄，方便以後查閱和複用。

歸檔這事兒挺重要的，就像把寫完的文章好好收起來一樣。以後遇到類似的問題，翻一翻以前的記錄，可能就有答案了。只是很多人懶得做，覺得麻煩，可實際上這些積累纔是最寶貴的財富。

注意事項和最佳實踐

提案命名規範

使用 kebab-case 格式，以字母開頭，僅包含小寫字母、數字和連字符：

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

命名規範這東西，說起來也沒啥大不了的，只是統一一點總歸是好的。畢竟程式碼這事兒， consistency 很重要，只是很多人不在意罷了。

避免常見錯誤

1. 在三步流程的步驟 1 使用錯誤的型別 - 會過早轉換狀態
2. 忘記在最後一步觸發狀態轉換 - 會卡在 Openspecing 狀態
3. 跳過審查直接執行 - 應該先驗證所有工件完整

這些錯誤其實都是新手容易犯的，老手自然知道怎麼避免。只是新手總有變老手的一天，走了彎路也就罷了，只希望不要走太多彎路就好。

多變更管理

OpenSpec 支援同時管理多個提案，這在處理大型功能時特別有用：

# 查看所有活动变更
openspec list

# 切换到特定变更
openspec apply "add-user-auth"

# 查看变更状态
openspec status --change "add-user-auth"

多變更管理這事兒，就像同時寫幾篇文章一樣，需要一點技巧和耐心。只是習慣了就好了，畢竟人嘛，總能適應的。

會話狀態機理解

瞭解狀態轉換有助於排查問題：

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

• Openspecing：產生規劃中
• Reviewing：審查中（可反覆修改工件）
• Executing：執行中（應用 tasks.md）

狀態機這東西，說白了就是一套規則。規則這東西，有時候挺煩人的，但更多時候是有用的。畢竟沒有規矩不成方圓，這話古人早就說過了。

總結

透過 OpenSpec 流程，HagiCode 專案在解決 AI 幻覺問題上取得了顯著效果：

1. 減少幻覺 - AI 必須遵循結構化規範，不能隨意產生程式碼
2. 提高質量 - 多層驗證確保變更符合專案標準
3. 加速協作 - 歸檔的變更爲後續開發提供參考
4. 可追溯性 - 每個變更都有完整的提案、設計、規範和任務記錄

這套方案不是讓 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/blog/2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development/
• 著作權宣告: 本博客所有文章除特別宣告外,均採用 BY-NC-SA 許可通訊協定。轉載請註明出處!

Tags:

• AI 编程
• OpenSpec
• 规范驱动开发
• HagiCode
• 开发流程

如何安裝和使用 Hermes：從本地 CLI 到 Feishu 接入快速上手