拯救老項目！比Cursor更細、比spec-kit更輕：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 工具：
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 助手首次接入項目:
- 讀取 openspec/project.md
- 了解項目背景和規范
- 準備好遵循一致的開發標準
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
- xxtasks.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 會：
- 讀取?
?proposal.md??、??tasks.md??、??design.md?? - 讀取?
?specs/skills/spec.md?? 的新增或者修改需求 - 按?
?tasks.md?? 順序逐條實施 - 每完成一個 task 就勾選對應的 checkbox
當任務完整之后，我習慣使用另外的模型對這次新增的代碼進行審核，并讓當前的AI Coding 工具針對審核結果做針對性的修改
4. 歸檔任務
當所有任務都執行結束并測試通過之后，執行歸檔，以讓AI 知道項目的演變路徑
/openspec:archive當這個命令執行完畢之后，會進行兩步操作：
- 移動目錄
# 從
openspec/changes/add-recommend-record-export-api/
# 移動到
openspec/changes/archive/2025-10-20-add-recommend-record-export-api/- 合并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 博物院???? 作者：longyunfeigu
