用AI寫代碼,需求改10次錯9次?這個方法讓我返工率降75%

作者：賽洛xAI

日期：2025年10月22日上午10:01

來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點高亮

OpenSpec 幫你鎖死需求，AI 編程返工率即降 75%

整理版摘要

呢篇文章係一個叫賽洛嘅開發者分享嘅真實經驗。佢本身用 Cursor 做 AI 編程，成日遇到產品經理改完需求之後 AI 亂改代碼、功能越改越錯嘅問題，試過通宵 Debug 好崩潰。佢嘅核心困擾係：口頭同 AI 溝通需求，就好似「口頭傳話起樓」——今日話砌牆，聽日話開窗，後日又想改門，AI 根本記唔到之前講過乜，每次新需求都當新任務，成日互相衝突。

為咗解決呢個問題，佢用咗一個叫 OpenSpec 嘅工具。個概念好簡單：寫代碼之前，先創建一份規格文件（Spec），將所有需求、功能細節、邊界條件寫清楚。AI 每次改代碼都要參考呢份 Spec，唔會亂改。結果用咗一個月，需求返工率由 60% 降到 15%，同產品經理溝通成本減少 83%，仲慳咗 3 個通宵。

文章詳細講解咗點樣用 OpenSpec 嘅五個步驟：創建提議、審查提議、迭代完善、實施變更、歸檔完成。同時提醒咗三個容易踩嘅坑：Node 版本要 >=20.19.0、初始化後要重啟 AI 工具、Spec 要寫得夠詳細連邊界情況都包。最後仲列舉咗 OpenSpec 最適合嘅場景：改舊項目、需求常變、團隊協作、需要可追溯性。總括嚟講，呢篇文章係一個實戰型嘅工具使用指南，對成日用 AI 寫代碼嘅開發者好有參考價值。

OpenSpec 透過寫規範文件（Spec）鎖死需求，返工率由 60% 降至 15%，溝通成本減 83%。
核心方法：先畫設計圖（Spec），再動工，避免 AI 亂改舊功能。
同傳統口頭溝通相比，Spec 提供咗可追溯嘅需求記錄，唔會再出現「你明明話係……」嘅爭拗。
Spec 要寫得詳細，包含正常情況、邊界情況同無結果情況，越細越好。
實戰步驟：創建提議 → 審查提議 → 迭代完善 → 實施變更 → 歸檔，熟練後每次只需 5 分鐘。

結構示例

內容片段

內容片段 cs

你： "幫我創建一個 OpenSpec 變更提議。功能是：在用戶資料頁面添加搜索過濾器，可以按角色和團隊篩選用戶"
AI： "好的！我來幫你創建提議..."
    [AI會自動創建以下文件]
    ✓ openspec/changes/add-profile-filters/proposal.md
    ✓ openspec/changes/add-profile-filters/tasks.md
    ✓ openspec/changes/add-profile-filters/specs/profile/spec.md
你： [看一下AI創建的文件，檢查是否符合預期]

整理重點

AI 寫 Code 嘅痛：需求改 10 次錯 9 次

作者用 Cursor 做用戶管理功能，產品半夜加咗個「按角色篩選」需求，AI 改完之後，「部門篩選」竟然報錯。呢啲情況唔係 AI 蠢，而係佢冇辦法記住成個項目嘅上下文。

整理重點

OpenSpec 點樣解決問題？

OpenSpec 嘅核心概念係：在寫代碼之前，先用 Spec 文件鎖死需求。

呢個工具幫你創建一個規格說明書，將所有功能細節、邊界條件、使用場景都寫清楚。AI 每次改代碼都會參考呢份 Spec，唔會再忘記之前嘅約定。

流程係：提議 → 審查 → 迭代 → 實施 → 歸檔。

整理重點

實戰教學：五步搞掂一個功能

步驟 1：創建提議 — AI 會自動生成 proposal.md（計劃書）、tasks.md（任務清單）、specs/（規格詳細）。
步驟 2：審查提議 — 打開 files 睇下有冇漏任務，spec 係咪清楚。可以用 openspec validate 驗證格式。
步驟 3：迭代完善 — 不斷同 AI 修改 spec，加埋邊界情況，例如「選擇全部角色時顯示所有用戶」「搜尋無結果時顯示提示」。
步驟 4：實施變更 — 確認 spec 冇問題後，叫 AI 開工。佢會按 tasks.md 逐項完成，並打勾標記。
步驟 5：歸檔完成 — 用 openspec archive 或叫 AI 歸檔，將完成嘅變更移到 archive/ 並更新主 spec 文件。

歸檔之後，openspec/specs/ 會包含最新功能描述，changes/ 保持乾淨，archive/ 留低歷史記錄，方便日後追溯。

整理重點

三個最常踩嘅坑

1 Node 版本問題：裝 OpenSpec 前一定要 check node --version >= 20.19.0，否則會報錯。
2 初始化後冇重啟 AI 工具：init 完之後必須重啟 Cursor 等工具，斜槓命令先會顯示。
3 Spec 寫得太粗糙：一定要將邊界情況寫清楚，唔好剩係寫「用戶可以過濾」，要寫埋「選擇角色後點樣」「冇結果點樣」「重置點樣」。

寫 Spec 嘅好例子：場景 1 正常情況、場景 2 無結果、場景 3 重置。

作者親身經驗：Spec 越詳細，AI 寫代碼越準確，後期修改越少。

整理重點

一個月實戰數據：返工率跌 75%

OpenSpec 特別適合：改舊項目、需求經常變、團隊協作、需要可追溯性嘅場景。只要你用 AI 寫代碼，呢個工具都值得一試。

講真，我而家諗返上個月嗰個通宵夜晚，都仲係覺得好崩潰。

嗰晚11點，我用Cursor做一個用戶管理功能。需求好明確：加個按部門篩選用戶嘅下拉box。AI三兩下手勢寫完code，我一測，功能正常，心諗今日可以早啲收工。

點知產品經理突然喺group度@我："喂，篩選功能使唔使再加個按角色過濾？"

好la，我又同AI講多次。佢開始改code，我去斟杯水返嚟，發現啱啱仲好地地嘅「部門篩選」功能居然報錯。我即刻叫AI整返，佢整係整好咗，但「角色篩選」又冇咗...

就係咁樣來回搞咗2個鐘。你有冇試過類似嘅經驗？

後來我發現咗OpenSpec。用咗一個月，需求返工率由60%直降到15%，同產品經理溝通成本減少咗83%。最爽係，以後唔使再通宵改bug。

早用早享受，我今個月已經慳返3個通宵。

OpenSpec到底做咗啲乜？

簡單講：喺寫code之前，先鎖死需求。

以前我哋同AI傾需求，就好似口頭傳話起樓——今日話砌牆，聽日話開窗，後日又想改門嘅位置，工人(AI)全程矇查查。每次新需求一到，佢就將之前嘅嘢忘記得一乾二淨。

OpenSpec嘅做法係：先畫設計圖，再開工。將所有需求、功能細節、邊界條件都寫喺Spec文件(規格說明書)度。AI每次寫code都會參考呢個文件，唔會東一忽西一忽。

聽落好簡單啫？但就係咁簡單嘅思路，可以慳返一大半浪費時間嘅溝通。

一步一步教你第一次用

我哋做個真實嘅例子：俾網站加一個「用戶資料搜索過濾器」功能

💡 新手提示：下面嘅步驟會比較詳細，唔好心急。第一次可能需要20-30分鐘，熟咗之後只需要5分鐘。

準備功夫：安裝OpenSpec

首先檢查Node版本，呢個千祈唔好忽略：

node --version  # 必須 >= 20.19.0

然後全局安裝：

npm install -g @fission-ai/openspec@latest

在項目目錄裏初始化：

cd your-project
openspec init

會彈出一個嚮導，問你用邊款AI工具。我用Cursor，就揀咗Cursor。

重點：initialize完一定要重啟你嘅AI工具！斜槓命令係啟動時加載嘅，唔重啟係見唔到㗎。

步驟 1：創建提議 (好似寫計劃書)

直接同AI講 (推薦新手)：

你： "幫我創建一個 OpenSpec 變更提議。功能是：在用戶資料頁面添加搜索過濾器，可以按角色和團隊篩選用戶"
AI： "好的！我來幫你創建提議..."
    [AI會自動創建以下文件]
    ✓ openspec/changes/add-profile-filters/proposal.md
    ✓ openspec/changes/add-profile-filters/tasks.md
    ✓ openspec/changes/add-profile-filters/specs/profile/spec.md
你： [看一下AI創建的文件，檢查是否符合預期]

或者用斜槓命令 (如果你嘅AI工具支援)：

/openspec：proposal Add profile search filters by role and team

⚠️ 新手好易卡喺度：
問：AI冇自動創建文件點算？
答：確保你項目入面已經有 openspec/AGENTS.md 文件(initialize時創建嘅)。然後清楚話俾AI知：「請跟OpenSpec工作流創建變更提議」
問：AI創建嘅文件喺邊？
答：喺你項目目錄下面，openspec/changes/ 文件夾入面。用文件瀏覽器睇，或者行 ls openspec/changes/

步驟 2：審查提議 (檢查AI寫得對唔對)

# 查看變更列表
openspec list
# 輸出示例：
# Active Changes：
# ├── add-profile-filters (3 specs， 5 tasks)

呢步做咩？
你需要打開AI創建嘅文件，仔細睇下
proposal.md
- 睇下AI明唔明你嘅需求？
tasks.md
- 需要做嘅嘢列曬未？
specs/profile/spec.md
- 功能描述清楚未？

實際檢查例子：

你： [打開 openspec/changes/add-profile-filters/tasks.md]
    "嗯...這裏少了一個任務：需要給過濾器添加重置按鈕"
AI： "好的，我加上這一條"
    ✏️ 更新 tasks.md，添加：
    - [ ] 1.4 添加"重置過濾器"按鈕
你： [打開 specs/profile/spec.md]
    "specs裏要不要加個場景：同時選擇多個團隊過濾？"
AI： "好主意！我補充到specs裏"
    ✏️ 更新 specs/profile/spec.md

驗證格式係咪正確：

openspec validate add-profile-filters
# 如果看到： ✓ All specs are valid
# → 說明格式沒問題！

常見驗證錯誤：
錯誤：「Missing Scenario for Requirement」
意思：有個Requirement(需求)下面冇寫Scenario(場景例子)
點做：叫AI補充一個具體嘅使用場景
錯誤：「Invalid Delta format」
意思：Delta文件入面嘅ADDED/MODIFIED/REMOVED格式錯咗
點做：檢查係咪寫錯成ADD/MODIFY/REMOVE(少咗ED)

步驟 3：迭代完善 (來回修改，直到滿意)

你： "能否為角色過濾器添加'全部角色'這個選項？"
AI： "可以！我更新規範..."
    [AI 編輯 specs/profile/spec.md]
    ✓ 添加 Scenario： "選擇全部角色時顯示所有用戶"
你： "再加個場景：如果搜索結果為空怎麼辦？"
AI： "好的"
    ✓ 添加 Scenario： "過濾器組合後無結果時，顯示'未找到匹配用戶'"
你： "看起來不錯了，就這樣吧"

呢個階段嘅目的：
將功能嘅細節都想清楚
確保AI同你理解一致
喺度花時間係值得嘅，後面寫code會快好多

步驟 4：實施變更 (AI開始開工)

你： "規範確認沒問題了，開始實施吧"
AI： "收到！我按 tasks.md 的清單來做"
    ✓ Task 1.1： 添加角色過濾器UI組件 → 完成
    ✓ Task 1.2： 添加團隊過濾器UI組件 → 完成
    ✓ Task 1.3： 更新搜索API端點 → 完成
    ✓ Task 1.4： 添加"重置過濾器"按鈕 → 完成
    ✓ Task 2.1： 添加過濾器驗證邏輯 → 完成
    ✓ Task 3.1： 添加單元測試 → 完成
你： "測試一下功能...嗯，工作正常！"

或者用斜槓命令觸發 (一鍵完成所有任務)：

/openspec：apply add-profile-filters

AI實施時做咗啲乜？
打開 tasks.md，當佢係待辦清單
參考 specs/ 入面嘅需求同場景，知道要實現咩效果
逐個完成任務，寫code、改文件
在 tasks.md 入面打勾標記完成
你嘅角色：監督AI，測試功能，發現問題就叫AI修

如果AI做錯咗點算？
場景：AI實現嘅過濾邏輯唔啱
唔好：直接叫AI重寫code
應該：先返去 specs.md，檢查需求寫清楚未
你："等等，這個過濾邏輯不對。我再看看specs..."
[發現specs裏沒寫清楚'角色'和'團隊'是AND還是OR邏輯]

你："我需要先改一下specs。角色是單選(AND)，團隊是多選(OR)"

AI："明白了，我更新specs，然後重新實現這部分代碼"

步驟 5：歸檔完成嘅變更 (收尾功夫)

# 方式1：手動歸檔
openspec archive add-profile-filters --yes
# 方式2：讓AI執行
你： "請歸檔這個變更"
AI： [運行歸檔命令]
   ✓ Delta已合併到 specs/profile/spec.md
   ✓ 變更已移至 archive/add-profile-filters/
   ✓ 歸檔完成！

歸檔後發生了什麼？

之前：
openspec/
├── specs/
│   └── profile/spec.md (舊版本，沒有過濾器)
├── changes/
│   └── add-profile-filters/ (提議和Delta)
└── archive/ (空)
歸檔後：
openspec/
├── specs/
│   └── profile/spec.md (✨新版本，包含過濾器需求)
├── changes/ (空，或其他進行中的變更)
└── archive/
    └── add-profile-filters/ (📦完整的項目記錄)
        ├── proposal.md
        ├── tasks.md
        └── specs/...

點解要歸檔？
更新正式規範
- specs/ 而家包含最新嘅功能描述
清理工作區
- changes/ 保持整潔，只放進行中嘅項目
保留歷史
- archive/ 入面查到「當時點解要咁做」
就好似做完功課交俾老師(歸檔)，老師會將你嘅功課放入檔案櫃(archive)，同時更新你嘅成績單(specs)

🎉 恭喜！你完成咗第一個OpenSpec變更。

你學識咗：

✅ 點樣創建提議(同AI一齊規劃)

✅ 點樣審查同完善規範(確保理解一致)

✅ 點樣實施變更(AI按規範寫code)

✅ 點樣歸檔(更新知識庫)

下一步：重複呢個流程，開發更多功能。會越來越熟練㗎！

三個最容易中招嘅位

坑1： Node版本問題 - 安裝之前一定要確認Node >= 20.19.0

坑2： initialize後唔重啟 - init完一定要重啟AI工具，如果唔係見唔到斜槓命令

坑3： Spec寫得太粗糙 - 要將各種邊界情況都寫清楚，越詳細越好

✅ 好的寫法：
場景1：正常情況 - 用戶選擇角色"開發者"，團隊"前端組"，顯示2個匹配用戶
場景2：無結果 - 用戶選擇角色"設計師"，團隊"後端組"，顯示"未找到匹配用戶"
場景3：重置 - 用戶點擊"重置過濾器"按鈕，所有過濾器清空，顯示全部用戶
❌ 不好的寫法：
用戶可以過濾搜索結果

數據說話：我真實嘅體驗

用咗OpenSpec一個月後，我專登統計咗效果：

最後一條係我最滿意嘅——同產品經理拗數嘅時間減少咗80%！

因為有咗spec文件，需求變更都有記錄，邊個改咗啲咩一目瞭然。以後唔使再拗「你當時明明話係...」

前幾日產品又嚟改需求，我直接掟咗個連結俾佢，清楚寫明係「按部門篩選」，你而家要改成「按崗位篩選」，呢個係新需求，要重新評估工時。

產品睇完，靜靜咁話：「咁...都係下個版本先啦。」

爽！

邊個最需要OpenSpec？

如果你遇到呢啲情況，OpenSpec可以幫大忙：

改舊項目
- 唔會將新舊需求溝埋一齊
需求成日變
- 改spec文件比起揾聊天記錄方便
團隊協作
- 唔同AI工具都可以睇同一份spec
需要可追溯性
- 完整記錄每個功能嘅決定過程

講真，只要你用緊AI寫code，OpenSpec都值得一試。第一次可能需要20-30分鐘摸索，但熟咗之後真係只需要5分鐘。

講下你嘅睇法

我分享咗我真實嘅體驗，而家想聽聽你嘅諗法：

你喺用AI寫程式嗰陣遇過啲咩問題？ 有冇類似嘅工具推薦？

喺留言區寫低，話唔定可以幫到其他正在中招嘅朋友！

如果呢篇文章救咗你一個通宵：

按個👍🏻，等更多人睇到。留言區講下你俾AI陰過幾次。轉俾啲用緊AI寫code嘅朋友。

項目地址： https://github.com/Fission-AI/OpenSpec

官網： https://openspec.dev/

想睇更多AI寫程式技巧？關注我，每星期分享AI工具~

我是賽洛，一個喺AI寫程式路上跌跌撞撞嘅🐂🐴。

說實話，我現在回想起上個月那個通宵夜晚，還是覺得挺崩潰的。

那天晚上11點，我用Cursor做一個用戶管理功能。需求很明確：加個按部門篩選用戶的下拉框。AI三下五除二把代碼寫完了，我一測，功能正常，心想今天能早點下班。

結果產品經理突然在羣裏@我："對了，篩選功能要不要再加個按角色過濾？"

行吧，我又跟AI說了一遍。它開始改代碼，我去倒了杯水回來，發現剛才好好的"部門篩選"功能居然報錯了。我趕緊讓AI修，它修是修好了，但"角色篩選"又沒了...

就這樣來回折騰了2個小時。你有沒有過類似經歷？

後來我發現了OpenSpec。用了一個月，需求返工率從60%直降到15%，和產品經理溝通成本減少了83%。最爽的是，再也不用通宵改bug了。

早用早爽，我這個月已經省出3個通宵了。

OpenSpec到底幹了啥？

簡單來說：在寫代碼之前，先把需求鎖死。

以前我們跟AI聊需求，就像口頭傳話蓋房子——今天說砌牆，明天說開窗，後天又想改門的位置，工人(AI)全程懵逼。每次新需求一來，它就把之前的忘得一乾二淨。

OpenSpec的做法是：先畫設計圖，再動工。把所有需求、功能細節、邊界條件都寫在Spec文件(規格說明書)裏。AI每次寫代碼都參考這個文件，不會東一榔頭西一棒子。

聽起來很簡單對吧？但就這麼個簡單的思路，能省下一大半扯皮的時間。

手把手教你第一次使用

我們來做個真實的例子：給網站加一個"用戶資料搜索過濾器"功能

💡 新手提示：下面的步驟會比較詳細，不要着急。第一次可能需要20-30分鐘，熟悉後只需要5分鐘。

準備工作：安裝OpenSpec

首先檢查Node版本，這個千萬別忽略：

node --version  # 必須 >= 20.19.0

然後全局安裝：

npm install -g @fission-ai/openspec@latest

在項目目錄裏初始化：

cd your-project
openspec init

會彈出一個嚮導，問你用的啥AI工具。我用Cursor，就選了Cursor。

重點：初始化完必須重啓你的AI工具！斜槓命令是啓動時加載的，不重啓根本看不到。

步驟 1：創建提議 (就像寫計劃書)

直接和AI對話 (推薦新手)：

你： "幫我創建一個 OpenSpec 變更提議。功能是：在用戶資料頁面添加搜索過濾器，可以按角色和團隊篩選用戶"
AI： "好的！我來幫你創建提議..."
    [AI會自動創建以下文件]
    ✓ openspec/changes/add-profile-filters/proposal.md
    ✓ openspec/changes/add-profile-filters/tasks.md
    ✓ openspec/changes/add-profile-filters/specs/profile/spec.md
你： [看一下AI創建的文件，檢查是否符合預期]

或者使用斜槓命令 (如果你的AI工具支持)：

/openspec：proposal Add profile search filters by role and team

⚠️ 新手容易卡在這裏：
問：AI沒有自動創建文件怎麼辦？
答：確保你項目裏已經有 openspec/AGENTS.md 文件(初始化時創建的)。然後明確告訴AI："請按照OpenSpec工作流創建變更提議"
問：AI創建的文件在哪裏？
答：在你的項目目錄下，openspec/changes/ 文件夾裏。用文件瀏覽器查看，或運行 ls openspec/changes/

步驟 2：審查提議 (檢查AI寫得對不對)

# 查看變更列表
openspec list
# 輸出示例：
# Active Changes：
# ├── add-profile-filters (3 specs， 5 tasks)

這一步在幹什麼？
你需要打開AI創建的文件，仔細看看
proposal.md
- 看看AI理解你的需求了嗎？
tasks.md
- 需要做的事情列全了嗎？
specs/profile/spec.md
- 功能描述清楚了嗎？

實際檢查示例：

你： [打開 openspec/changes/add-profile-filters/tasks.md]
    "嗯...這裏少了一個任務：需要給過濾器添加重置按鈕"
AI： "好的，我加上這一條"
    ✏️ 更新 tasks.md，添加：
    - [ ] 1.4 添加"重置過濾器"按鈕
你： [打開 specs/profile/spec.md]
    "specs裏要不要加個場景：同時選擇多個團隊過濾？"
AI： "好主意！我補充到specs裏"
    ✏️ 更新 specs/profile/spec.md

驗證格式是否正確：

openspec validate add-profile-filters
# 如果看到： ✓ All specs are valid
# → 說明格式沒問題！

常見驗證錯誤：
錯誤："Missing Scenario for Requirement"
意思：有個Requirement(需求)下面沒寫Scenario(場景例子)
怎麼辦：讓AI補充一個具體的使用場景
錯誤："Invalid Delta format"
意思：Delta文件裏的ADDED/MODIFIED/REMOVED格式不對
怎麼辦：檢查是不是寫錯成了ADD/MODIFY/REMOVE(少了ED)

步驟 3：迭代完善 (來回修改，直到滿意)

你： "能否為角色過濾器添加'全部角色'這個選項？"
AI： "可以！我更新規範..."
    [AI 編輯 specs/profile/spec.md]
    ✓ 添加 Scenario： "選擇全部角色時顯示所有用戶"
你： "再加個場景：如果搜索結果為空怎麼辦？"
AI： "好的"
    ✓ 添加 Scenario： "過濾器組合後無結果時，顯示'未找到匹配用戶'"
你： "看起來不錯了，就這樣吧"

這個階段的目的：
把功能的細節都想清楚
確保AI和你理解一致
花時間在這裏是值得的，後面寫代碼會快很多

步驟 4：實施變更 (AI開始幹活)

你： "規範確認沒問題了，開始實施吧"
AI： "收到！我按 tasks.md 的清單來做"
    ✓ Task 1.1： 添加角色過濾器UI組件 → 完成
    ✓ Task 1.2： 添加團隊過濾器UI組件 → 完成
    ✓ Task 1.3： 更新搜索API端點 → 完成
    ✓ Task 1.4： 添加"重置過濾器"按鈕 → 完成
    ✓ Task 2.1： 添加過濾器驗證邏輯 → 完成
    ✓ Task 3.1： 添加單元測試 → 完成
你： "測試一下功能...嗯，工作正常！"

或者用斜槓命令觸發 (一鍵完成所有任務)：

/openspec：apply add-profile-filters

AI實施時做了什麼？
打開 tasks.md，把它當作待辦清單
參考 specs/ 裏的需求和場景，知道要實現什麼效果
一個個完成任務，寫代碼、改文件
在 tasks.md 裏打勾標記完成
你的角色：監督AI，測試功能，發現問題就讓AI修

如果AI做錯了怎麼辦？
場景：AI實現的過濾邏輯不對
不要：直接讓AI重寫代碼
應該：先回到 specs.md，檢查需求寫清楚了沒有
你："等等，這個過濾邏輯不對。我再看看specs..."
[發現specs裏沒寫清楚'角色'和'團隊'是AND還是OR邏輯]

你："我需要先改一下specs。角色是單選(AND)，團隊是多選(OR)"

AI："明白了，我更新specs，然後重新實現這部分代碼"

步驟 5：歸檔完成的變更 (收尾工作)

# 方式1：手動歸檔
openspec archive add-profile-filters --yes
# 方式2：讓AI執行
你： "請歸檔這個變更"
AI： [運行歸檔命令]
   ✓ Delta已合併到 specs/profile/spec.md
   ✓ 變更已移至 archive/add-profile-filters/
   ✓ 歸檔完成！

歸檔後發生了什麼？

之前：
openspec/
├── specs/
│   └── profile/spec.md (舊版本，沒有過濾器)
├── changes/
│   └── add-profile-filters/ (提議和Delta)
└── archive/ (空)
歸檔後：
openspec/
├── specs/
│   └── profile/spec.md (✨新版本，包含過濾器需求)
├── changes/ (空，或其他進行中的變更)
└── archive/
    └── add-profile-filters/ (📦完整的項目記錄)
        ├── proposal.md
        ├── tasks.md
        └── specs/...

為什麼要歸檔？
更新正式規範
- specs/ 現在包含最新的功能描述
清理工作區
- changes/ 保持整潔，只放進行中的項目
保留歷史
- archive/ 裏能查到"當時為什麼這麼做"
就像做完作業交給老師(歸檔)，老師會把你的作業放進檔案櫃(archive)，同時更新你的成績單(specs)

🎉 恭喜！你完成了第一個OpenSpec變更。

你學會了：

✅ 如何創建提議(和AI一起規劃)

✅ 如何審查和完善規範(確保理解一致)

✅ 如何實施變更(AI按規範寫代碼)

✅ 如何歸檔(更新知識庫)

下一步：重複這個流程，開發更多功能。會越來越熟練的！

三個最容易踩的坑

坑1： Node版本問題 - 裝之前務必確認Node >= 20.19.0

坑2：初始化後不重啓 - init完必須重啓AI工具，不然看不到斜槓命令

坑3： Spec寫得太粗糙 - 要把各種邊界情況都寫清楚，越細越好

✅ 好的寫法：
場景1：正常情況 - 用戶選擇角色"開發者"，團隊"前端組"，顯示2個匹配用戶
場景2：無結果 - 用戶選擇角色"設計師"，團隊"後端組"，顯示"未找到匹配用戶"
場景3：重置 - 用戶點擊"重置過濾器"按鈕，所有過濾器清空，顯示全部用戶
❌ 不好的寫法：
用戶可以過濾搜索結果

數據說話：我的真實體驗

用OpenSpec一個月後，我專門統計了一下效果：

最後一條是我最滿意的——和產品經理扯皮的時間減少了80%！

因為有了spec文件，需求變更都有記錄，誰改了什麼一目瞭然。再也不用糾結"你當時明明說的是..."

前幾天產品又來改需求，我直接甩給他一個連結，明確寫的是'按部門篩選'，你現在要改成'按崗位篩選'，這屬於新需求，得重新評估工時。"

產品看完，默默地說："那...還是下個版本再說吧。"

爽！

誰最需要OpenSpec？

如果你遇到這些情況，OpenSpec能幫大忙：

改老項目
- 不會把新舊需求攪和在一起
需求經常變
- 改spec文件比翻聊天記錄方便
團隊協作
- 不同AI工具都能看同一套spec
需要可追溯性
- 完整記錄每個功能的決策過程

說實話，只要你在用AI寫代碼，OpenSpec都值得一試。第一次可能需要20-30分鐘摸索，但熟悉後真的只需要5分鐘。

說說你的看法

我分享了我的真實體驗，現在想聽聽你的想法：

你在用AI編程時遇到過哪些坑？ 有沒有類似的工具推薦？

在評論區留言，說不定能幫到其他正在踩坑的朋友！

如果這篇文章救了你一個通宵：

點個👍🏻，讓更多人看到。評論區說說你被AI坑過幾次。轉給正在用AI寫代碼的朋友。

項目地址： https://github.com/Fission-AI/OpenSpec

官網： https://openspec.dev/

想看更多AI編程技巧？關注我，每週分享AI工具~

我是賽洛，一個在AI編程路上摸爬滾打的🐂🐴。

內容片段

AI 寫 Code 嘅痛：需求改 10 次錯 9 次

OpenSpec 點樣解決問題？

實戰教學：五步搞掂一個功能

三個最常踩嘅坑

一個月實戰數據：返工率跌 75%

一步一步教你第一次用

準備功夫：安裝OpenSpec

步驟 2： 審查提議 (檢查AI寫得對唔對)

步驟 3： 迭代完善 (來回修改，直到滿意)

步驟 4： 實施變更 (AI開始開工)

步驟 5： 歸檔完成嘅變更 (收尾功夫)

三個最容易中招嘅位

數據說話：我真實嘅體驗

邊個最需要OpenSpec？

講下你嘅睇法

手把手教你第一次使用

準備工作：安裝OpenSpec

步驟 2： 審查提議 (檢查AI寫得對不對)

步驟 3： 迭代完善 (來回修改，直到滿意)

步驟 4： 實施變更 (AI開始幹活)

步驟 5： 歸檔完成的變更 (收尾工作)

三個最容易踩的坑

數據說話：我的真實體驗

誰最需要OpenSpec？

說說你的看法

步驟 2：審查提議 (檢查AI寫得對唔對)

步驟 3：迭代完善 (來回修改，直到滿意)

步驟 4：實施變更 (AI開始開工)

步驟 5：歸檔完成嘅變更 (收尾功夫)

步驟 2：審查提議 (檢查AI寫得對不對)

步驟 3：迭代完善 (來回修改，直到滿意)

步驟 4：實施變更 (AI開始幹活)

步驟 5：歸檔完成的變更 (收尾工作)