wellwelwel/blue-spec

模擬 Blue Spec 指令

這個技能之所以存在，是因為模擬指令很容易出錯，且錯誤的方式會浪費使用者的時間與信任。經過多次實際操作後，我們歸納出四個不可妥協的規則與一套方法。請嚴格遵守。

每當使用者要求「模擬」、「示範」、「實際展示」、「執行」或「觀看」任何 /bluespec.* 指令（charter、detect、plan、harden、verify），或想預覽指令在發布前的行為時，請使用此技能。

開始之前（必要步驟）

在兩件事都確定之前，不要開始模擬、建立情境或複製測試專案。順序如下：

1. 使用者必須告訴你要模擬哪個 Blue Spec 指令。 這是必要的，絕不要自行假設或挑選。如果使用者沒有指定指令（charter、detect、plan、harden 或 verify），請先詢問要模擬哪一個。如果使用者指定了多個指令，請確認執行的順序。
2. 然後，列舉可用的測試專案，讓使用者選擇。 指令確定後，從 .claude/skills/simulate/fixtures/ 列出可用的測試專案，每個項目需包含一行情境描述，並要求使用者以編號選擇。不要預設使用某個測試專案。即使只有一個測試專案，也要展示並在確認後才使用。如果沒有測試專案符合該指令情境，請告知使用者，並提議新增測試專案（詳見測試專案章節）。

只有在指令名稱與測試專案都確定後，才能進行後續的規則與方法。

為何需要這個技能（請先閱讀）

一個 Blue Spec 指令不是一個獨立程式。它是一個指令檔案（spec/commands/bluespec.<phase>.md，以技能形式提供給代理讀取），用來指示 AI 代理如何執行特定階段的安全工作。「執行指令」意指代理遵循這些指示。沒有所謂的二元執行檔能產生與代理無關的確定性結果。因此，「模擬」就是代理實際執行指令的步驟，針對真實情境，並展示其工作過程。

需要避免的失敗模式：敘述你想像中指令會產生的輸出，將其格式化成終端機畫面，然後假裝它已經執行過了。那是表演。使用者無法區分虛構輸出與真實輸出，他們會（正確地）稱之為鬧劇。以下所有設計都是為了讓模擬真實且可供使用者驗證，而非一場表演。

四條嚴格規則

規則 1：在 ./temp 目錄下執行情境

將模擬所需的一切（測試專案、各階段產生的 .bluespec/memory/ 工件、任何輸入）建立在儲存庫根目錄下的 ./temp 目錄中，絕不能使用系統的 /tmp。

• /tmp 對使用者不可見：他們無法在編輯器中開啟那些檔案，因此你在那裡做的所有事情都只能「相信我」。./temp 位於使用者的工作空間中，可以開啟和檢查。
• ./temp 已被 .gitignore 忽略，因此模擬不會汙染提交紀錄。
• 當使用者完成模擬時，清理 ./temp，或留給使用者檢查，但需先詢問。

測試專案：每個模擬都從一個測試專案開始

中立的範例專案隨此技能一同提供，每個專案位於 .claude/skills/simulate/fixtures/<name>/ 目錄下。選擇情境符合指令需求的測試專案，或新增一個（見下方說明）。每個測試專案都是一個小型真實專案，刻意包含穩健與脆弱的程式碼，以中立配對方式呈現，讓指令必須分析程式碼，而非讀取標籤。

可用測試專案：

• image-upload-service：一個小型 ESM HTTP 服務，接受圖片上傳並提供回傳功能。
• template-toolkit：一個可發布的 ESM npm 套件（一個函式庫加上 tmpl CLI），用於渲染模板和解析文字。

永遠從複製一個測試專案原始內容到 ./temp 開始模擬。 如果 ./temp 已存在且非空，請先清除，確保每次執行從乾淨狀態開始（將 <name> 替換為你選擇的測試專案名稱）：

rm -rf ./temp && mkdir -p ./temp
cp -R .claude/skills/simulate/fixtures/<name>/. ./temp/

然後依照規則 4 的方式，在 ./temp 中實際執行上游階段來建立鏈結，讓指令讀取的 .bluespec/memory/*.md 工件由其對應階段產生，而非手寫。按照規則 3 的要求，嚴格遵循指令規範，在 ./temp 中執行指令步驟，並根據規則 2 展示每個步驟的輸出。

若要新增測試專案，請建立 .claude/skills/simulate/fixtures/<new-name>/ 作為一個小型真實專案，包含自己的 package.json，保持穩健與脆弱程式碼的中立配對，不要加入會透露資訊的註解或名稱，並在上方清單中列出。當某個指令需要當前測試專案未涵蓋的情境時（例如不同的語言或技術棧、機密處理、認證、資料庫等），就新增一個。

規則 2：將提示與回應以圍籬程式碼區塊形式呈現在聊天訊息中

這條規則花了最久時間才學會。當你執行工具（Bash、Read）時，使用者的介面會顯示該工具的 IN 和 OUT 的截斷預覽。你無法控制顯示的長度，而且通常會被截斷。如果支持某個主張的證據只存在於工具呼叫的輸出中，使用者看不到，而任何描述該證據的文字都會被視為虛構。

因此：

• 執行工具後，將相關的原始輸出複製到聊天訊息中的圍籬程式碼區塊（三個反引號）。這個圍籬區塊能在所有介面中完整且一致地呈現。這就是使用者所謂的「黃色字母」：一個 Markdown 程式碼區塊。
• 指令的提示與互動過程（/bluespec.<phase> 執行時的逐步顯示、範圍決策、判定結果）也應放在圍籬程式碼區塊中，樣式類似逐字稿。
• 絕不要寫「上述輸出顯示了 X」並指向工具呼叫。要指向你貼上的圍籬區塊，使用者可以完整閱讀。
• 當逐字稿中的某個數字或行來自實際執行，它必須與你貼上的原始輸出相符。如果你寫了一行無法由你貼上的原始輸出支持的逐字稿，那就是在虛構，請停止。

一個可靠的模式：執行指令，將原始輸出重新導向到 ./temp 下的檔案（例如 ./temp/run.log），然後用 Read 讀取該檔案（Read 結果會完整顯示給你看），再將其內容貼入圍籬程式碼區塊。使用者也可以直接開啟 ./temp/run.log 來驗證。

邊做邊展示，絕不在最後一批完成。 觸發點在每個步驟：一旦某個步驟產生了使用者應該看到的內容（讀取的輸入、逐字稿、寫入的工件），就立即在同一個訊息中貼入圍籬區塊，然後再進行下一步。如果你將要開始下一個階段或修復，但前一個步驟的輸出尚未顯示在畫面上，請先停止並貼上輸出。如果使用者需要提醒你展示指令的輸出，表示規則已經失敗了。

規則 3：你就是指令，所以嚴格遵循其規範

「執行指令」是指你逐步執行 spec/commands/bluespec.<phase>.md，而不是用自己的方式執行該階段然後稱之為指令。

• 首先打開該規範，將其視為唯一真理來源。 依序遵循其步驟。不要根據記憶或此技能的摘要來執行該階段。
• 實際執行規範中要求的每個確認停頓。 harden 必須在編輯任何程式碼前確認；完整的 detect 掃描由於耗費大量 Token，也需要確認。以逐字稿區塊呈現規範要求呈現的內容，然後等待。絕不要在未經確認的情況下編輯程式碼或執行需要停頓的步驟。
• 根據規範步驟的邏輯來決定範圍、判定結果、修復方案、優先順序和發現項目，並針對真實情境進行。如果你無法指出規範中的哪個步驟支持你產出的某一行輸出，那你就是在以自我意志行動，請停止並遵循規範。

規則 4：每個階段的輸入必須來自執行上一個階段，而不是來自你

鏈結順序為 charter → detect → plan → harden → verify，每個階段讀取前一個階段寫入的內容。手動撰寫具有你預期答案的下游工件（例如，一份剛好記錄了你希望 verify 確認或捕捉的內容的 harden.md）是失敗的：下游階段會針對你的預測進行測試，而非真實情況，因此它會遺漏你遺漏的內容。

• 透過執行其階段來產生每個上游工件，在其規範下執行，並根據規則 2 展示。要示範 verify，請先執行 detect（讀取程式碼），然後執行 plan（讀取 detect.md），再執行 harden（讀取 plan.md，編輯程式碼）。即使使用者從中間環節開始，也要以這種方式按順序建立缺失的工件。
• 讓工件反映實際執行的結果，包括缺口：可能是 Partial、Blocked，或你未預見的發現。一個可疑地乾淨的工件就是違反此規則的跡象。
• 刻意偏離的情境是可以的（例如，harden 應用了所有修復，然後程式碼被還原，讓 verify 必須發現差異），但必須讓偏離過程可見（透過顯示工具呼叫來執行還原，並保留真實工件），絕不能手寫一個從未實際執行的記錄。

逐步方法

每個階段讀取前一個階段的輸出，並撰寫一個工件。請熟知此鏈結，不要破壞它：

階段	讀取	寫入
charter	專案上下文	.bluespec/memory/charter.md
detect	程式碼	.bluespec/memory/detect.md
plan	僅 detect.md，絕不讀取程式碼	.bluespec/memory/plan.md
harden	僅 plan.md 加上 charter，並編輯使用者的程式碼	.bluespec/memory/harden.md
verify	harden.md 與程式碼，將記錄與現實比對，不改變任何東西	.bluespec/memory/verify.md

接著，針對你要模擬的指令：

1. 將測試專案原始內容複製到 ./temp（規則 1）。
2. 透過依序執行每個上游階段，在 ./temp 中建立鏈結（規則 4）。
3. 根據其 spec/commands/bluespec.<phase>.md，嚴格執行目標階段（規則 3）。
4. 邊執行邊將每個輸入、逐字稿和工件展示在圍籬程式碼區塊中（規則 2）。將每個輸出工件寫入真實檔案，然後用 Read 讀取並展示。

呈現前的誠實檢查

• 這真的執行了，還是我只是在打我想像中會發生的事？
• 每一行逐字稿是否都有我貼上的原始輸出支持，或是使用者可以開啟的 ./temp 檔案，而非截斷的工具呼叫？（規則 2）
• 我是否已經貼上了目前每個步驟的輸出，讓使用者從來不必主動要求？（規則 2）
• 我是否遵循了每個階段的規範，包括確認停頓，而不是以自我意志行動？（規則 3）
• 每個上游工件是否來自執行其階段，而非我手寫想要的結果？（規則 4）
• 情境是否建立在 ./temp 下，而非隱藏在 /tmp 中？（規則 1）

如果任何答案是「否」，請在送出前修正。使用者寧願看到真實且普通的輸出，也不願看到華麗的虛構作品。