2.6 Spec-Driven Development:商管人的可執行規格

學完本節,你能夠:

  1. 說明「文字規格書」與「可執行規格」的差別,以及為什麼後者在 AI 時代更重要。
  2. 把一條商業規則寫成 Given-When-Then 場景表,包含門檻上、門檻外與錯誤輸入。
  3. 讓 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. 執行步驟

  1. 開啟 Google Colab,新增筆記本,貼上程式碼並執行。
  2. 看到「✅ 全部 5 個場景通過」即代表程式符合規格。
  3. 若出現 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 章權限與控管
例子表的數字如果本身就錯 程式會「正確地」照錯的規格做 例子表要由財務、稅務人員覆核

本節小結

  1. 文字規格無法自己檢查程式;可執行規格的每個場景都能變成自動測試。
  2. 好的場景表一定包含門檻上、門檻外、錯誤輸入三類例子。
  3. 把整份場景表交給 AI,要求「每個場景對應一個測試」,AI 交出的就是程式加上驗收證明。
  4. 寫出具體數字本身就是品質控管,能抓到連工程師都不知道的錯誤(例如銀行家捨入)。

柒、練習

  1. 改數字(5 分鐘):假設免稅門檻調降為 NT$ 1,000。你要改哪一行?例子表哪幾列要改?請新增「1,000 元」與「1,001 元」兩列並寫出正確的預期結果,再執行測試確認。
  2. 加功能(20 分鐘):公司新增第二種商品:羊毛毛衣(HS Code 6110.11,教學假設稅率 12%)。請先在 Gherkin 例子表新增至少 2 列(含一列會產生 0.5 元的情況),再讓 AI 修改程式與測試,確認全部通過。
  3. 管理反思(討論):信用狀(L/C)審單有一條規則:「提單簽發日期不得晚於信用狀規定的最遲裝運日」。(a) 請寫出這條規則的 Given-When-Then 場景,至少包含「早一天、同一天、晚一天」三個例子。(b) 為什麼說在 AI 時代,「寫出精確例子的能力」比「會寫程式」更稀缺?

📚 本節補充內容出處:五段式規格與成對動詞的寫法參考美國密西根大學 EECS 498「Applied Agentic Software Engineering」課程(2026 秋季),內容依商學院情境重新撰寫。

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。