2.6 Spec-Driven Development:商管人的可執行規格
學完本節,你能夠:
- 說明「文字規格書」與「可執行規格」的差別,以及為什麼後者在 AI 時代更重要。
- 把一條商業規則寫成 Given-When-Then 場景表,包含門檻上、門檻外與錯誤輸入。
- 讓 AI 依場景表產生程式與自動測試,並用測試抓出程式中的錯誤。
壹、開場情境:規格書寫了,程式也做了,但沒人知道對不對
📌 以下為教學情境(依跨境電商實務改編)。
一家跨境賣家想提供 DDP(賣方負擔進口稅費)報價,需要一個「進口稅額試算」功能。財務主管在 Word 規格書裡寫:
「商品價值超過免稅額,就要計算關稅與營業稅,金額四捨五入到元。」
外包工程師一週後交件,業務用了一個月,直到買家投訴才發現兩個問題:
| 情況 | 正確結果 | 系統結果 | 原因 |
|---|---|---|---|
| 商品價值剛好 NT$ 2,000 | 免稅 | 課稅 | 工程師把「超過」寫成「大於或等於」 |
| 商品價值 NT$ 3,500,營業稅 192.5 元 | 193 元 | 192 元 | 程式語言內建的「四捨五入」其實不是四捨五入(第伍段說明) |
規格書沒有寫錯,程式也「看起來」沒錯。問題是:規格書沒辦法自己去檢查程式。 業務、財務和工程師之間只隔著一份文字,每個人讀到的意思不一樣,也沒有人能在交件時一鍵確認「程式有沒有照規格做」。
本節要解決的問題: 能不能把規格寫成「可以拿去自動檢查程式」的形式,讓錯誤在交件當天就被抓到?
貳、為什麼會這樣:文字規格與可執行規格
自然語言有歧義:「超過 2,000」包不包含 2,000?「四捨五入」是哪一種?寫的人覺得理所當然,讀的人各自解讀。
可執行規格(Executable Specification) 是指:寫法有固定結構、每一條都附具體數字,可以直接轉成自動測試的規格。以規格為中心、讓 AI 依規格產生程式與測試的開發方式,近年被稱為規格驅動開發(Spec-Driven Development, SDD)。
| 傳統文字規格書 | 可執行規格 | |
|---|---|---|
| 長相 | 數十頁敘述、截圖、流程圖 | 場景表:給定什麼、做什麼、應該得到什麼數字 |
| 誰看得懂 | 寫的人 | 業務、財務、工程師、AI 都看得懂 |
| 怎麼驗收 | 人工逐條比對,常被省略 | 每個場景都是一個自動測試,一鍵執行 |
| 規則改了 | 文件與程式各改各的,慢慢不一致 | 先改場景,測試失敗就知道程式還沒跟上 |
一份完整的可執行規格通常包含四種內容,本節只練第一種,其他三種先認識名稱即可:
| 內容 | 常見格式 | 回答什麼問題 | 本書何處深入 |
|---|---|---|---|
| ① 行為場景 | Given-When-Then(Gherkin 語法) | 在什麼情況下,系統應該產生什麼結果? | 本節;第 5.2 節 |
| ② 介面契約 | OpenAPI | 其他系統要怎麼呼叫這個功能?傳入與回傳哪些欄位? | 第 3.3 節 |
| ③ 資料規格 | JSON Schema | 每個欄位的型態與限制(例如金額必須大於 0) | 第 3.3 節 |
| ④ AI 工作規則 | AGENTS.md 等規則檔 |
AI 寫程式時要遵守哪些原則與禁止事項? | 第 7.2 節 |
參、把規則寫下來:從一句話到場景表
| 財務主管的說法 | 需要追問的問題 | 寫成規格 |
|---|---|---|
| 「超過免稅額要課稅」 | 免稅額多少?剛好等於算不算超過? | 完稅價格 ≤ NT$ 2,000 免稅;> 2,000 全額課稅 |
| 「算關稅」 | 稅率從哪裡來? | 依 HS Code 查稅率表;查不到就停止,不可自行假設稅率 |
| 「算營業稅」 | 稅基是什麼? | 營業稅 =(完稅價格 + 關稅)× 5% |
| 「四捨五入到元」 | 哪一步四捨五入? | 關稅、營業稅各自四捨五入到整數元(0.5 進位) |
| (沒說) | 金額填 0 或負數? | 視為輸入錯誤,停止並提示 |
⚠️ 稅率說明:本節以棉製 T 恤(HS Code 6109.10)稅率 10% 作為教學假設。實際稅率、免稅門檻與次數限制以財政部關務署公告為準,且台灣實際使用的稅則號別比國際通用的 6 碼更長。
把規格表改寫成 Gherkin 場景。Gherkin 支援中文關鍵字,下面用「場景大綱 + 例子表」一次列出多組數字:
功能: 進口稅額試算
作為跨境賣家
我希望依完稅價格與 HS Code 試算進口稅額
以便向買家提供正確的 DDP 報價
場景大綱: 依完稅價格計算稅額
假設 HS Code 為 "6109.10",關稅稅率 10%
當 完稅價格為 <完稅價格> 元
那麼 關稅應為 <關稅> 元
並且 營業稅應為 <營業稅> 元
並且 稅額合計應為 <合計> 元
例子:
| 完稅價格 | 關稅 | 營業稅 | 合計 |
| 3500 | 350 | 193 | 543 |
| 2000 | 0 | 0 | 0 |
| 2001 | 200 | 110 | 310 |
場景: 輸入不合理的金額
當 完稅價格為 0 元或負數
那麼 系統應停止計算並提示「CIF 金額必須是大於 0 的數字」
場景: 稅率表查不到 HS Code
當 HS Code 為 "9999.99"
那麼 系統應停止計算並提示人工確認稅率
驗算第一列:關稅 3,500 × 10% = 350;營業稅(3,500 + 350)× 5% = 192.5,四捨五入為 193;合計 543。第三列:關稅 2,001 × 10% = 200.1 → 200;營業稅 2,201 × 5% = 110.05 → 110;合計 310。
注意第二、三列:剛好在門檻上、門檻外 1 元,這兩列就是第 2.4 節說的邊界條件,也正是開場情境出錯的地方。
肆、讓 AI 做出來
1. 給 AI 的 Prompt
重點是把場景表整份交給 AI,並要求每個場景對應一個測試。這樣 AI 交出的不只是程式,還有一份證明程式符合規格的檢查表。
你是熟悉稅務計算的 Python 工程師。請依照下面的 Gherkin 規格實作。
【規格】
(貼上第參段的完整 Gherkin 內容)
【實作要求】
1. 函式名稱 calculate_import_tax(cif_twd, hs_code),回傳 {"tariff", "vat", "total"}。
2. 免稅門檻、營業稅率、稅率表請宣告為程式最上方的常數。
3. 金額計算請使用 Decimal,四捨五入採 0.5 進位,不要使用 Python 內建的 round()。
4. 查不到 HS Code 或金額不合理時拋出錯誤,不要使用預設稅率繼續計算。
【測試要求】
寫一個 test_all() 函式,規格中的每個場景(例子表的每一列也算)都要有對應的檢查,全部通過時印出訊息。
2. AI 產出的程式碼(已人工驗收)
from decimal import Decimal, ROUND_HALF_UP
# ===== 商業規則(稅率為教學假設,實際以關務署公告為準)=====
DUTY_FREE_LIMIT = 2000 # 完稅價格 NT$ 2,000 以下免稅(含 2,000)
VAT_RATE = Decimal("0.05") # 營業稅 5%
TARIFF_RATES = { # HS Code → 關稅稅率(教學假設)
"6109.10": Decimal("0.10"), # 棉製 T 恤
}
def round_ntd(amount):
"""四捨五入到整數元(0.5 一律進位)"""
return int(Decimal(amount).quantize(Decimal("1"), rounding=ROUND_HALF_UP))
def calculate_import_tax(cif_twd, hs_code):
"""依完稅價格(CIF)與 HS Code 試算進口稅額"""
# 例外:輸入不合理或稅率表查不到 → 停止,不要猜稅率
if not isinstance(cif_twd, (int, float)) or cif_twd <= 0:
raise ValueError("CIF 金額必須是大於 0 的數字")
if hs_code not in TARIFF_RATES:
raise ValueError(f"HS Code {hs_code} 不在稅率表中,請人工確認")
# 門檻:2,000 以下(含)免稅
if cif_twd <= DUTY_FREE_LIMIT:
return {"tariff": 0, "vat": 0, "total": 0}
cif = Decimal(str(cif_twd))
tariff = round_ntd(cif * TARIFF_RATES[hs_code])
vat = round_ntd((cif + tariff) * VAT_RATE)
return {"tariff": tariff, "vat": vat, "total": tariff + vat}
# ===== 驗收測試:每個 Gherkin 場景對應一行 =====
def test_all():
assert calculate_import_tax(3500, "6109.10") == {"tariff": 350, "vat": 193, "total": 543}
assert calculate_import_tax(2000, "6109.10") == {"tariff": 0, "vat": 0, "total": 0}
assert calculate_import_tax(2001, "6109.10") == {"tariff": 200, "vat": 110, "total": 310}
for bad in [(0, "6109.10"), (-100, "6109.10"), (3500, "9999.99")]:
try:
calculate_import_tax(*bad)
assert False, f"{bad} 應該要報錯"
except ValueError:
pass
print("✅ 全部 5 個場景通過")
test_all()
🔍 驗收重點(不懂語法也能檢查) -
test_all()裡的數字,是否和 Gherkin 例子表一字不差?(測試數字必須來自規格,不能來自程式算出來的結果。) - 門檻判斷是<=(含 2,000 免稅),和規格表一致嗎? - 查不到 HS Code 時是「拋出錯誤」,而不是用一個預設稅率繼續算?
3. 執行步驟
- 開啟 Google Colab,新增筆記本,貼上程式碼並執行。
- 看到「✅ 全部 5 個場景通過」即代表程式符合規格。
- 若出現
AssertionError,錯誤訊息會指出是哪一行(哪一個場景)沒通過。
4. 規格變大時:給 AI 代理的五段式規格
場景表適合「一條規則」。當工作牽涉三個以上的檔案或步驟、步驟之間互相依賴,或你希望之後能重做一次時,就需要一份完整的規格交給 AI 代理(第 4.4 節)。判斷標準可以借用採購的經驗:金額大到需要簽合約、附工作說明書的案子,交給 AI 時也值得寫規格。
和真人合作最大的不同是:真人遇到模糊處會打電話來確認,AI 通常不會停下來問,而是挑一個「看起來合理」的解讀繼續做。所以把規格寫精確,本身就是在做事,不是額外的行政負擔。
| 段落 | 寫什麼 | 本節範例 |
|---|---|---|
| ① 總目標 | 一句話:做什麼、為什麼 | 為 DDP 報價新增進口稅額試算 |
| ② 可檢查的成果 | 3–5 項,每一項都能單獨驗收 | 第參段的 5 個場景全部通過 |
| ③ 實作注意事項 | AI 不能自己猜的事:限制、標準、禁止事項 | 用 Decimal、不用內建 round();查不到稅率就停止;不得新增其他套件 |
| ④ 範圍 | 哪些檔案要新增、要修改,哪些只能讀不能改 | 新增 import_tax.py;tariff_rates.csv 只讀 |
| ⑤ 依序的工作步驟 | 照相依順序排列,後面的步驟可以使用前面的成果 | 1. 建立常數 → 2. 寫四捨五入函式 → 3. 寫試算函式 → 4. 寫測試 |
第 ③ 段有一個實用原則:任何你會在審查時糾正的事,都事先寫進去,就能省下一輪退件。第 ④ 段最常被省略,卻最重要:沒寫範圍,AI 就可能順手改了不該改的檔案。
5. 用精準的動詞下指令
寫第 ⑤ 段時,動詞的選擇會大幅影響結果。下面這組成對的動詞,意思很接近,但對 AI 來說是完全不同的指令:
| 動詞 | 意思 | 對照 | 意思 |
|---|---|---|---|
| 新增(CREATE) | 建立一個原本不存在的東西 | 加入(ADD) | 在已存在的東西裡追加 |
| 修改(UPDATE) | 在原處調整 | 取代(REPLACE) | 整個換掉原本的做法 |
| 刪除(DELETE) | 整個移除 | 移除(REMOVE) | 只拿掉其中一行或一個參數 |
搭配「動詞 + 位置:細節」的句型,例如:
修改 import_tax.py:在 calculate_import_tax() 中加入「HS Code 查無資料就停止」的檢查
比一大段「請幫我讓稅額計算更完整一點」更短,也更常一次就做對。
💡 審計畫,是全流程中最便宜的檢查點。 請 AI 先依規格產出計畫、還沒動任何檔案時就檢查:這時發現誤解,改一句話就好;等它做完再發現,就要退回、重做、重新驗收。第 4.4 節的「審查計畫」與附錄 B.3 的規劃模式,都是這個道理。
伍、跑跑看、壞給你看
每個實驗做完,都把程式改回原樣再做下一個。
| 實驗 | 操作 | 預期結果 | 想想看 |
|---|---|---|---|
| ① 重現開場的錯誤一 | 把 if cif_twd <= DUTY_FREE_LIMIT 改成 < |
第 2 個檢查(2,000 元)失敗 | 文字規格書寫「超過」時,你能一眼看出這個錯嗎? |
| ② 重現開場的錯誤二 | 把 round_ntd(...) 都換成 Python 內建的 round(...) |
第 1 個檢查失敗:營業稅算出 192 | Python 的 round(192.5) 是 192,因為它採「銀行家捨入」(0.5 時捨入到偶數)。AI 和工程師都很常踩這個坑 |
| ③ 新增商品 | 呼叫 calculate_import_tax(3500, "6110.20") |
出現錯誤「HS Code 6110.20 不在稅率表中,請人工確認」 | 如果系統自動套用 0% 稅率,DDP 報價會少收多少?誰來負擔? |
| ④ 稅率調整 | 把 VAT_RATE 改成 Decimal("0.06"),不改測試 |
第 1 個檢查就失敗(第 3 個也會失敗) | 規則改了,先改程式還是先改規格?測試失敗代表什麼? |
實驗 ② 是本節最重要的一課:只要規格裡寫了 193,就能抓到一個連工程師都不一定知道的錯誤。 寫出具體數字,本身就是一種品質控管。
陸、回到情境
如果財務主管當初交出去的是第參段的場景表,外包工程師交件當天執行 test_all(),就會看到 2 個場景失敗,兩個錯誤在上線前就被修正。財務主管不需要看懂程式,只需要確認「例子表的數字是對的」。這就是 SDD 對商管人的意義:你負責寫對的例子,AI 負責寫通過例子的程式。
這個做法還做不到的事:
| 限制 | 後果 | 在哪一節解決 |
|---|---|---|
| 測試只檢查你想到的例子 | 沒寫進例子表的情況仍可能出錯 | 2.5 用紅隊找漏洞;5.4 讓 AI 補充極端測試 |
| 稅率表是手動維護 | 法規改了沒人更新,系統照舊計算 | 指定負責人定期核對官方公告;第 9 章權限與控管 |
| 例子表的數字如果本身就錯 | 程式會「正確地」照錯的規格做 | 例子表要由財務、稅務人員覆核 |
本節小結
- 文字規格無法自己檢查程式;可執行規格的每個場景都能變成自動測試。
- 好的場景表一定包含門檻上、門檻外、錯誤輸入三類例子。
- 把整份場景表交給 AI,要求「每個場景對應一個測試」,AI 交出的就是程式加上驗收證明。
- 寫出具體數字本身就是品質控管,能抓到連工程師都不知道的錯誤(例如銀行家捨入)。
柒、練習
- 改數字(5 分鐘):假設免稅門檻調降為 NT$ 1,000。你要改哪一行?例子表哪幾列要改?請新增「1,000 元」與「1,001 元」兩列並寫出正確的預期結果,再執行測試確認。
- 加功能(20 分鐘):公司新增第二種商品:羊毛毛衣(HS Code 6110.11,教學假設稅率 12%)。請先在 Gherkin 例子表新增至少 2 列(含一列會產生 0.5 元的情況),再讓 AI 修改程式與測試,確認全部通過。
- 管理反思(討論):信用狀(L/C)審單有一條規則:「提單簽發日期不得晚於信用狀規定的最遲裝運日」。(a) 請寫出這條規則的 Given-When-Then 場景,至少包含「早一天、同一天、晚一天」三個例子。(b) 為什麼說在 AI 時代,「寫出精確例子的能力」比「會寫程式」更稀缺?
📚 本節補充內容出處:五段式規格與成對動詞的寫法參考美國密西根大學 EECS 498「Applied Agentic Software Engineering」課程(2026 秋季),內容依商學院情境重新撰寫。