【Day - 10】看過 Spectra 怎麼接續 OpenSpec，以及多提供了哪些流程與紀錄。這篇接著看流程與文件的處理：AI 從哪裡取得指引，文件寫好後會做哪些檢查，最後又怎麼把變更寫回正式 specs？
【Day - 8】介紹 OpenSpec 時，我們已經看過 Skill 透過 CLI 取得狀態與 instructions，也看過各個 Skill 怎麼提示下一步。Spectra 延續了這種分工，但初始化時還會在根目錄加入整體 workflow 導覽。既然 Skills 已經有自己的指引，這份導覽又多做了什麼？
我們先從這份導覽開始，再看各個 Skill 怎麼提示下一步，以及文件更新後、準備歸檔時，還有哪些事情要確認吧！
這篇使用哪個版本？ 以下延續【Day - 10】，仍以 Spectra 2.3.1 的 Skills、設定與 CLI 行為為準。
還記得【Day - 10】的初始化結構嗎？使用 Claude Code 時，Spectra 會在根目錄的 CLAUDE.md 注入一段管理區塊，並用 SPECTRA:START 與 SPECTRA:END 包住。這種由開始與結束標記包起來的內容，後面我就稱它為 marker block。
把裡面的內容精簡後，大致如下：
<!-- SPECTRA:START -->
# Spectra Instructions
## Use `/spectra-*` skills when:
- A discussion needs structure before coding → `/spectra-discuss`
- User wants to plan, propose, or design a change → `/spectra-propose`
- User asks about specs or how something works → `/spectra-ask`
## Workflow
discuss? → propose → apply ⇄ ingest → archive
<!-- SPECTRA:END -->
這段指引會告訴 AI：遇到什麼需求時，可以使用哪個 Skill，以及各個流程之間怎麼接。例如，需要先討論想法時使用 discuss，準備建立變更計畫時使用 propose。如果初始化時選擇的是 Codex，同樣的指引會放在 AGENTS.md，Skills 則放在 .agents/skills/。
OpenSpec 以前也放過類似的入口： OpenSpec 0.17.2 的 Claude Code 設定也會在執行
openspec init時，把 marker block 加進根目錄的CLAUDE.md或AGENTS.md。不過，當時的 template顯示，那段內容主要是提醒 AI 在哪些情況下打開openspec/AGENTS.md，完整的 workflow、spec 格式與專案規範仍放在另一份文件裡。到了 1.0，根目錄的 marker blocks 與
openspec/AGENTS.md一起被移除，流程指示改由各個 Skill 保存。Spectra 沒有直接照搬舊版作法，而是把哪些情況適合使用 discuss、propose、apply、ingest、archive 或 ask 寫進根目錄；每個流程完整的工作指引，則繼續留在各自的 Skill 中。
一開始，我還真的不太懂根目錄裡多一段 workflow 導覽會有什麼差別。實際用下來後才發現，當我打開 Claude Code，不一定要馬上呼叫某個 Skill，也可以先直接和 AI 聊聊目前想做什麼。聊到需求需要再整理，或是方向已經可以正式立案時，AI 有時候就會主動進入 discuss，或詢問我要不要直接使用 propose 建立 change。
這個體感真的很好，很像有一個很懂我的助手待在一旁，會在適合的時機提醒我接下來可以怎麼走。不過，有時候也會太主動了一點XD。我可能只是想問一個問題，Claude Code 看到 Spectra 的提示後，就自己使用 ask 幫我搜尋規格XD。
ask 是做什麼的？ ask 是當時 Spectra 另外設計的一個查詢 Skill，會搜尋
openspec/裡的正式 specs 與歷史 changes，再依照找到的文件回答專案功能、規格或 change 設計相關的問題。整個過程只會讀取文件，不會修改 code 或 artifacts。考量這次鐵人賽的篇幅，這裡先交代它的用途，後面就不另外介紹當時的 ask 流程了。
對我來說，這份導覽帶來的感覺，很像 AI 一開始就知道整條路要怎麼走，也知道現在可以往哪裡接。實際用下來，我會注意它建議進入哪個流程，再確認那是不是我這次想做的事。
現在有什麼不同？ Spectra 3.0.0 已不再提供前面提到的 ask Skill。根目錄仍會放入 workflow 提示，不過新版指引也多了一個條件：明確要求使用 Spectra 時，才進入 discuss 或 propose。
沒有這份導覽，AI 還知道可以使用哪些 Skill 嗎？ 還是有可能。以 Claude Code 為例，AI 可以先從 Skill 的描述知道它適合處理什麼需求，選用後再讀取完整指示。因此，即使沒有根目錄的 workflow 導覽，Skill 描述也能提供使用入口；只是它不一定會把各個流程之間的關係一起說清楚。
找到適合的 Skill 後，接著就要看：這一步做到哪裡該停，完成後又會提示我們往哪裡走？
根目錄的 CLAUDE.md 先列出整體 workflow，進入各個流程後，Skill 則會告訴 AI 這一步做到哪裡該停，以及接下來可以往哪裡走。【Day - 8】介紹 OpenSpec 時，也看過這種安排；到了 Spectra，流程有所調整，各個 Skill 的收尾與下一步提示如下：
| 完成的流程 | Skill 接下來怎麼處理？ |
|---|---|
| discuss（可選） | 討論收斂後先整理結論；準備正式建立 change 時，提示我們進入 propose。 |
| propose | 建立並驗證需要的 artifacts，完成後先停在規劃完成的狀態；提醒我們準備好後使用 apply，但不會直接開始實作。 |
| apply | tasks 全部完成後提示進入 archive；實作途中發現規格需要調整時，則可以先回到 ingest。 |
| ingest（需要時） | 更新並驗證 change 後讓我們選擇先結束，或直接接著進入 apply。 |
| verify（可選） | 回報實作與 artifacts 的核對結果；沒有需要先處理的問題時，提示可以進入 archive，但不會直接歸檔。 |
| archive | 先詢問是否同步正式 specs，再呼叫 CLI 完成歸檔，最後整理歸檔位置與執行時出現的警告。 |
當根目錄的流程導覽和這些下一步提示串起來，就是【Day - 10】圖中的 workflow。例如，discuss 談妥後可以進入 propose，規劃完成後再由我們決定是否開始 apply；實作途中需要調整需求，則透過 ingest 更新 change，再回到 apply。這些箭頭表示接下來可以怎麼走，不是 AI 一定會自動把整條流程跑完。
不過，Skill 不只會提示下一步。propose 建立完文件，或 ingest 更新完內容後，還有哪些檢查要先完成，才算做好這一步呢？
【Day - 9】已經介紹過，OpenSpec 的 validate 可以檢查 change 與 specs 的結構，執行 openspec archive CLI 時也會預設先檢查。Spectra 沿用了這個時間點，另外把同一項檢查提早接到 propose 與 ingest 的收尾：
也就是說，propose 建立好文件，或 ingest 更新完內容後，AI 會依照 Skill 的指示，呼叫 CLI 執行 validate，先確認文件格式有沒有問題。這樣就能在文件剛寫好或改完時發現問題，不必等到 archive 才處理。
這裡也可以看出 Skill 和 CLI 怎麼配合：Skill 告訴 AI 什麼時候要檢查，CLI 則實際檢查文件，再回報結果。不過，當時的 validate 檢查的是文件結構與格式，不會確認程式是否真的做出規格要求的功能，也不是每次 apply 都會執行。
現在有什麼不同？ Spectra 3.0.0 把部分封存檢查也放進
validate，讓可能無法合併的規格修改提早出現警告。檢查仍由 CLI 執行，Skill 則負責在適當的時機呼叫它。
前面的 validate 檢查文件格式；到了 archive，則要決定是否把變更寫回正式 specs。【Day - 10】看過歸檔後留下的快照與 @trace，這裡接著看歸檔時怎麼更新規格，以及遇到無法合併的內容時會怎麼處理。
要理解 Spectra 的作法，我們先補充【Day - 9】的 OpenSpec 歸檔流程。OpenSpec 1.0 除了讓 AI 使用 archive Skill，也可以直接在終端機執行 openspec archive <change-name>。這兩種方式適合什麼時候用，又有什麼差別呢？
平常和 AI 一起開發時，可以使用 OpenSpec 1.0 的 archive Skill，讓 AI 先確認文件與 tasks 的狀態，再詢問是否同步規格。如果選擇同步，AI 會依照 sync 的指引修改正式 specs，最後把 change 移進歸檔目錄。
如果想直接從終端機完成歸檔，或把歸檔接進腳本，則可以使用 openspec archive <change-name>，由 CLI 依固定規則檢查、合併規格，再搬移 change。OpenSpec 1.0 的 archive Skill 並不會直接呼叫這個指令，因此兩者的處理步驟也不同。
到了 Spectra 2.3.1，archive Skill 會先讓 AI 比較 delta specs 與正式 specs，整理這次要改哪些內容，再詢問是否同步；最後則會呼叫 spectra archive。我們仍然可以透過 AI 操作，但更新規格、保存快照與歸檔的工作，會交給 CLI 處理。把這幾種操作方式放在一起看，就能看出分工上的差別：
| 操作方式 | 誰更新正式 specs？ | 怎麼完成歸檔？ |
|---|---|---|
| OpenSpec 1.0 archive Skill | 選擇同步後，由 AI 依 sync 指引修改 | AI 把 change 移進歸檔目錄 |
OpenSpec 1.0 openspec archive <change-name> |
CLI 依固定規則合併 | CLI 把 change 移進歸檔目錄 |
| Spectra 2.3.1 archive Skill | 最後呼叫 spectra archive，由 CLI 處理合併 |
CLI 一起處理快照與歸檔 |
那麼，把更新規格的工作交給 CLI 後，如果正式 spec 裡找不到要修改的 requirement，會怎麼處理？這裡再補充兩套 CLI 的差異。
假設一份 change 同時修改兩個 capabilities，其中一份正式 spec 找得到要修改的 requirement，另一份卻找不到。OpenSpec 1.0 的 CLI 會停下來，兩份規格都不修改，也不會完成歸檔。Spectra 2.3.1 則仍可能讓這份 delta 通過 validate，接著更新找得到目標的那份規格，略過另一項修改，最後完成歸檔。
因此，使用 Spectra 2.3.1 時，即使 AI 在歸檔前已經比較過規格，看到 archive 完成後，還是要確認正式 specs 裡該改的內容都有更新。
現在有什麼不同？ Spectra 3.0.0 遇到同樣的情況，也就是
MODIFIED指定的 requirement 不存在時，會停止歸檔，兩份正式 specs 都維持原樣。新版也多了archive --preview，可以先看歸檔時預計更新哪些內容。
從前面的下一步提示，到檢查文件、確認是否同步規格，Skill 都會告訴 AI 接下來該做什麼。不過，像 archive 的例子一樣，除了看 AI 是否照著指引操作，我們也要確認最後的文件有沒有正確更新。
這篇看過了流程中的指引與檢查，真正開始實作時，又會遇到哪些問題呢？規劃可能已經跟不上 codebase，實作途中可能碰到 Bug，也可能有好幾項工作想同時進行。下一篇，我們就把焦點放到 apply 前後，看看 Spectra 怎麼協助處理這些情況吧！
iThome鐵人賽
看影片追技術