前言¶
在多工具協作（如 Cursor、Claude Code、DSH）的開發場景中，統一編碼規範（ICVO）並確保 Harness 流程的 P0 門控執行，通常需要手動維護多套配置。SpecWave 提供了一個聲明式的適配表，將一套規範原生化地落地到多個客戶端中，並內置 Harness 進程命令與任務門控機制。
是什麼¶
SpecWave 是一個多主機編碼 CLI 工具。它通過聲明式的適配表，將 ICVO 規範（告知、約束、驗證、編排）和 Harness 流程直接注入到 Cursor、Claude Code、可選的 DSH 以及其他智能體工具中。工具提供 P0 門控（Gate）與 Harness 進程命令支持，確保流程在 IDE 和命令行中的一致性。
安裝與啓用¶
在使用前，請確保 Node.js 版本滿足要求。
# 檢查 Node.js 版本，需爲 ^22.19.0 或 >=24.0.0
node -v
通過 npm 全局執行（推薦鎖定版本）：
# 確認版本
npx spec-wave@3.0.2 --version
核心功能¶
- 多主機落地：一套適配表支持 Cursor、Claude Code、DSH 及其他智能體。
- P0 門控與 Harness：內置 Harness 進程命令與任務驗證門控，支持硬停止（exit 2）。
- ICVO 規範：維護 Discipline 資產，確保編碼行爲的可約束性與可驗證性。
- 主機應用：通過
host apply命令將適配表寫入對應 IDE 的目錄結構。
典型用法¶
1. 驗證適配表¶
在正式應用前，先進行 dry-run 驗證：
npx spec-wave@3.0.2 host validate
2. 應用主機配置¶
將適配表寫入指定工具（以 Cursor、Claude Code、DSH 爲例）：
npx spec-wave@3.0.2 host apply --tools cursor,claude,dsh --profile core
3. 初始化項目¶
如果這是首次初始化，指定 preset 並自動應用：
npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude,dsh --yes
4. 驗證任務門控¶
在執行任務前，驗證任務文檔是否符合規範，如果門控失敗則進程退出（exit 2）：
npx spec-wave@3.0.2 verify --task docs/tasks/active/task_<slug>.md
關於 DSH 與系統提示詞的注意點¶
Loading ≠ injecting。安裝或加載 DSH 插件不會自動重寫系統提示詞。apply() 僅註冊工具。只有當你或模型調用了 apply_coding_standards 後，後續輪次的運行時上下文才會包含 # Coding Standards。
適用場景與注意¶
- 適用場景：需要在 Cursor、Claude Code、DSH 之間保持一致編碼規範的開發者；使用 Harness 流程管理任務門控的團隊。
- Node 版本限制：不支持 Node 20 及更早版本，升級前請檢查環境。
- 文件寫入限制：CLI 不會自動將示例任務寫入
docs/tasks/，需手動複製模板。 - 人工門控表：
HG-AUDIT-R1等人工門控表必須包含 4 列。 - 源碼與許可證：使用前請檢查源碼與許可證（MIT）。
結語¶
SpecWave 通過聲明式配置解決了多客戶端規範同步的痛點，結合 Harness 的 P0 門控，爲 AI 編碼提供了強約束的執行環境。更多細節可參考項目目錄或 GitHub 倉庫。
