給代理的規格書：如何把想法變成任務

連續給代理兩個請求。第一個是："照 SPEC_LANDING.md 這個檔案裡的規格書做出頁面"。幾分鐘後，資料夾裡出現了 index.html，看起來跟預想的一模一樣。第二個是同一天晚上的："做一個 2048 遊戲"。這次代理要不是一口氣問您五個問題，就是默默做出一個 5×5 的棋盤，還附上一個沒人要求的"悔一步"按鈕。

差別不在代理，而在它拿到的輸入。這篇文章會說明一個小任務的規格書由哪些部分組成、要寫進去的內容從哪裡來、只知道大方向時該怎麼辦，以及為什麼在代理說"完成"之後，您要用開工前寫下的那幾行來檢查結果。

1. 想法還不是任務

"我想要 2048"。"做一個漂亮的頁面"。"做個新遊戲，有趣一點的"。這些都是想法，而它們有同一個毛病：您腦中有一整幅畫面，寫出來的卻只有幾個字。代理只看得到文字。

遇到請求裡的空白處，代理有兩條路。第一條是發問。第二條是自己補上：選一個棋盤大小、編一條規則、加一個按鈕。第二條路比較安靜，所以也比較危險。在看到結果之前，您不會發現決定已經有人替您做了。請求裡每一個沒填的空白，都是一個總會有人做出的決定，而預設情況下，做決定的不會是您。

"大家都知道 2048 怎麼玩"，這句話只存在於您的腦袋裡。代理讀不到這個"大家都知道"。棋盤多大？新方塊從哪裡冒出來、什麼時候冒出來？哪些方塊會合併，合併成什麼？什麼時候算贏、什麼時候結束？對您來說是一個詞，對它來說在拆成規則之前都是空白。在聊天中看起來是這樣：

您：   做一個 2048 遊戲
代理： 開始之前先確認幾件事：
       1. 棋盤是 4×4 嗎？
       2. 怎樣算獲勝？
       3. 需要悔一步的功能嗎？

這是好的結果。同一個請求，也可能是另一種走向：

您：   做一個 2048 遊戲
代理： 完成了。遊戲在 index.html 檔案裡：
       - 5×5 棋盤
       - 撤回上一步的按鈕
       - 存在 localStorage 裡的最高分排行榜

這不是代理的錯。這是您留下的三個空白，只是沒問過您就被補上了。

這就是從想法走到可信結果的路徑。這篇文章會從左到右沿著它走一遍。最後一步則會回到第三步：檢查、找到漏洞、在規格書裡補一行，再交給代理一次。

2. 內容從哪裡來

頁面或遊戲的骨架，代理幾分鐘就能做好，這確實不是最難的部分。難的是知道頁面上應該有什麼，以及這到底是個什麼樣的遊戲。這些東西程式碼裡沒有。它們在人的腦袋裡，有時就在您自己腦中，也有一部分是代理知道的。要靠提問把它挖出來，來源有三個：其他人、您自己、代理。

其他人，指的是提出需求的人和將來要用的人。問他們問題，最好一次問一批。一次列出五、六個問題，而不是一天問一個。一次問一批看起來有點煩人，這我知道。實際上它能幫大家省下一整個星期的往返訊息。

當提出需求的就是您自己（自己的遊戲、自己的頁面），問題就得問自己，這時最大的誘惑是回答"這不是很明顯嗎"。明顯的事和不明顯的事一樣要寫下來。"棋盤 4×4"只要兩秒鐘，對代理來說卻能排除一整個分岔。

第三個來源是代理，這裡有個最好事先知道的陷阱：您沒辦法問自己不知道的事。什麼都沒移動的一步算不算一步？手機上需要支援滑動嗎？要不要顯示分數？這些問題在遊戲出現在眼前之前，根本不會想到。而代理看過上千個這類遊戲，知道大家通常在哪裡卡住。所以有時候，與其一開口就說"做出來"，不如先說"我們來討論一下"：

我想做一個在瀏覽器裡玩的 2048 遊戲。先什麼都不要寫。
把你開工前一定要知道的問題問我。一次全部列出來。
我回答完，我們再把規格書整理到 SPEC_2048.md 檔案裡。

這種對話有兩條規則，不然它會沒完沒了。第一，四根支柱（下一節會講）都填好了，討論才算結束，而討論的成果是一個檔案，不是聊天紀錄。第二，代理的問題是選項，不是要求。它很樂意問"那排行榜要做嗎？"，而"不要"是完全正常的回答。這個"不要"也是規格書裡的一行，只是放在"不做"那一欄。

不管是誰問的，是您問還是代理問，答案都要寫進規格書檔案，而不是留在聊天裡當一句話。否則下一個請求又會從同一個漏洞開始。

左邊三個來源，右邊一個目的地。往下的虛線箭頭，是答案最常走的那條路：留在聊天裡，十則訊息之後就再也找不到了。圖上有這支箭頭，箭頭盡頭卻沒有檔案。

您還可以要求代理做得更多：不只是發問，還可以根據您的回答自己起草一份規格書，把您沒說到的地方補上。至於它自己補出來的部分該怎麼處理，第 4 節會談。先來看規格書由什麼組成。

3. 規格書的四根支柱

一個小任務的規格書，大約六到八行。撐起這幾行的是四根支柱：目標、應該發生什麼、第一版不做什麼、怎麼檢查。以遊戲為例，完整內容如下：

# 規格書：2048

目標:   瀏覽器上的 2048 遊戲，直接開啟檔案就能玩，不用安裝。
        HTML、CSS 和 JavaScript，不用建置

規則:   4×4 棋盤
        開局時和每一步之後都會出現一個新方塊：2 或 4
        方向鍵把所有方塊往同一個方向推到底
        兩個相同的方塊相撞時，合併成一個，數字為兩者之和
        獲勝：棋盤上出現 2048 方塊
        失敗：沒有可走的步，棋盤滿了，也沒有可以合併的方塊

不做:   最高分排行榜、動畫、悔一步

檢查:   在瀏覽器開啟 index.html，看到棋盤和開局方塊
        用方向鍵走三步，每一步之後都出現新方塊
        把兩個 2 合在一起，得到 4
        玩到最後，看到失敗畫面

接下來一根一根支柱來看，每一根都用兩個任務來示範：這個遊戲，以及一個桌遊社聚會的邀請頁面。

目標

第一行。讀完這一行，人應該能想像出成果，而不是程式碼。"瀏覽器上的 2048 遊戲，直接開啟檔案就能玩，不用安裝"。"桌遊社聚會的邀請頁面：看的人知道這是什麼聚會，並且按一個按鈕就能報名"。

檢查目標的方法：如果讀它的時候，您看到的是程式碼，而不是使用者會看到的東西，那它就已經不是目標了。"寫一個合併方塊的函式"不是目標，而是工作的一小塊。

這裡也要用一行寫上"用什麼做"：HTML、CSS 和 JavaScript，不用建置。少了這一行，代理會自己選，而它選的不一定是您知道怎麼執行的東西。

至於"做得漂亮一點"，則不能當作目標。說不清是對誰來說漂亮，也說不清要在哪裡看出來。

應該發生什麼

這是最長的一根支柱，遊戲的部分上面已經寫好了。規則只有一條：一行寫得好不好，就看執行之後能不能看著它說出"是"或"否"。"棋盤 4×4"：是或否。"兩個相同的方塊合併成一個，數字為兩者之和"：是或否。"有趣一點"：既不是"是"也不是"否"，這種行不該出現在規格書裡。

一行只寫一件事。"方塊會出現並合併"是兩項檢查，所以要寫成兩行。

頁面也一樣，只是規則換成了頁面上有什麼："有名稱和日期的頁首"、"三個區塊：活動內容、適合誰、地點"、"報名按鈕連到表單網址"。每一項都可以打開來親眼確認。

跟想法擺在一起，這種清單看起來很無聊。無聊正是好事。無聊的東西才檢查得了。

第一版不做什麼

這是唯一一根常被忘記的支柱，也因此最有價值。空白處代理會自己補上，而它最愛用的補法就是加東西。排行榜、方塊動畫、悔一步按鈕、深色主題。這些都很有用，也都不是您要求的。

要逐項寫出名稱。不是寫"不要多餘的東西"（這不是界線，只是願望），而是寫"不做：排行榜、動畫、悔一步"。頁面則是："不做：報名表單本身、付款、相簿"。通常寫三項就夠了，反正也沒有人會寫到十項。

這一條是為了您，而不是為了代理。做出來的東西越少，要檢查的就越少。壞掉的東西是從哪裡來的，也越容易看出來：在六行裡找，總比在六個畫面裡找容易。沒有界線的訊號是：您的請求裡或代理的回覆裡，"順便"這個詞開始頻繁出現。

怎麼檢查

"應該發生什麼"裡的每一行，都是代理說"完成"之後的一項檢查。打開遊戲：4×4 棋盤，有。按下方向鍵：方塊移動了，出現一個新的，有。把兩個 2 合在一起：得到 4，有。檢查清單不用另外寫，它已經寫好了。

另外，在規格書裡再加兩三行"檢查"：具體要動手做什麼。"在瀏覽器開啟檔案，走三步，玩到輸為止"。這幾行要在提出請求之前寫，而不是之後。看到結果之後再寫，就會不知不覺配合做出來的東西去調整，這是自然而然會發生的事，您也不例外。

代理說的"完成"只是一句話，不是檢查。檢查是您的事，依照您寫的那幾行來做。

接下來動手練習。拿"幫桌遊社聚會做一個漂亮的頁面"這個請求，把它拆成四根支柱，每根寫一兩行。答案就在下面，寫完對照一下：

# 規格書：邀請頁面

目標:      桌遊社聚會的邀請頁面：
           看的人知道這是什麼聚會、時間和地點，並按一個按鈕就能報名。
           單一 HTML 檔案，樣式寫在裡面

頁面內容:  有社團名稱和聚會日期的頁首
           三個區塊：活動內容、適合誰、地點
           "報名"按鈕連到表單網址

不做:      報名表單本身、付款、相簿

檢查:      在瀏覽器開啟，看到頁首和三個區塊
           按下按鈕，進入表單網址

請注意，"漂亮"這個詞根本沒有寫進規格書。它沒辦法檢查。如果漂亮真的很重要，就像其他所有東西一樣，把它拆成幾行："頁首放一張圖"、"不超過兩種顏色"、"整個頁面在手機螢幕上都放得下"。這樣就能打開來看了。

兩個範例裡的區塊名稱不一樣：遊戲用"規則"，頁面用"頁面內容"。這不重要，您覺得怎麼方便就怎麼命名。重要的是，每一份都有四根支柱：

4. 這是誰的決定

規格書裡會出現沒有人確認過的決定，情況通常有兩種。第一種：您允許代理用"某個合理的做法"補上漏洞，好讓您現在就拿到草稿，而不必等到星期二才有答案。第二種：您自己替需求方做了決定，因為找不到人問，或是沒時間問。

兩種情況都很正常。不正常的是忘了這是一個假設。一個星期後，沒有人會記得是誰決定讓按鈕連到電子郵件而不是表單，偏偏大家爭的就是這件事。

第一種情況，給代理的請求長這樣：

根據這些回答，幫邀請頁面起草一份規格書。
沒有答案的地方，就想一個合理的做法，並另外列一份清單，
寫出哪些是你自己想的。寫進 SPEC_INVITE.md 檔案。

代理自行補充的那份清單，要比規格書本身先讀。這些是替您做的決定：每一項要不是交給了解狀況的人確認，就是帶著標記留在規格書裡。

第二種情況，則是在檔案裡直接做標記。在決定前面加上"假設："，或乾脆在行尾加個問號："按鈕連到社團的電子郵件（?）"。等答案來了，一眼就看得出要改哪裡。也不用去回想這是從哪來的。

標記是雙向的。代理拿到一份帶問號的規格書，通常會先問這些地方：對它來說，這跟對您一樣是個訊號。

5. 用沙盒代替提問

有時候，四根支柱怎麼想都寫不出來。"我想要一個類似 2048 的東西，但不知道要不要分數、要不要滑動，也不知道到底是不是 4×4"。這不是規格書，甚至也不是一般意義上的想法。這是一個方向：大方向清楚，結果卻不清楚。這時提問幫不上忙：您和需求方都還沒有答案，而代理提出的選項，您也沒有東西可以拿來比較。

這種時候，最省事的做法是先看看。做一個沙盒：最簡單的版本，可以看一眼、摸一摸，搞清楚自己真正想要什麼。有代理幫忙，這只要十分鐘，只花十分鐘做出來的東西，丟掉也不可惜。

沙盒也要寫一份四根支柱的規格書，只是目標不同：

# 規格書：2048 沙盒

目標:   看看 2048 在瀏覽器裡玩起來怎麼樣，搞清楚我想要什麼。
        HTML、CSS 和 JavaScript，不用建置

規則:   4×4 棋盤
        方向鍵移動方塊，相同的方塊會合併
        每走一步出現一個新方塊

不做:   其他全部：獲勝、失敗、分數、滑動、美化

檢查:   玩五分鐘，記下缺了什麼、多了什麼

看看有什麼不一樣。目標不是遊戲，而是弄清楚想要什麼。"不做"是最長的一行，裝的是所有您不確定的東西。而檢查也不是"能不能動"，而是"我現在知道了什麼"。玩個五分鐘，一開始問不出來的問題就會自己冒出來：滑動不需要，在電腦上都用方向鍵玩；分數需要，沒有分數很無聊；4×4 太小，想試試 5×5；失敗要顯示出來，不然搞不清楚遊戲已經結束了。

這些就是沙盒的成果。不是程式碼，而是答案。用這些答案寫出真正的規格書，再從零開始，在一個乾淨的資料夾裡，用一句話讓代理做出來："照檔案裡的規格書做出這個遊戲"。沙盒的任務就完成了。

這就是第一節那條流程，只是"提問"這一步換成了一個迴圈：沒有問題可問時，就先看，再寫下來。往下流進規格書的只有一樣東西：答案。沙盒沒有箭頭通往代理，這不是忘了畫：真正的版本要在乾淨的資料夾裡從零開始做。之後就照著流程走。

6. 規格書放在檔案裡

為什麼是檔案，而不是聊天紀錄。聊天紀錄會被淹沒：十則訊息之後，關於方塊合併的那條規則就找不到了。檔案放在專案資料夾裡，就在程式碼旁邊，您指給代理看，它就會自己去讀；修改之後要再交給它，也還是同一句話。檔名隨意：SPEC_2048.md、SPEC_LANDING.md，甚至 task.txt 也行。這就是一般的文字檔，沒有什麼特殊格式。

交給代理只要一句話。比較一下：

之前："做一個 2048 遊戲，你懂的那種，有趣一點"。

之後："照 SPEC_2048.md 這個檔案裡的規格書做出遊戲"。

第二個請求比第一個短，資訊量卻多了十倍：資訊都在檔案裡。不需要把規格書的內容貼進聊天，代理會自己打開檔案。

哪些要改檔案，哪些用說的就好。判斷方法是這樣：規則或界線變了，就修改檔案，再交給代理一次（"獲勝是 2048，不是 1024"，這要寫進檔案）。只是外觀上的小地方，不影響規則，用說的就可以（"把按鈕改成藍色"）。拿不定主意，就寫進檔案：多一行的代價，比忘掉一條規則小得多。

關於長度。小任務的規格書就是六到八行，像上面 2048 的那份一樣。如果一個晚上就能做完的遊戲，規格書卻寫成了兩頁，那多半是把該放進"不做"的東西寫進去了。

最後，在把檔案交給代理之前：用看別人文件的眼光讀一遍。幾乎每次都會找到一行沒辦法檢查的內容。我自己也每次都找得到。

7. 代理拿規格書做什麼，什麼留給您

最後把所有內容整理在一起：在這套做法裡，Claude Code 負責什麼，您這一邊又負責什麼。兩兩對照。

規格書的意義不在於讓代理看懂。就算只有兩個字，它也會做出點什麼。意義在於讓您自己清楚知道要的是什麼，並且能夠檢查。