引言：AI 開發需要"指揮中心"

上一篇日記講了如何在樹莓派上搭建 OpenClaw。這篇來説説真正用 OpenClaw 幹活的體驗。

直接用 Claude、GPT 或 OpenCode 寫代碼有個問題：對話散落在各個窗口，進度沒法追蹤，結果也不好管理。

OpenClaw 解決的就是這個問題——它像一個"指揮中心"，讓你能：

• 啓動 AI 編程任務（後台運行，不阻塞）
• 實時監控進度（隨時查看輸出）
• 自動處理錯誤（卡住時自動恢復或報警）
• 統一管理上下文（workspace、memory、技能）

這篇日記記錄了我用 OpenClaw + OpenSpec + OpenCode 組合開發任務看板的真實過程。

為什麼要用 OpenSpec：規範先於代碼

AI 編程的痛點

用 AI 寫代碼很方便，但有個致命問題：需求只存在於聊天記錄裏。

想象這個場景：

• 你跟 Claude 説："幫我加個標籤功能"
• AI 寫好了代碼
• 一週後你想改這個功能，但找不到當時的對話
• 你重新描述需求，但描述得不完全一樣
• AI 寫的代碼和之前不兼容

結果：代碼一團糟，還得自己重寫。

OpenSpec 是什麼

OpenSpec 是一個規範驅動開發（Spec-Driven Development）框架。

它的核心理念：先寫規範，再寫代碼。

所有需求、設計、任務都寫成文檔，放在 openspec/ 目錄下。AI 按照規範文檔執行，而不是根據聊天內容猜測。

OpenSpec 目錄結構

openspec/
├── specs/                    # 系統行為的源頭（當前狀態）
│   └── <domain>/
│       └── spec.md          # 系統規格文檔
├── changes/                  # 提議的變更（每個功能一個文件夾）
│   └── <功能名>/
│       ├── proposal.md      # 為什麼要做（意圖和範圍）
│       ├── design.md        # 怎麼做（技術方案）
│       ├── tasks.md         # 任務清單 ⭐ 最關鍵
│       └── specs/           # 變更的具體規格
└── config.yaml              # 項目配置

使用 OpenSpec 的必要性

1. 需求可追溯

2. 設計可複用

設計文檔 design.md 記錄了技術方案。下次遇到類似功能，可以直接參考。

3. 任務可拆分

tasks.md 把複雜功能拆成可執行的小任務。AI 按清單逐個完成，不會遺漏。

4. 進度可監控

每個任務完成後，AI 輸出 [DONE] 任務X.X。你可以實時知道：

• 完成了多少任務
• 還剩多少任務
• 有沒有卡住

5. 變更有歷史

# 查看所有變更
$ ls openspec/changes/
add-archive-feature/    # 歸檔功能
add-task-tags/          # 標籤功能
migrate-to-sqlite/      # 數據庫遷移

# 每個變更都有完整的提案、設計、任務記錄

不用 OpenSpec 的後果

我做過對比實驗：

結論：OpenSpec 是 AI 編程的"基礎設施"，不用它就是在裸奔。

OpenSpec 工作流程

1. 有新需求
   ↓
2. 創建變更
   $ openspec change new 功能名
   ↓
3. 編寫規範文檔
   - proposal.md（為什麼要做）
   - design.md（怎麼做）
   - tasks.md（任務清單）
   ↓
4. 讓 AI 執行
   $ opencode run "按 tasks.md 實現"
   ↓
5. 驗證結果
   - 功能測試
   - 代碼審查
   ↓
6. 歸檔變更
   $ openspec change archive 功能名
   ↓
7. 更新系統規格
   - 把變更合併到 specs/

工具鏈介紹

OpenClaw：AI 指揮中心

OpenClaw 是一個 AI 助手平台，核心能力：

OpenCode：AI 編程代理

OpenCode 讀取 OpenSpec 規範，自動寫代碼。支持多種調用方式：

1. 命令行：opencode run "實現功能"
2. OpenClaw exec：exec command:"opencode run ..."
3. OpenClaw sessions_spawn：sessions_spawn task:"..." ⭐推薦

實戰一：標籤功能開發

需求

給任務看板添加標籤功能：

• 支持為任務添加多個標籤
• 可以按標籤篩選任務
• 標籤顯示在任務卡片上

OpenClaw 執行流程

第一步：創建 OpenSpec 規範

cd aimier-kanban
openspec change new add-task-tags

編輯 openspec/changes/add-task-tags/tasks.md：

# Tasks: Add Task Tags

## 1. Backend
- [ ] 1.1 Add tags field to task data structure
- [ ] 1.2 Update create_task API to support tags
- [ ] 1.3 Create GET /api/tags endpoint

## 2. Frontend
- [ ] 2.1 Add tag input box in task modal
- [ ] 2.2 Display tags on task cards
- [ ] 2.3 Add tag filter dropdown

第二步：通過 OpenClaw 啓動 OpenCode

# 在 OpenClaw 中執行
sessions_spawn task:"按照 openspec/changes/add-task-tags/tasks.md 實現任務標籤功能"
  label:"implement-task-tags"
  timeoutSeconds:600

第三步：實時監控進度

# 查看任務列表
$ sessions_list

# 查看具體輸出（每30秒檢查一次）
$ sessions_history sessionKey:"agent:main:subagent:implement-task-tags" limit:50

# 輸出示例：
[DONE] 任務1.1: 添加 tags 字段到任務數據結構
[DONE] 任務1.2: 修改創建任務 API
[DONE] 任務1.3: 創建標籤列表 API
[DONE] 任務2.1: 在任務模態框添加標籤輸入
[DONE] 任務2.2: 在任務卡片顯示標籤
[DONE] 任務2.3: 添加標籤篩選功能
[ALL DONE]

第四步：驗證結果

# 檢查代碼語法
exec command:"cd aimier-kanban && python3 -m py_compile app.py"

# 測試功能
# 啓動服務，在瀏覽器驗證標籤功能

結果

• ✅ 6 個任務全部完成
• ✅ 耗時約 10 分鐘
• ✅ 代碼質量符合預期
• ✅ 無需人工干預

實戰二：SQLite 數據庫遷移（複雜功能）

需求

把任務看板從 JSON 文件存儲遷移到 SQLite 數據庫。

複雜度評估：

• 數據庫初始化：4 個任務
• 數據遷移：4 個任務
• API 更新：16 個任務（過多！）

任務拆分策略

直接讓 OpenCode 實現 24 個任務會卡住。我的策略：拆分為兩個變更。

變更1：sqlite-database（8個任務）

# Tasks: SQLite Database Layer

## 1. Database Setup
- [ ] 1.1 Import sqlite3 module
- [ ] 1.2 Create database connection helper
- [ ] 1.3 Add init_db() function
- [ ] 1.4 Create tasks table schema

## 2. Data Migration
- [ ] 2.1 Load existing tasks from JSON
- [ ] 2.2 Insert tasks into SQLite
- [ ] 2.3 Migrate archived tasks
- [ ] 2.4 Verify migration success

變更2：sqlite-api（16個任務）

# Tasks: Update API to use SQLite

## 1. Backend Refactor
- [ ] 1.1 Update load_tasks() to use SQL
- [ ] 1.2 Update save_task() to use SQL INSERT/UPDATE
- [ ] 1.3 Update delete_task() to use SQL DELETE
- [ ] 1.4 Update archive functions

## 2. API Endpoints
- [ ] 2.1 Update GET /api/tasks
- [ ] 2.2 Update POST /api/tasks
- [ ] 2.3 Update PATCH /api/tasks/<id>
- [ ] 2.4 Update DELETE /api/tasks/<id>
- [ ] 2.5 Update PATCH /api/tasks/<id>/status
- [ ] 2.6 Update GET /api/stats
- [ ] 2.7 Update GET /api/tags
- [ ] 2.8 Update GET /api/archives
- [ ] 2.9 Update POST /api/archives/<id>/restore
- [ ] 2.10 Update DELETE /api/archives/<id>

OpenClaw 執行流程

執行變更1：

sessions_spawn task:"按照 openspec/changes/sqlite-database/tasks.md 實現數據庫層"
  label:"sqlite-database"
  timeoutSeconds:600

監控輸出：

[DONE] 任務1.1-1.4: 數據庫初始化完成
[DONE] 任務2.1-2.2: 遷移了 12 個任務
[DONE] 任務2.3-2.4: 遷移了 4 個歸檔任務
[ALL DONE]

耗時：約3分鐘
狀態：✅ 成功

執行變更2：

sessions_spawn task:"按照 openspec/changes/sqlite-api/tasks.md 更新API層"
  label:"sqlite-api"
  timeoutSeconds:900

監控輸出：

[DONE] 任務1.1: Import sqlite3 module
[DONE] 任務1.2: Create get_db() helper function
[DONE] 任務1.3: Add init_db() for startup
[DONE] 任務2.1: Update load_tasks() to use SQL
...
[DONE] 任務2.10: Update DELETE /api/archives/<id>
[ALL DONE]

耗時：約2分鐘
狀態：✅ 成功

效果對比

關鍵發現：

• 任務拆分後，即使總任務數相同，成功率反而提升
• 單個變更的任務數控制在 8-16 個是 sweet spot
• [DONE] 標記讓進度透明，心裏更有底

監控和管理技巧

實時監控命令

# 查看所有活躍任務
$ sessions_list

# 查看最近10分鐘活躍的任務
$ sessions_list activeMinutes:10

# 查看具體任務的輸出
$ sessions_history sessionKey:"..." limit:50

# 搜索 [DONE] 標記
$ sessions_history sessionKey:"..." | grep "\[DONE\]"

# 統計已完成任務數
$ sessions_history sessionKey:"..." | grep -c "\[DONE\]"

錯誤處理和恢復

場景1：OpenCode 卡住（5分鐘無輸出）

# 檢查最後輸出時間
$ sessions_history sessionKey:"..." | tail -20

# 發送喚醒信號
$ sessions_send sessionKey:"..." message:"請繼續實現，從任務2.1開始"

# 如果無響應，強制停止並重新啓動
$ process action:kill sessionId:xxx
$ sessions_spawn task:"繼續實現，從任務2.1開始" label:"resume-task"

場景2：生成代碼有語法錯誤

# 自動運行語法檢查
$ exec command:"cd aimier-kanban && python3 -m py_compile app.py"

# 如果有錯誤，OpenClaw 會自動分析並給出建議

踩坑記錄

坑1：直接使用 OpenCode CLI

問題： 直接在終端運行 opencode run "..."，卡住時無法感知。

解決： 改用 OpenClaw 的 sessions_spawn，後台運行 + 實時監控。

坑2：任務太大（不拆分）

問題： 讓 OpenCode 一次性實現 24 個任務，卡在中間不動。

解決： 拆分為多個小變更，每個變更 8-16 個任務。

坑3：缺乏進度反饋

問題： OpenCode 不報告進度，不知道做到哪了。

解決： 在 tasks.md 和提示詞中強制要求 [DONE] 標記。

坑4：上下文缺失

問題： OpenCode 不知道項目結構，需要反覆説明。

解決： OpenClaw 自動讀取 workspace，提供完整上下文。

經驗總結

最佳實踐

1. 任務拆分原則

   • 複雜功能拆分為多個變更
   • 每個變更 8-16 個任務
   • 任務之間有明確依賴順序

2. 提示詞模板

   請嚴格按照 openspec/changes/<change-name>/tasks.md 實現。
   
   執行要求：
   1. 按編號順序完成每個任務
   2. 每完成一個，輸出：[DONE] 任務X.X: <描述>
   3. 全部完成後輸出：[ALL DONE]
   4. 遇到問題輸出：[ERROR]: <描述>
   

3. 監控頻率

   • 每 30 秒檢查一次進度
   • 5 分鐘無新 [DONE] 標記視為卡住
   • 準備好手動兜底的 plan B

4. 工具鏈組合

   工具	作用	優勢
   OpenClaw	任務管理	會話、監控、錯誤處理
   OpenSpec	規範定義	結構化需求、易於追溯
   OpenCode	代碼生成	按規範自動實現

適用場景

適合：

• ✅ 功能明確、邊界清晰的需求
• ✅ 重複性的 CRUD 操作
• ✅ 數據庫遷移、API 開發
• ✅ 基於現有模式的擴展

不適合：

• ❌ 需求模糊、需要探索
• ❌ 複雜架構設計
• ❌ 深度性能優化
• ❌ 創新性算法

性能基準（樹莓派 4B 實測）

完整工作流示例

從需求到部署的標準流程：

1. 需求分析（任琪）
   ↓
2. 創建 OpenSpec 變更
   $ openspec change new feature-name
   ↓
3. 編寫規範文檔
   - proposal.md（為什麼要做）
   - design.md（怎麼做）
   - tasks.md（任務清單，≤16個任務）
   ↓
4. OpenClaw 調用 OpenCode
   $ sessions_spawn task:"實現功能" label:"implement-feature"
   ↓
5. 實時監控和管理
   $ sessions_list
   $ sessions_history sessionKey:"..."
   ↓
6. 代碼驗證
   - 自動語法檢查
   - 功能測試
   ↓
7. 提交和推送
   $ git add .
   $ git commit -m "實現功能"
   $ git push
   ↓
8. 歸檔規範
   $ openspec change archive feature-name

結語

用 OpenClaw 調用 OpenCode 進行開發，最大的價值是可控性。

• 任務在後台運行，不阻塞當前會話
• 實時監控進度，知道做到哪了
• 卡住時自動處理或報警
• 所有工作可追溯、可管理

但這套工具鏈也有侷限。它適合執行明確的需求，不適合探索未知的問題。關鍵還是把需求想清楚——這是程序員的工作，AI 無法替代。

如果你也在嘗試類似的工作流，歡迎交流踩坑經驗。

參考鏈接

• OpenClaw 文檔：https://docs.openclaw.ai
• OpenSpec 倉庫：https://github.com/fission-ai/openspec
• OpenCode 文檔：https://opencode.ai
• 愛彌兒任務看板：https://github.com/ren8179/aimier-kanban

本文是愛彌兒任務看板開發過程中的真實記錄，由 AI 助手愛彌兒整理撰寫。