拯救老項目！比Cursor更細、比spec-kit更輕：OpenSpec如何顛覆AI編程工作流？

作者：AI 博物院
日期：2025年10月21日 上午8:00
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

OpenSpec：輕量規範驅動開發工具，專為已有項目嘅AI編程提升精確度與可追溯性

整理版摘要

作者用AI寫code時成日遇到AI誤解意圖，輸出好隨意，要自己逐個修正。佢試過spec-kit、BMAD-METHOD呢類強調規範驅動開發嘅工具，但理念好，實際用起嚟唔夠順暢，而且佢哋更適合由零開始嘅項目。喺公司真實環境，多數項目都係喺現有code base上面開發新功能或者重構，唔係由頭起。

直到最近，作者發現咗一個更輕量、更實用嘅新項目：OpenSpec。相比Cursor嘅Plan模式，OpenSpec更細緻、結構更清晰；相比spec-kit，佢又輕好多，好適合個人開發者同小團隊。OpenSpec增加咗一個規範驅動工作流程：你唔需要喺chat入面解釋功能，而係撰寫提案、一齊審查調整、等AI執行已批准嘅計劃，最後將變更歸檔，更新項目規範。核心分成兩部分：specs記錄當前規範狀態，changes追蹤每一次變更。

文章詳細示範咗由安裝、初始化、用自然語言或命令行生成變更提案，到最後執行任務同歸檔嘅完整流程。歸檔機制特別重要，確保specs永遠係最新狀態，避免新同事或者AI混淆。作者總結話「AI編程唔單止係寫code，更加係定義規則、執行規範嘅過程」，由簡單任務執行轉變為以規範為中心嘅智能協作。

  • OpenSpec專為已有項目設計，透過提案-審查-實施-歸檔流程，大幅提升AI編程嘅精確度同可追溯性。
  • 相比Cursor Plan更細緻，相比spec-kit更輕量，學習成本低，適合個人開發者同小團隊。
  • 初始化會自動生成project.md同AGENTS.md，令AI快速理解項目背景、技術棧同程式規範。
  • 變更提案包含proposal.md（點解做、做咩）、tasks.md（逐項任務）、spec.md（用ADDED/MODIFIED/REMOVED標記），仲可以多輪修改。
  • 歸檔命令會將完成嘅變更加入archive，同時合併spec.md，確保specs永遠反映系統最新狀態，避免資訊不一致。
整理重點

從問題到方案：OpenSpec嘅誕生

作者用AI寫code時最常遇到嘅困擾，唔係AI寫唔出code，而係佢寫得太隨意——有時誤解意圖，有時實現邏輯唔清晰，最終要自己逐個修正。

試過spec-kit、BMAD-METHOD呢類強調規範驅動開發嘅工具

但呢啲工具理念雖好，實際使用唔夠順暢，而且更適合由零啟動嘅項目。

公司實際環境多數係喺現有code base上開發新功能或重構

直到發現OpenSpec，一個更輕量、更實用嘅新項目。

整理重點

工作流核心：提案、審查、執行、歸檔

OpenSpec增加咗一個規範驅動工作流程，你唔需要喺chat入面解釋功能，而係：

  1. 1 撰寫（或讓AI起草）提案（Draft Change Proposal）。
  2. 2 共同審查並調整規範（Review & Align）。
  3. 3 讓AI執行已批准嘅計劃（Implement Tasks）。
  4. 4 將變更歸檔，更新項目規範（Archive & Update Specs）。

核心分成specs（記錄當前規範狀態）同changes（追蹤每一次變更）

specs記錄項目規則、API約束、模塊定義等；changes保存每次變更提案及其實施過程。

整理重點

實戰示範：由安裝到歸檔

npm install -g @fission-ai/openspec

初始化現有項目，可以選擇用嘅AI Coding工具：Claude Code、Cursor、Windsurf等。

程式內容 plaintext 
openspec/
  ├── specs/     # 已實現功能
  ├── changes/   # 正在開發功能
  ├── AGENTS.md  # AI工作流指南
  └── project.md # 項目整體上下文

project.md包含Purpose、Tech Stack、Project Conventions等，係AI理解項目嘅入口

用自然語言或命令行生成變更提案：

/openspec:proposal 我想增加一個api，用於導出RecommendRecord成CSV

會產生以下文件：

  • proposal.md：點解做、做咩、影響範圍
  • tasks.md：逐條可勾選嘅實施任務，分Phase
  • specs/xxx/spec.md：用ADDED/MODIFIED/REMOVED標記需求

可以反覆同AI交流修改提案，直到滿意

執行 /openspec:archive 歸檔：移動changes到archive，合併spec.md到主spec目錄。

整理重點

歸檔嘅價值：AI同團隊嘅單一事實來源

假設冇歸檔：第1周加咗登錄功能，第2周加咗密碼重置，第3周加咗2FA，但specs/auth/spec.md仲係3周前嘅舊規範，唔包含任何新功能。

新同事入職睇specs會以為系統得基礎認證

AI助手會困惑：「系統未有登錄功能，需要先實現嗎？」

  • 新同事入職：睇specs就知系統有登錄、密碼重置、2FA，唔使周圍揾。
  • AI助手準確理解：喺已有登錄基礎上加註銷，唔會重複實現。
整理重點

總結：AI編程嘅未來係規範協作

AI編程唔只係寫code，更加係定義規則、執行規範嘅過程

OpenSpec讓我重新理解「AI參與開發」嘅意義——由簡單任務執行，轉變為以規範為中心嘅智能協作。

背景

我喺用AI開發嗰陣，最成日遇到嘅煩惱唔係「AI寫唔出碼」，而係佢寫出嚟嘅碼太隨意——有時誤解咗我嘅意思，有時俾嘅實現邏輯唔夠清晰，最後焗住要我逐個改返好。

之後，我試過好似 spec-kit、BMAD-METHOD 呢類強調「規範驅動開發」嘅工具。理念係好，實際用起嚟就唔係咁順暢，而且佢哋更適合由零開始嘅項目。但喺公司實際環境入面，大部分項目唔係從頭搞起，更多情況係喺現有代碼基礎上開發新功能或者重構舊模塊。

直到最近，我發現咗一個更輕量、亦都更實用嘅新項目：OpenSpec。

相比 Cursor 嘅 Plan 模式，OpenSpec 更細緻、結構更清晰；相比 spec-kit，佢又輕好多，好適合個人開發者同小團隊用。

同其他工具對比

工具
適用場景
特點
spec-kit
由 0 到 1 嘅系統搭建
結構化強、上手複雜
BMAD-METHOD
團隊協作型 AI 項目
自動化程度高、學習曲線陡峭
OpenSpec
現有項目嘅功能演進同維護
輕量、兼容性強、適合個體開發者

尤其喺需要修改現有功能或牽涉多個模塊規範嗰陣，OpenSpec 嘅變更分組同追溯機制好實用。

工作流程同核心理念

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

OpenSpec 加咗一個規範驅動嘅工作流程。

你唔需要喺對話入面解釋某個功能，然後期望 AI 會正確理解，而係：

  • 撰寫（或者叫 AI 起草）提案。
  • 一齊審查同調整規範。
  • 叫 AI 執行已批准嘅計劃。
  • 將變更歸檔，用嚟更新你嘅項目規範。

佢嘅核心邏輯分做兩部分：

  • specs：記錄當前嘅規範狀態（項目規則、API 約束、模塊定義等）

  • changes：追蹤每一次變更提案同實施過程

AI 執行順序

1. 讀取 proposal.md
   → 理解"為什麼要做"、"做什麼"

2. 讀取 design.md (如果存在)
   → 理解"如何做"、"技術決策"
   → 瞭解架構選擇和權衡

3. 讀取 tasks.md
   → 獲取實現清單

4. 開始實現
   → 按照 design.md 中的決策編寫代碼

實操流程

OpenSpec 支援命令行同自然語言兩種交互方式，而且支援多款 AI Coding 工具：

工具
Claude Code
Cursor
Factory Droid
OpenCode
Kilo Code
Windsurf
Codex
GitHub Copilot
Amazon Q Developer
Auggie (Augment CLI)

安裝同初始化流程好簡單：

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

初始化你現有嘅項目，初始化期間你可以揀你會用嘅 AI Coding 工具

cd your_project
openspec init

初始化之後會生成以下結構：

openspec/
  ├── specs/  # 已經實現的功能或修改
  ├── changes/  # 正在開發的功能
  ├── AGENTS.md  # AI 工作流指南（如何使用 OpenSpec）
  └── project.md  # 項目整體上下文（技術棧、規範）

其中 project.md 嘅內容結構大致係咁：

# [項目名] Context

## Purpose
[描述項目的目的和目標]

## Tech Stack
- [列出主要技術]
- [例如: TypeScript, React, Node.js]

## Project Conventions

### Code Style
[描述代碼風格偏好、格式化規則和命名約定]

### Architecture Patterns
[記錄架構決策和模式]

### Testing Strategy
[解釋測試方法和要求]

### Git Workflow
[描述分支策略和提交約定]

## Domain Context
[添加 AI 助手需要理解的領域特定知識]

## Important Constraints
[列出任何技術、業務或法規約束]

## External Dependencies
[記錄關鍵外部服務、API 或系統]

project.md 唔應該包含：

  • 詳細嘅 API 文檔（應該喺 specs/ 入面）

  • 具體嘅實現細節（應該喺代碼入面）

  • 臨時嘅開發筆記

  • 個人偏好（除非係團隊共識）

1. 完善項目文檔 project.md

Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions

跟住 AI 會按照 OpenSpec 指引，閲讀當前 repo 結構，並喺 openspec 目錄生成 project.md。

新 AI 助手首次接入項目：

  1. 讀取 openspec/project.md
  2. 瞭解項目背景同規範
  3. 準備好跟從一致嘅開發標準

2. 生成變更提案

我想增加一個api，用於導出RecommendRecord 成csv, 這個api 可以傳餐廳id, 開始時間和結束時間，請使用OpenSpec 創建一個提案

或者用命令行方式：

/openspec:proposal 我想增加一個api，用於導出RecommendRecord 成csv, 這個api 可以傳餐廳id, 開始時間和結束時間

喺公司我通常會攞住產品嘅需求功能文檔，用 /openspec:proposal 幫我生成提案，費事自己表達得唔好，令到生成嘅提案唔夠精確。

佢建立咗以下文件夾：

openspec/
 └── changes/
      └── add-recommend-record-export-api/
           ├── proposal.md  # 變更提案：為什麼做、做什麼、影響範圍
           ├── tasks.md   # 實施清單：逐條可勾選的任務
           └── specs/recommend-records/spec.md  # 使用 ADDED/MODIFIED/REMOVED 標記

proposal.md 嘅內容結構如下：

## Why
導出推薦記錄用於運營分析、質量評估與模型回放，目前缺少按商户與時間窗口導出的標準接口。

## What Changes
- 新增導出接口：GET /xx/v1/recommend_record/export，支持 CSV 下載
- 支持參數：merchant_id、start_time、end_time（ISO 8601）
- 內容字段：xx
- 大數據量下采用流式響應，避免內存峯值

## Impact
- Affected specs: recommend-records
- Affected code:
  - xx
  - xx
  - xx

tasks.md 將整個開發工作拆分成多個 Phase，每個 Phase 包含若干可以打勾嘅 checkbox 任務

## 1. Implementation
- [] 1.1 新增導出視圖：註冊到 `/xxx/v1/recommend_record/export`
- [] 1.2 服務層實現：按商户與時間窗口查詢 RecommendRecord，並關聯 ProcessRecord、CallRecord 獲取 `seat_id`、`call_id`、`merchant_id`
- [] 1.3 CSV 生成：使用生成器流式寫出，設置 `Content-Type: text/csv` 與 `Content-Disposition`
- [] 1.4 校驗與錯誤處理：參數校驗（必填/時間格式/範圍），異常返回 400/500
- [ ] 1.5 單元測試：服務層查詢和 CSV 行序列化；空結果與大數據量用例
- [ ] 1.6 API 測試：GET 成功/空數據/參數錯誤

## 2. Non-Goals
- [ ] 不實現 XLSX 導出（後續需要再提）
- [ ] 不新增鑑權機制（與當前工程一致，如後續需要單獨提案）

## 3. Rollout
- [ ] 本地驗證與示例導出
- [ ] 預發環境驗證（大樣本）
- [ ] 文檔更新 README/變更日誌

spec.md 記錄功能嘅新增同改動

## ADDED Requirements
### Requirement: Export Recommend Records CSV
系統 SHALL 提供導出 RecommendRecord 的 CSV 接口，按商户與時間窗口過濾。

- Endpoint: `GET /xx/v1/recommend_record/export`
- Query 參數（必填）
  - `merchant_id`: string，商户 ID
  - `start_time`: string，ISO 8601（例如 `2025-01-01T00:00:00-05:00`）
  - `end_time`: string，ISO 8601（例如 `2025-01-31T23:59:59-05:00`）
- 時間過濾：基於 RecommendRecord `created_at` 範圍，包含端點時間
- 響應：`text/csv`，`Content-Disposition: attachment; filename="recommend_records_{merchant_id}_{start}_{end}.csv"`
- CSV 列（順序固定）：
  - `recommend_id`
  - `process_record_id`
  - `call_id`
  - `seat_id`
  - `dish_id`
  - `dish_name`
  - `std_id`
  - `std_name`
  - `type`
  - `confidence`
  - `accept`
  - `accept_time`
  - `recommend_method`
  - `created_at`
- 性能：當導出記錄量較大時，系統 MUST 採用流式寫出，避免一次性加載到內存

#### Scenario: 導出成功（有數據）
- WHEN 調用 `GET /xxx/v1/recommend_record/export?merchant_id=abc&start_time=2025-01-01T00:00:00-05:00&end_time=2025-01-02T00:00:00-05:00`
- THEN 返回 200，`Content-Type: text/csv`
- AND 響應包含表頭與至少 1 行數據
- AND 首行表頭與列順序與規範一致

#### Scenario: 導出成功（無數據）
- WHEN 指定時間範圍內無 RecommendRecord
- THEN 返回 200，`Content-Type: text/csv`
- AND CSV 僅包含表頭，無數據行

#### Scenario: 參數缺失或格式錯誤
- WHEN 缺少 `merchant_id` 或 `start_time` 或 `end_time`
- OR `start_time`/`end_time` 不是有效的 ISO 8601
- THEN 返回 400，JSON 錯誤消息，指明無效參數

#### Scenario: 大數據量流式導出
- GIVEN 預置 > 100k 條記錄在時間窗口內
- WHEN 觸發導出
- THEN 服務端以流式方式寫出 CSV（分塊 flush/迭代生成）
- AND 不發生內存 OOM 或進程阻塞

當你對變更提案唔係好滿意嘅時候，你可以繼續同 AI 交流直到滿意為止，例如：

你能給接口增加一個校驗嗎，開始和結束時間相差不能超過一週

AI 更新咗規範，來回修改，直到符合我嘅要求。

3. 執行任務

當一切都同 AI 同團隊成員對齊之後，就可以執行 openspec.apply 嚟執行任務，AI 會：

  1. 讀取 proposal.md、tasks.md、design.md
  2. 讀取 specs/skills/spec.md 嘅新增或者修改需求
  3. 按 tasks.md 順序逐條實施
  4. 每完成一個 task 就打勾對應嘅 checkbox

當任務完成之後，我習慣用另一個模型對呢次新增嘅代碼做審核，然後叫當前嘅 AI Coding 工具根據審核結果做針對性修改

4. 歸檔任務

當所有任務都執行完畢同測試通過之後，執行歸檔，等 AI 知道項目嘅演變路徑

/openspec:archive

呢個命令執行完之後，會做兩步操作：

  1. 移動目錄

    # 從
    openspec/changes/add-recommend-record-export-api/

    # 移動到
    openspec/changes/archive/2025-10-20-add-recommend-record-export-api/

  2. 合併 spec.md：將需求入面嘅 spec.md 合併到主 spec 目錄度，spec 目錄永遠代表系統嘅最新狀態

    # 合併到
    openspec/specs

點解要歸檔？

假設冇歸檔：

第1周: 你計劃添加"用戶登錄"功能
  → 創建 changes/add-login/
  → 編寫代碼,測試,部署 ✅

第2周: 你計劃添加"密碼重置"功能
  → 創建 changes/add-password-reset/
  → 編寫代碼,測試,部署 ✅

第3周: 你計劃添加"雙因素認證"功能
  → 創建 changes/add-2fa/
  → 編寫代碼,測試,部署 ✅

現在的狀態:
changes/
  ├── add-login/           ← 已上線3周,但還在"計劃"文件夾
  ├── add-password-reset/  ← 已上線2周,但還在"計劃"文件夾  
  └── add-2fa/             ← 已上線1周,但還在"計劃"文件夾

specs/
  └── auth/spec.md         ← 3周前的舊規範,不包含任何新功能!

問題出現：

1. 新同事入職:

     新同事: "我看了 specs/auth/spec.md,系統只有基礎認證?"

     你: "不不不,我們還有登錄、密碼重置、2FA..."

     新同事: "可規範裏沒寫啊?代碼在哪?"

     你: "呃...去 changes/ 目錄找找..."

2. AI 助手困惑:

     你: "幫我添加用戶註銷功能"

     AI: [讀取 specs/auth/spec.md]

       "我看系統還沒有登錄功能,需要先實現登錄嗎?"

     你: "不用!我們已經有登錄了!"

     AI: "可是規範裏沒有啊..."

當有咗歸檔功能之後

第1周: 添加"用戶登錄"
  → 創建 changes/add-login/
  → 實現並部署 
  → openspec archive add-login
     specs/auth/spec.md 更新(包含登錄需求)
     移動到 archive/2025-10-01-add-login/

第2周: 添加"密碼重置"  
  → 創建 changes/add-password-reset/
  → 實現並部署 
  → openspec archive add-password-reset
     specs/auth/spec.md 更新(包含密碼重置)
     移動到 archive/2025-10-08-add-password-reset/

第3周: 添加"雙因素認證"
  → 創建 changes/add-2fa/
  → 實現並部署 
  → openspec archive add-2fa
     specs/auth/spec.md 更新(包含2FA需求)
     移動到 archive/2025-10-15-add-2fa/

現在的狀態:
specs/
  └── auth/spec.md         ←  最新!包含所有已實現功能

changes/
  └── (空的或只有進行中的工作)

archive/
  ├── 2025-10-01-add-login/
  ├── 2025-10-08-add-password-reset/
  └── 2025-10-15-add-2fa/

咁樣帶嚟嘅好處係：

新同事入職:
   新同事: "我看了 specs/auth/spec.md"
   新同事: "明白了!系統有登錄、密碼重置、2FA,很完善!"
   你: "對!規範就是現狀,看規範就夠了"
AI 助手準確理解
   你: "幫我添加用戶註銷功能"
   AI: [讀取 specs/auth/spec.md]
       "我看到系統已有登錄功能,我會在登錄流程基礎上添加註銷"
   你: "完美!你理解得很對"

總結

OpenSpec 俾我最大嘅啟發係：

「AI 程式編寫唔止係寫代碼，更加係定義規則、執行規範嘅過程。」

佢令我重新理解咗「AI 參與開發」嘅意義——由簡單嘅任務執行，轉變為 以規範為中心嘅智能協作。如果你而家用 AI 做項目維護或者功能升級，強烈建議試試。


背景

在我藉助AI進行開發的過程中，最常遇到的困擾並不是“AI寫不出代碼”，而是它寫出的代碼過於隨意——有時誤解了我的意圖，有時給出的實現邏輯不夠清晰，最終不得不由我逐一修正。

後來，我嘗試過像 spec-kit、BMAD-METHOD 這類強調“規範驅動開發”的工具。理念雖好，實際使用起來卻不夠順暢，而且它們更適用於從零啓動的項目。但在公司實際環境中，大多數項目並非從頭開始，更多場景是在現有代碼基礎上開發新功能或重構舊模塊。

直到最近，我發現了一個更輕量、也更實用的新項目：OpenSpec。

相比 Cursor 的 Plan 模式，OpenSpec 更細緻、結構更清晰；相比 spec-kit，它又輕得多，非常適合個人開發者和小團隊使用。

與其他工具對比

工具
適用場景
特點
spec-kit
從 0 到 1 的系統搭建
結構化強、上手複雜
BMAD-METHOD
團隊協作型 AI 項目
自動化程度高、學習曲線陡峭
OpenSpec
已有項目的功能演進與維護
輕量、兼容性強、適合個體開發者

尤其在需要修改現有功能或觸及多個模塊規範時，OpenSpec 的變更分組與追溯機制非常實用。

工作流&核心理念

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

OpenSpec 增加了一個規範驅動的工作流程。

你無需在聊天中解釋某個功能，並希望 AI 能夠正確理解，而是：

  • 撰寫（或讓 AI 起草）提案。
  • 共同審查並調整規範。
  • 讓 AI 實施已批准的計劃。
  • 將變更歸檔，以便更新你的項目規範。

其核心邏輯分為兩部分：

  • specs：記錄當前的規範狀態（項目規則、API 約束、模塊定義等）

  • changes：追蹤每一次變更提案及其實施過程

AI 執行順序

1. 讀取 proposal.md
   → 理解"為什麼要做"、"做什麼"

2. 讀取 design.md (如果存在)
   → 理解"如何做"、"技術決策"
   → 瞭解架構選擇和權衡

3. 讀取 tasks.md
   → 獲取實現清單

4. 開始實現
   → 按照 design.md 中的決策編寫代碼

實操流程

OpenSpec 支持命令行和自然語言兩種交互方式，並且支持多種ai coding 工具：

Tool
Claude Code
Cursor
Factory Droid
OpenCode
Kilo Code
Windsurf
Codex
GitHub Copilot
Amazon Q Developer
Auggie (Augment CLI)

安裝與初始化流程非常簡潔：

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

初始化你已有的項目，初始化過程中你可以選擇你會使用的AI Coding 工具

cd your_project
openspec init

初始化後會生成以下結構：

openspec/
  ├── specs/  # 已經實現的功能或修改
  ├── changes/  # 正在開發的功能
  ├── AGENTS.md  # AI 工作流指南（如何使用 OpenSpec）
  └── project.md  # 項目整體上下文（技術棧、規範）

其中project.md 的內容結構大致如下：

# [項目名] Context

## Purpose
[描述項目的目的和目標]

## Tech Stack
- [列出主要技術]
- [例如: TypeScript, React, Node.js]

## Project Conventions

### Code Style
[描述代碼風格偏好、格式化規則和命名約定]

### Architecture Patterns
[記錄架構決策和模式]

### Testing Strategy
[解釋測試方法和要求]

### Git Workflow
[描述分支策略和提交約定]

## Domain Context
[添加 AI 助手需要理解的領域特定知識]

## Important Constraints
[列出任何技術、業務或法規約束]

## External Dependencies
[記錄關鍵外部服務、API 或系統]

project.md 不應該包含：

  • 詳細的 API 文檔（應該在 specs/ 中）

  • 具體的實現細節（應該在代碼中）

  • 臨時的開發筆記

  • 個人偏好（除非是團隊共識）

1. 完善項目文檔project.md

Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions

接着AI 會按照OpenSpec guide 閲讀當前repo structure, 並在openspec目錄生成project.md。

新 AI 助手首次接入項目:

  1. 讀取 openspec/project.md
  2. 瞭解項目背景和規範
  3. 準備好遵循一致的開發標準

2. 生成變更提案

我想增加一個api，用於導出RecommendRecord 成csv, 這個api 可以傳餐廳id, 開始時間和結束時間，請使用OpenSpec 創建一個提案

或者使用命令行的方式：

/openspec:proposal 我想增加一個api，用於導出RecommendRecord 成csv, 這個api 可以傳餐廳id, 開始時間和結束時間

在公司我一般會習慣拿着產品的需求功能文檔，使用/openspec:proposal 幫我生成提案，防止我的表達不到位生成的提案不夠精確。

它搭建了以下文件夾：

openspec/
 └── changes/
      └── add-recommend-record-export-api/
           ├── proposal.md  # 變更提案：為什麼做、做什麼、影響範圍
           ├── tasks.md   # 實施清單：逐條可勾選的任務
           └── specs/recommend-records/spec.md  # 使用 ADDED/MODIFIED/REMOVED 標記

proposal.md 的內容結構如下：

## Why
導出推薦記錄用於運營分析、質量評估與模型回放，目前缺少按商户與時間窗口導出的標準接口。

## What Changes
- 新增導出接口：GET /xx/v1/recommend_record/export，支持 CSV 下載
- 支持參數：merchant_id、start_time、end_time（ISO 8601）
- 內容字段：xx
- 大數據量下采用流式響應，避免內存峯值

## Impact
- Affected specs: recommend-records
- Affected code:
  - xx
  - xx
  - xx

tasks.md 將整個開發工作拆分為多個 Phase，每個 Phase 包含若干可勾選的 checkbox 任務

## 1. Implementation
- [] 1.1 新增導出視圖：註冊到 `/xxx/v1/recommend_record/export`
- [] 1.2 服務層實現：按商户與時間窗口查詢 RecommendRecord，並關聯 ProcessRecord、CallRecord 獲取 `seat_id`、`call_id`、`merchant_id`
- [] 1.3 CSV 生成：使用生成器流式寫出，設置 `Content-Type: text/csv` 與 `Content-Disposition`
- [] 1.4 校驗與錯誤處理：參數校驗（必填/時間格式/範圍），異常返回 400/500
- [ ] 1.5 單元測試：服務層查詢和 CSV 行序列化；空結果與大數據量用例
- [ ] 1.6 API 測試：GET 成功/空數據/參數錯誤

## 2. Non-Goals
- [ ] 不實現 XLSX 導出（後續需要再提）
- [ ] 不新增鑑權機制（與當前工程一致，如後續需要單獨提案）

## 3. Rollout
- [ ] 本地驗證與示例導出
- [ ] 預發環境驗證（大樣本）
- [ ] 文檔更新 README/變更日誌

spec.md 記錄功能的新增與改動

## ADDED Requirements
### Requirement: Export Recommend Records CSV
系統 SHALL 提供導出 RecommendRecord 的 CSV 接口，按商户與時間窗口過濾。

- Endpoint: `GET /xx/v1/recommend_record/export`
- Query 參數（必填）
  - `merchant_id`: string，商户 ID
  - `start_time`: string，ISO 8601（例如 `2025-01-01T00:00:00-05:00`）
  - `end_time`: string，ISO 8601（例如 `2025-01-31T23:59:59-05:00`）
- 時間過濾：基於 RecommendRecord `created_at` 範圍，包含端點時間
- 響應：`text/csv`，`Content-Disposition: attachment; filename="recommend_records_{merchant_id}_{start}_{end}.csv"`
- CSV 列（順序固定）：
  - `recommend_id`
  - `process_record_id`
  - `call_id`
  - `seat_id`
  - `dish_id`
  - `dish_name`
  - `std_id`
  - `std_name`
  - `type`
  - `confidence`
  - `accept`
  - `accept_time`
  - `recommend_method`
  - `created_at`
- 性能：當導出記錄量較大時，系統 MUST 採用流式寫出，避免一次性加載到內存

#### Scenario: 導出成功（有數據）
- WHEN 調用 `GET /xxx/v1/recommend_record/export?merchant_id=abc&start_time=2025-01-01T00:00:00-05:00&end_time=2025-01-02T00:00:00-05:00`
- THEN 返回 200，`Content-Type: text/csv`
- AND 響應包含表頭與至少 1 行數據
- AND 首行表頭與列順序與規範一致

#### Scenario: 導出成功（無數據）
- WHEN 指定時間範圍內無 RecommendRecord
- THEN 返回 200，`Content-Type: text/csv`
- AND CSV 僅包含表頭，無數據行

#### Scenario: 參數缺失或格式錯誤
- WHEN 缺少 `merchant_id` 或 `start_time` 或 `end_time`
- OR `start_time`/`end_time` 不是有效的 ISO 8601
- THEN 返回 400，JSON 錯誤消息，指明無效參數

#### Scenario: 大數據量流式導出
- GIVEN 預置 > 100k 條記錄在時間窗口內
- WHEN 觸發導出
- THEN 服務端以流式方式寫出 CSV（分塊 flush/迭代生成）
- AND 不發生內存 OOM 或進程阻塞

當你對變更提案不夠滿意的時候，你可以繼續和ai 交流直到你滿意為止，比如：

你能給接口增加一個校驗嗎，開始和結束時間相差不能超過一週

AI更新了規範，反覆修改，直到符合我的要求。

3. 執行任務

當一切都和AI以及團隊成員對齊之後，就可以執行 openspec.apply 來執行任務，AI 會：

  1. 讀取 proposal.md、tasks.md、design.md
  2. 讀取 specs/skills/spec.md 的新增或者修改需求
  3. 按 tasks.md 順序逐條實施
  4. 每完成一個 task 就勾選對應的 checkbox

當任務完整之後，我習慣使用另外的模型對這次新增的代碼進行審核，並讓當前的AI Coding 工具針對審核結果做針對性的修改

4. 歸檔任務

當所有任務都執行結束並測試通過之後，執行歸檔，以讓AI 知道項目的演變路徑

/openspec:archive

當這個命令執行完畢之後，會進行兩步操作：

  1. 移動目錄

    # 從
    openspec/changes/add-recommend-record-export-api/

    # 移動到
    openspec/changes/archive/2025-10-20-add-recommend-record-export-api/

  2. 合併spec.md: 將需求中的spec.md 合併到主的spec 目錄下，spec 目錄下永遠代表系統的最新狀態

    # 合併到
    openspec/specs

為什麼要歸檔?

假設沒有歸檔：

第1周: 你計劃添加"用戶登錄"功能
  → 創建 changes/add-login/
  → 編寫代碼,測試,部署 ✅

第2周: 你計劃添加"密碼重置"功能
  → 創建 changes/add-password-reset/
  → 編寫代碼,測試,部署 ✅

第3周: 你計劃添加"雙因素認證"功能
  → 創建 changes/add-2fa/
  → 編寫代碼,測試,部署 ✅

現在的狀態:
changes/
  ├── add-login/           ← 已上線3周,但還在"計劃"文件夾
  ├── add-password-reset/  ← 已上線2周,但還在"計劃"文件夾  
  └── add-2fa/             ← 已上線1周,但還在"計劃"文件夾

specs/
  └── auth/spec.md         ← 3周前的舊規範,不包含任何新功能!

問題出現:

1. 新同事入職:

     新同事: "我看了 specs/auth/spec.md,系統只有基礎認證?"

     你: "不不不,我們還有登錄、密碼重置、2FA..."

     新同事: "可規範裏沒寫啊?代碼在哪?"

     你: "呃...去 changes/ 目錄找找..."

2. AI 助手困惑:

     你: "幫我添加用戶註銷功能"

     AI: [讀取 specs/auth/spec.md]

       "我看系統還沒有登錄功能,需要先實現登錄嗎?"

     你: "不用!我們已經有登錄了!"

     AI: "可是規範裏沒有啊..."

當有了歸檔功能之後

第1周: 添加"用戶登錄"
  → 創建 changes/add-login/
  → 實現並部署 
  → openspec archive add-login
     specs/auth/spec.md 更新(包含登錄需求)
     移動到 archive/2025-10-01-add-login/

第2周: 添加"密碼重置"  
  → 創建 changes/add-password-reset/
  → 實現並部署 
  → openspec archive add-password-reset
     specs/auth/spec.md 更新(包含密碼重置)
     移動到 archive/2025-10-08-add-password-reset/

第3周: 添加"雙因素認證"
  → 創建 changes/add-2fa/
  → 實現並部署 
  → openspec archive add-2fa
     specs/auth/spec.md 更新(包含2FA需求)
     移動到 archive/2025-10-15-add-2fa/

現在的狀態:
specs/
  └── auth/spec.md         ←  最新!包含所有已實現功能

changes/
  └── (空的或只有進行中的工作)

archive/
  ├── 2025-10-01-add-login/
  ├── 2025-10-08-add-password-reset/
  └── 2025-10-15-add-2fa/

這樣帶來的好處就是：

新同事入職:
   新同事: "我看了 specs/auth/spec.md"
   新同事: "明白了!系統有登錄、密碼重置、2FA,很完善!"
   你: "對!規範就是現狀,看規範就夠了"
AI 助手準確理解
   你: "幫我添加用戶註銷功能"
   AI: [讀取 specs/auth/spec.md]
       "我看到系統已有登錄功能,我會在登錄流程基礎上添加註銷"
   你: "完美!你理解得很對"

總結

OpenSpec 給我的最大啓發是：

“AI 編程不只是寫代碼，更是定義規則、執行規範的過程。”

它讓我重新理解了“AI 參與開發”的意義—— 從簡單的任務執行，轉變為 以規範為中心的智能協作。如果你正在用 AI 做項目維護或功能升級，強烈建議試試。