可供檢查的 TASK_SPEC

"做一個計算器，算出大家在餐廳各自要付多少。"這個要求聽起來很清楚，直到您開始細想：費用要平均分攤，還是每個人只付自己點的餐點？小費已經算在帳單裡了嗎？如果總額無法平均分給所有人，該顯示什麼？

我們和 Claude Code 一起整理任務規格：您說明任務並做出決定，代理把決定寫進檔案，再由您檢查記錄。先從簡短的要求開始，一步步整理成可據以工作的 TASK_SPEC。

"做好一點"不是任務

想像一下：您只想快速分帳，代理卻加上註冊功能和餐廳紀錄。為了儲存帳單，它還需要一台伺服器。您原本以為只要在瀏覽器開啟一個檔案，現在卻得研究如何啟動，還要移除多餘功能。每項新增功能單看都很有用，但最後的結果已經和您的想法差得很遠。

處理程式碼時，沒說清楚的地方可能變成實際的檔案修改。過程大致如下：

這張圖呈現了漏掉一個決定如何帶來額外工作。代理可能會反問，但最好在修改前就找出不明確之處。第一句描述就可以先定下方向和範圍：

目前還不清楚：
做一個計算器，算出大家在餐廳各自要付多少。

再具體一點：
需要一個頁面：輸入帳單總額和人數，
顯示每個人要付的金額。費用平均分攤。
不做帳戶、帳單紀錄，也不按餐點分帳。

第二個要求仍未回答所有問題，但已經排除了第一個要求可能衍生出的幾種不同產品。接下來，代理會協助找出剩下的問題，並記下您的決定。

把任務寫在一個檔案裡

TASK_SPEC 是一份任務條件紀錄：需要什麼結果、工作到哪裡為止，以及要如何檢查。通常會將它存成 Markdown 檔案 TASK_SPEC.md，放在專案旁邊。這個名稱沒有對應的特殊格式或專用指令。您也可以直接在訊息中提供條件，不過檔案比較方便重讀和更新。

不必手動撰寫 TASK_SPEC。和代理一起整理，再檢查它如何記下您的決定，會更方便。您可以用一般文字描述任務、回答問題，或要求調整措辭。代理維護檔案，您則確認內容是否符合原意。

1. 您說明想完成什麼，並討論不清楚的部分；
2. 代理提出幾種做法，由您選擇合適的方案；
3. 代理把決定寫進 TASK_SPEC，並展示新增或修改的片段；
4. 您在檔案中閱讀該片段：原意沒有改變、沒有多出條件，也沒有和先前的記錄矛盾。如果有問題，就請代理修改，再次檢查。

每做出一個決定，只要檢查受影響的行和相關條件即可。開始實作前，請重讀整份檔案：各項記錄分開看似乎都正確，放在一起卻可能互相衝突。只看到"我已更新規格"這句話，還不知道文件裡實際寫了什麼。

CLAUDE.md 和 TASK_SPEC 的差別在於用途。"專案中的所有介面文字都用中文"是專案通用規則；"這次任務要加入小費計算"則是特定工作的條件。前者適合放在 CLAUDE.md，後者放在 TASK_SPEC。

文件長短取決於任務。如果只需要修正已完成頁面上的錯字，這樣描述就夠了：

請修正分帳頁面上的按鈕標籤錯字：
"計箅"→"計算"。其他內容不要改。
確認新標籤有顯示，而且按鈕仍能計算。

這是一份簡短的 TASK_SPEC，有時也稱為 tiny spec。這裡幾乎沒有什麼需要討論。新的計算器則可能有好幾種行為，因此兩行描述就不夠了。值得記下的是會影響結果的決定；標題數量本身並不能保證內容完整。

從結果開始

假設目前還沒有專案。一群人想在瀏覽器開啟一個頁面，輸入帳單金額，看看每個人要付多少。請代理先建立草稿：

為分帳頁面建立 TASK_SPEC.md。
目前還沒有專案。輸入帳單金額和人數，
按下"計算"後顯示每個人的分攤金額。
產出需要是一個不必安裝、可在瀏覽器開啟的 index.html。
記下已確認的條件，未知事項標記為問題。
展示寫下的內容。先不要撰寫頁面程式碼。

以下是檔案第一段的教學範例：

## 背景
一群人想快速分攤在餐廳消費的總帳單。
目前還沒有專案，工作資料夾是空的。

## 預期行為
使用者輸入帳單金額和人數。
按下"計算"後，看到每位參與者應付的金額。
工作成果：index.html 頁面，
不必安裝即可在瀏覽器開啟。

在編輯器中開啟 TASK_SPEC.md，對照原本的要求：兩個欄位、操作方式，以及每位參與者的結果都在裡面。如果代理加上姓名輸入或強制註冊，那些條件並未經過確認。請它從檔案中移除，再檢查修改結果。

現在已經清楚誰會使用頁面，以及他們會得到什麼。同時也說明了交付成果，也就是代理工作的具體結果：頁面檔案。其他任務的成果可能是錯誤分析，或是不包含程式碼的修改計畫。最好直接說明。

請注意，我們還沒有挑選 JavaScript 函式，也沒有指定如何儲存參與者資料。這些屬於實作決定。任務規格更重要的是記下使用者會看到什麼：輸入、操作和結果。

任務的範圍到哪裡

接著要明確定義第一版做到哪裡為止。請代理記下已確認的範圍，並展示更新後的區塊：

## SCOPE
一個頁面：輸入金額和人數，
平均分攤總額，顯示每個人的分攤金額。

## NON-GOALS
不做帳戶和帳單紀錄：不需要儲存資料。
不按餐點分帳：第一版採平均分攤。
實作限制：使用單一 HTML 檔案，內含樣式和 script，
不使用伺服器或外部函式庫。
頁面必須能以雙擊方式開啟。

檢查這段內容時，不只要確認排除項目有寫上去：平均分攤必須留在任務範圍內，按餐點分帳則應該排除在外。如果代理把兩者弄反，請先修正文件，再開始處理頁面。

Scope 說明工作的範圍。像這個例子，可以透過畫面和使用情境來描述。知道確切路徑時，寫上路徑會有幫助，但不一定要先列出檔案。如果您正在修改既有專案，卻不知道頁面在哪裡，可以請 Claude Code 先搜尋，不要修改任何內容，並說明為什麼選了那個檔案。接著再把路徑補進任務規格。未知事項可以保留，但不能憑空編造。

Non-goals 是刻意排除的事項。"不做帳單紀錄"比"不要做多餘的事"更能說清楚範圍。簡短的原因也對您有幫助：一週後回來看，仍能知道當時考慮過儲存資料，最後決定不做。

實作限制回答的是另一個問題：哪些做法適合這個任務。帳戶是多餘功能，伺服器則是我們明確排除的一種實作方式。短文件可以把這些條件放在同一區塊，但要清楚標示哪些是限制。

範圍設定仍要讓目標可行。若之後需要在不同裝置上共用帳戶和帳單紀錄，就得重新考慮"單一本機 HTML 檔案"的要求。不能一邊要求新增功能，一邊保留讓它無法實現的限制。

少算的一分錢

目前看起來已經相當明確。先在寫程式之前檢查任務規格：三個人一起用餐，帳單是 1000。每個人應該付多少？

333.33 + 333.33 + 333.33 = 999.99

少了一分錢。可以加給第一位、最後一位，或讓使用者選擇。"平均分攤"並沒有說明要怎麼處理。這是需要您決定的事，不是 JavaScript 知識問題。

這個頁面採用以下規則：每人的金額最多相差一分；剩餘金額每次分一分給名單前面的參與者。因此 1000 元由三人分攤，結果是 333.34、333.33、333.33；若總額是 1000.01，剩下兩分，結果則是 333.34、333.34、333.33。所有金額都分配完畢，各份金額加總也會等於帳單總額。

現在請代理把選定的規則記進文件：

把四捨五入規則寫進 TASK_SPEC.md 的預期行為。
展示修改過的行。先不要改程式碼。

檢查檔案中是否出現類似這樣的記錄：

每份金額加總後恰好等於總額。
各份金額最多相差 0.01。
剩餘的每一分依序分給名單前面的參與者；
頁面上要說明這項規則。

特別留意"依序分給名單前面的參與者"這幾個字。如果代理寫成"全部餘額都給第一位"，那就改變了決定：剩下兩分時，第一位會比其他人多付 0.02。請它修正這一行，再次檢查檔案。重點是意思正確，不必逐字相同。

這就是為什麼在任務規格裡代入數字很有用。我們在代理選擇做法並據此寫程式碼之前，就找到了漏掉的決定。目前只修改了幾行。

讓 Claude 來提問

有些問題您不一定會自己注意到。把草稿交給代理，請它專注協助整理任務規格：

閱讀 @TASK_SPEC.md，幫我找出還缺少哪些條件。
一次問一個問題，並為每個問題提出一個建議答案。
我回答之前，不要把你的建議當成已確認的決定。
每確認一項決定，就更新 TASK_SPEC.md，
並展示修改過的片段，讓我檢查。
先不要寫程式碼。

以下是一段對話範例。您實際使用時可能會遇到不同問題；這裡要看的是回答如何改變文件。

Claude："小費包含在帳單金額裡，還是要另外加上？我建議新增一個百分比欄位，預設值為 0。"
您："另外加。百分比以帳單金額計算，小費加在帳單上，再把總額一起分攤。頁面要顯示小費金額和總額。"

Claude："如果小費算出來有不到一分的金額，要怎麼四捨五入？我建議四捨五入到最近的一分，剛好半分時進位。"
您："好。先把小費金額四捨五入，再加到帳單上，最後依照我們的規則分攤總額。"

Claude："哪些數值可以接受？我建議輸入大於 0 的金額，小數點或逗號都可以；人數必須是大於等於 1 的整數；百分比則是大於等於 0 的整數。欄位輸入錯誤時，在旁邊顯示提示。"
您："可以。金額的小數部分最多兩位，千位之間不加空格。如果欄位是空的或數值不正確，就隱藏結果，即使先前已經算出結果也一樣。"

不只小費的條件釐清了。現在也定義了可接受的輸入、四捨五入順序，以及發生錯誤時的行為。把答案記下來後，再檢查更新過的文件片段：

小費：獨立欄位，整數百分比，最小值 0，初始值 0。
依帳單金額計算小費，並四捨五入到最近的一分；
剛好半分時進位。
將四捨五入後的小費加到帳單，再分攤總額。
顯示小費金額、總額，以及每個人的分攤金額。
欄位空白或數值不正確時隱藏結果，
並在對應欄位旁顯示提示。

檢查計算順序：先將小費四捨五入，再加到帳單，最後分攤總額。同樣的詞語如果順序不同，代表的要求也會不同。也請代理更新 scope：第一版新增了小費欄位和總額計算。確認它確實修改了這兩個區塊，而不是只在對話中說已完成。

結果與檢查方式

"每份金額加總等於總額"是對結果的要求。"輸入 1000、3 人和 0% 小費，按下按鈕，看到 333.34、333.33 和 333.33"則是檢查方式。它說明要執行什麼操作，以及預期觀察到什麼。

請代理在開始實作前，先把幾項這類檢查寫進檔案。預期數字由我們自行核對，否則很容易接受實際結果，還不知不覺地把預期調整成符合已完成的頁面。

10.05 這一列用來檢查計算順序：10% 是 1.005，四捨五入後為 1.01。如果在其他步驟才四捨五入，總額可能不同。要檢查輸入格式，可以再用逗號輸入 10,05，結果應該相同。另外也要測試負數金額、小數人數、負數或小數百分比，以及空白的小費欄位；這些情況都不應執行計算。

每項重要條件都應該有相應的觀察結果。"頁面已開啟"還不能證明金額正確，就像網址正確不代表載入了您要的頁面。要檢查的，是您當初發起這項任務真正想要的行為。

整理出完整的 TASK_SPEC

討論過程中，代理已經把各項決定逐一記進檔案。現在請重讀全文：回答是否都已納入？檢查項目是否符合要求？是否還留有舊條件？以下是這個範例最後整理出的文件。它分成六個部分：背景、預期行為、scope、non-goals、檢查計畫和安全起步。標題能幫您快速找到需要的內容，而具體內容則來自任務分析。

# TASK_SPEC.md

## 背景
一群人想分攤餐廳帳單。
目前還沒有新專案；工作資料夾裡只有 TASK_SPEC.md。

## 預期行為
工作成果：可用雙擊方式開啟的 index.html，
以及簡短的檢查說明。
頁面上有三個欄位和"計算"按鈕：
- 帳單金額大於 0，小數最多兩位；
  可用小數點或逗號，不使用千分位分隔符號；
- 人數必須是大於等於 1 的整數；
- 小費百分比必須是大於等於 0 的整數，初始值為 0。
依帳單金額計算小費，四捨五入到最近的一分；
剛好半分時進位。
將四捨五入後的小費加到帳單，再分攤總額。
顯示小費、總額，以及標示編號的各人分攤金額。
所有分攤金額加總等於總額，彼此差距不超過 0.01。
剩餘金額每次分一分給名單前面的參與者；
頁面上要說明這項規則。
欄位空白或數值不正確時，隱藏結果，
並在錯誤欄位旁顯示提示。

## SCOPE
一個頁面：三個欄位、計算、提示和金額顯示。
按照上述規則平均分攤總額及餘額。

## NON-GOALS
不做帳戶和帳單紀錄：不儲存資料。
不按餐點分帳：那是另一種計算器。
限制：樣式和 script 都放在 index.html，
不使用伺服器或外部函式庫，讓檔案能在本機開啟。

## 檢查計畫
雙擊開啟 index.html。按下"計算"測試：
- 1000 / 3 人 / 0% → 333.34；333.33；333.33；
- 1000.01 / 3 / 0% → 333.34；333.34；333.33；
- 1000 / 3 / 10% → 小費 100.00，總額 1100.00，
  分攤金額 366.67；366.67；366.66；
- 10.05 / 3 / 10% → 小費 1.01，總額 11.06，
  分攤金額 3.69；3.69；3.68；輸入 10,05 時結果相同；
- 1000 / 1 / 0% → 單人分攤 1000.00。
每次都加總各份金額，並和總額核對。
檢查人數為 0 或小數、金額為負數、
百分比為負數或小數、金額的小數位超過兩位，
並依序清空每個欄位：
欄位旁有提示，結果隱藏，即使先前已經計算過也一樣。
檢查分攤金額的編號，以及餘額分配規則的說明。

## 安全起步
先閱讀任務規格，並查看工作資料夾的內容。
如果裡面已有專案檔案，先停下來釐清任務；
不要覆寫或刪除既有檔案。
先提出問題和不含程式碼的計畫，再等待核准。
如果實作需要修改範圍以外的內容，
請先釐清任務規格，再進行修改。

這份文件隨著真正需要的決定逐漸增加內容。它沒有逐步教您怎麼寫 JavaScript，卻清楚說明小費如何處理，以及如何檢查每一分錢。您的任務可能不需要這麼多細節。

整理自己的任務規格時，可以參考這份簡短的檢查表：

條件變更時怎麼辦

現在換您做個小練習。使用者看過任務規格後說："百分比不方便，我想直接輸入小費金額，例如 100。"TASK_SPEC 的哪些部分需要更新？先試著說出來，再看下面的分析。

在預期行為中，百分比欄位要改成小費金額：不可為負數，可使用小數點或逗號，小數最多兩位。初始值仍為 0。刪除百分比公式和計算小費時的四捨五入規則，改為直接把輸入金額加到帳單上。scope 中的計算方式要修改，檢查計畫中的輸入資料和錯誤輸入情況也要調整。總額分攤方式和 non-goals 維持不變。

用"帳單 1000、小費 100、三位參與者"來檢查，結果會是熟悉的 366.67、366.67、366.66。但光看這些數字，無法分辨新版本和舊版的 10% 小費。再加入另一筆帳單：500 加上固定小費 100，由兩人分攤。每人應付 300；舊版 10% 的結果則是每人 275。這個檢查能分辨規則是否已更改。

請代理更新預期行為、scope 和檢查項目，再展示所有修改過的片段。開啟檔案，確認舊的百分比公式已刪除，新的檢查則符合直接輸入金額的方式。不要同時保留舊公式和"現在改為輸入金額"的附註：任務規格必須只給出一個明確答案。上面的主要範例保留原本的百分比做法，這裡討論的是另外一種修改方案。

和 Claude Code 搭配使用

個別修改都檢查過之後，開始實作前請重讀整份 TASK_SPEC。確認目標、範圍和檢查方式描述的是同一項任務。接著明確把檔案交給代理：

閱讀 @TASK_SPEC.md。先檢查是否有矛盾，
或仍需要釐清的條件。
展示簡短計畫，以及預計建立或修改的檔案清單。
計畫核准前不要修改程式碼。

現在，即使還沒開始實作，也有內容可以先檢查。如果計畫中出現用來儲存帳單的伺服器，請代理重新規劃：帳單紀錄已排除，而且頁面必須能在本機開啟。計畫沒問題，再允許開始實作。完成後開啟產出的檔案，逐一檢查記下的情境，包括成功計算後的錯誤輸入。

Non-goals 只是文字條件，技術上不會阻止修改。因此，審閱計畫和檢查結果都很重要。代理說"完成了"可以讓您了解它做了什麼，但不能取代您親自核對預期數字。

工作結束後，如果 TASK_SPEC 會繼續留在專案裡，請將任務標記為已關閉。工作進行中則要維持文件內容最新。措辭和記錄可以交給代理處理，決定是否符合原意則要對照文件檢查：每次討論後檢查修改片段，開始實作前重讀全文。