AI 協作開發實務：利用 Claude Code 建立簡訊服務規格文件

前兩篇文章記錄了我與 Claude Code 關於 CabloyJS 中簡訊套件的架構和產品決策對話。第一輪討論區分了簡訊基礎設施、驗證、身份驗證和模擬傳送的職責。第二輪則釐清了明確註冊、國際號碼、真實供應商以及共享 Web/Admin 身份，而無需自動授予管理權限。

既然計畫已經到位，下一步指令是否應該是開始編碼呢？在這一輪中，我首先要求 Claude Code 將討論內容轉化為規格文件。提示詞很簡短：「/cabloy-spec-generation 我同意你的計畫。請將其整理成規格文件。」重點不在於產生更多 Markdown 檔案，而是將分散在對話中的共識轉化為規劃基準，以便日後檢查、分解為增量並進行驗證。

1. 在開始實作前確認文件範圍

Claude Code 並未將「我同意」解讀為建立業務模組的許可。它首先檢查了儲存庫的規劃慣例、現有帳戶規劃、Web/Admin 網站和登入路由，然後說明了這一輪的範圍：

「我將在 repo-specs/cabloy-sms/ 下為 Cabloy Basic 建立一個完整的全新套件基準，並以中文撰寫內文。範圍包括：六份核心文件：README、PRD（產品需求文件）、SRS（系統需求規格）、PDP/WBS（產品交付計畫/工作分解結構）、測試計畫和進度報告。

一份邊界 ADR（架構決策記錄）和一份用於真實簡訊供應商整合與驗收的執行手冊。一份從完整 WBS 輸入衍生的甘特圖和燃盡圖；這些不代表排程承諾或已完成的進度。

商定的計畫：明確的簡訊註冊、國際號碼、共享現有的 Web/Admin 網站，以及初步交付模擬、阿里巴巴雲、騰訊雲和 Twilio，Vonage 則延後。明確區分現有來源和建議功能。ADR 狀態為『建議』，交付狀態為『未開始』，此批准不擴及程式碼執行、真實簡訊傳送或發布授權。」

它還從現有系統中識別出兩個限制：現有的家庭用戶計畫將使用者名稱和其他登入識別碼排除在可自由編輯的個人資料欄位之外。新的規格將保留該界限，並說明必要的使用者名稱一致性檢查，而不會擴大重新命名權限。供應商帳戶、目的地啟用和真實測試號碼僅阻擋其各自通道的驗收，而非模擬流程的獨立交付。

這不僅僅是對先前答案的總結。早期的討論曾審視使用者名稱和顯示名稱之間的關係。這一輪檢查了現有的帳戶規劃，並確認簡訊整合不應悄悄地擴大個人資料編輯權限。對話中的建議仍需與儲存庫中已記錄的界限保持一致。在範圍確認中，我選擇：「按照建議生成完整的基準，使用英文內文。」

Claude Code 確認了調整：「了解。我將生成完整的英文內文基準，同時繼續用中文報告。我只會在 repo-specs/cabloy-sms/ 下撰寫規劃文件，不執行腳手架、資料庫操作或真實簡訊傳送。」因此，接下來是英文規格基準的生成，而不是對已完成簡訊功能的追溯。

2. 六份核心文件，六個不同的問題

「將計畫整理成文件」很容易變成將相同的架構描述複製到多個檔案中。一個更有用的方法是為每個文件賦予不同的職責。這一輪生成的核心文件集是：

文件 | 主要問題

---|---

README | 讀者應該從哪裡開始？目前的範圍、狀態和下一步是什麼？

PRD | 為何建立此功能，為誰建立？哪些業務功能屬於初始版本，哪些不屬於？

SRS | 哪些因素限制了實作？哪些契約規範了模組、API、安全性、身份、並行性和前端整合？

PDP/WBS | 交付應該以什麼順序進行？依賴關係和完成條件是什麼？

測試計畫 | 如何證明符合性？需要哪些情境和證據？

進度記錄 | 哪些尚未開始，哪些有證據，哪些決策或外部條件仍未確定？

例如，「簡訊登入不得自動建立帳戶」不應只在聊天中出現一次。它需要成為產品行為、在現有身份和身份驗證邊界強制執行的系統契約、一個實作任務，以及一個驗收情境，證明缺少身份不會悄悄地建立用戶。這些不是同一故事的六個平行版本，它們描述了同一目標的不同層次。

從產品需求到驗收證據

該基準透過明確的識別碼將需求和交付連結起來：PRD → SRS → WBS → ATP（產品需求 → 系統需求 → 交付任務 → 驗收情境）。這些識別碼的價值不在於整潔的格式，它們有助於回答：這個交付任務服務於哪個需求？哪個任務實作了特定的安全需求？什麼證據必須支持任務已完成的聲明？如果驗收情境失敗，交付的哪個部分受到影響？

並非所有規劃活動都需要發明執行時測試。初步的邊界決策可以透過文件審查完成，但這無法證明簡訊傳送已通過驗證。

3. 將架構決策與操作程序分開

除了六份核心文件，這一輪還生成了一份邊界 ADR 和一份供應商操作執行手冊。

ADR：記錄邊界而不暗示批准

ADR 是一份架構決策記錄。ADR 0001 保持「建議」狀態，記錄了簡訊傳輸、驗證、身份和現有框架之間建議的職責邊界。「我同意生成文件」與「我批准每個技術細節並授權實作」不同。明確的狀態可以防止看起來完整的計畫被誤認為是無限制的執行許可。

供應商執行手冊：程式碼整合後剩下什麼？

真實的簡訊整合不僅涉及 SDK 呼叫和參數映射：供應商帳戶和憑證的安全配置。經批准的簽名、範本或發送者身份。已啟用的目的地國家和地區。同意的測試號碼、白名單和支出限制。處理明確拒絕與不確定逾時結果。通道停用、切換和回滾。

這些程序屬於執行手冊。真實憑證、完整電話號碼和驗證碼不屬於規格。執行手冊還保留了上一篇文章的一個關鍵區別：供應商接受請求並不證明手機收到了訊息。轉接器映射可以先驗證；一旦先決條件和明確授權到位，必須單獨獲取即時發送和手機接收的證據。

4. 外部先決條件阻擋其各自的分支

在生成過程中，Claude Code 釐清了交付將如何劃分：「這些文件將把基礎傳送、驗證安全擴展、明確註冊/登入、Web/Admin 整合和真實供應商驗收作為獨立的交付項目進行追蹤。供應商帳戶、簽名、範本和國家權限限制了相應通道的驗收；它們不會阻擋模擬流程的獨立交付。」

這是一個實用的界限。如果 Twilio 目的地尚未啟用，則國際通道不能宣告為已驗收。這不要求每個開發活動都停止。模擬仍可以獨立執行傳送契約、電話與用途綁定、程式碼消耗和註冊/登入流程。反之，一個運作正常的模擬流程不能標記阿里巴巴雲、騰訊雲和 Twilio 為已驗收。這允許有用的增量向前推進，而不會在進度表中隱藏未完成的即時通道需求。

5. 最後一輪檢查前的一次失敗

並非所有檢查都一次通過。最初的規劃檢查發現了 45 個正式定義，但文件已經引用了兩個尚未生成的衍生圖表。它報告了缺失的連結目標：「完整的規劃結構失敗（45 個定義）。缺失的本地連結目標：implementation-gantt.svg。缺失的本地連結目標：implementation-burndown.svg。」

隨後生成了這些圖表，接著進行了新的規劃檢查和圖表新鮮度檢查：npm run spec:charts -- cabloy-sms、npm run spec:check -- cabloy-sms、npm run spec:charts:check -- cabloy-sms。

最終結果是：「完整的規劃結構通過（45 個定義）。檢查了 implementation-gantt.svg 和 implementation-burndown.svg（英文；0/10 已驗證）。」

「0/10 已驗證」很重要。生成圖表並未製造實作進度。所有十個交付任務仍處於「未開始」狀態。甘特圖代表任務組織和依賴關係；範圍計數燃盡圖代表記錄的狀態。兩者都不是基於實際交付歷史的排程承諾或速度預測。規劃檢查器也明確說明了其限制：它檢查靜態結構，而批准、語義充分性、實作和證據真實性仍需要人工審查。連接的識別碼不能證明設計是正確的。渲染的圖表不能證明功能有效。

6. 恢復的完成回覆

以下是那一輪的最終回覆，已翻譯成英文。其結論和狀態已保留；為便於閱讀，檔案連結已簡化為文件名稱。

Cabloy Basic 的完整英文規格基準已完成，全部位於 repo-specs/cabloy-sms/ 下。

文件進入點 | 文件內容

---|---

README | 規劃概述和閱讀順序

prd.md | 產品目標、用戶旅程、初始和延遲範圍

srs.md | 供應商/客戶/場景、驗證安全性、身份和並行性、Web/Admin 整合

pdp-wbs.md | 分階段交付、依賴關係和完成條件

test-plan.md | 12 個驗收情境和證據要求

progress.md | 初始狀態、未決決策和後續進入點

ADR 0001 | 建議的技術邊界和決策門

供應商執行手冊 | 通道配置、即時傳送驗收、故障處理和停用

還生成了兩張英文圖表：實作路線圖和範圍計數燃盡圖。

基準中記錄的重點

明確註冊：電話號碼 + 用戶選擇的使用者名稱 + 註冊碼；簡訊登入不會自動註冊用戶。國際號碼正規化為 E.164 格式；Web/Admin 重複使用現有身份、Passport 和共享網站。初始範圍包括模擬、阿里巴巴雲、騰訊雲和 Twilio；Vonage 延遲。

重複使用並安全擴展 a-captcha，而不是建立另一個 OTP 系統；涵蓋綁定、原子消耗、速率限制和通用入口點繞過風險。模擬自動填寫僅允許用於實際模擬傳輸，在生產環境之外，並明確啟用；真實通道絕不會將程式碼返回給前端。真實通道帳戶、簽名、範本和國家權限是單獨驗收的，不會阻擋模擬分支的實作。

檢查結果

spec:check：通過，包含 45 個正式定義和完整的追溯鏈。

spec:charts 和 spec:charts:check：通過。本地連結、空白和機器本地路徑隱私檢查通過；圖表已渲染並檢查。

僅規劃生成完成：ADR 仍為「建議」狀態，所有 10 個交付任務均為「未開始」狀態，沒有執行時或真實供應商驗收證據。未執行腳手架、依賴安裝、資料庫操作、真實傳送或提交。下一個候選是 WB。