一、測試內容由斷言自述，不寫敘述性註解

測試名稱就是主張、斷言就是內容——讀了名稱和斷言還無法判斷測試驗證什麼，該修的是名稱和斷言，不是加「本測試對應／驗證什麼」的說明註解。

名稱還承擔一個失敗訊息給不了的東西：失敗輸出只有症狀（Expected X、Actual Y），拿到紅燈的人要逆推「為什麼這個行為是刻意的」，而回答它的位置就是名稱。「直接進入下一階段：不做編輯流程的收尾」讓紅燈的人知道自己撞到的是一條刻意的規則、不是漏網的 bug；名稱說不出這件事為什麼成立，先改名稱，改完仍說不出來才考慮註解。

允許留下的註解只有兩種：

二、reason 寫失敗的後果與處置，不寫感想

斷言的失敗訊息是「未來某個紅燈時刻」的第一線資訊，它的讀者正急著知道兩件事：這代表什麼、接下來做什麼。

• 改寫前：reason: '狀態應該是 1'
• 改寫後：reason: '後端未釋放資源（即刻=X、延遲=Y）——前端刪除編排與假後端都依「同步釋放」設計，需與後端確認並同步修正兩處。'

把變數值內插進訊息（實際讀到的狀態、id），紅燈時不用重跑加 log。

三、檔頭陳述目的，不論證需求

檔頭回答三件事就夠：這是什麼、怎麼用、維護時要做什麼。存在理由的論證（「因為 stub 只會回放假設，所以需要這個假後端，否則⋯⋯」）屬於教材或 PR 說明，不屬於程式碼——讀程式的人需要的是操作資訊，不是被說服。

同理，彙整清單不放檔頭。「本假後端已模擬的行為：合併＝⋯、更新＝⋯、刪除＝⋯」這種清單，每一條在對應的 handler 方法上都有自己的說明——檔頭清單是重複，而且沒有任何機制守著它與 handler 同步，終將過期。

四、取證出處、日期、開發過程不入程式碼

取證出處、日期與開發過程回答的是「怎麼知道的」；測試文字只需要回答「行為是什麼」。

• 改寫前：「合併後保留記錄 id（某年某月實測證實）」「本測試曾以相反順序抓到此問題」
• 改寫後：「合併後記錄 id 不變（後端只改外鍵）」／刪除

取證紀錄和開發史寫進版本控制的 commit 訊息、團隊的知識庫即可。程式碼裡的註解只陳述當前為真的行為——帶日期的註解從寫下那刻就開始腐化，「曾經抓到」的敘述在下一個讀者眼中只是噪音。

五、分析詞彙不入測試內容

團隊在討論問題時會發展出後設詞彙——「語意」「契約」「漂移」這類幫助人類對齊理解的抽象詞。它們屬於對話，不屬於測試：

• 改寫前：測試名「後端語意：刪除單據釋放資源」、reason「語意漂移：⋯」
• 改寫後：測試名「刪除單據一併釋放關聯資源」、reason「後端未釋放資源——與前端編排依據的行為不符⋯」

判斷法：這個詞刪掉之後句子有沒有變得更直接？「刪除單據一併釋放關聯資源」是可以直接對後端行為驗證的陳述句；「後端語意：⋯」是套在陳述句外面的分類標籤，資訊量為零。

六、用動作＋結果的白話取代自創行話

白話的標準是「動作＋結果」：句子直接說出做了什麼、預期看到什麼，讀者不需要先學會團隊內部的簡稱。

• 改寫前：「驗證早退情境不打後端」
• 改寫後：「讓測試能斷言『提前結束的路徑（狀態未推進、空清單）沒有發出請求』」

判斷法：這個詞在程式碼或團隊詞彙表裡存在嗎？讀者第一次看到需要停下來猜嗎？「早退」「打後端」「塞 mock」這類壓縮語，寫的人省了五個字，每個讀者各付一次理解成本。

七、跳過訊息要可行動

測試被跳過時，輸出裡那行 skip 訊息是讀者唯一的線索。

• 改寫前：skip: '未提供憑證'
• 改寫後：skip: '未提供憑證，跳過真實後端驗證——帶 <具體參數> 執行（見檔頭）'

原則與 reason 相同：告訴讀者這代表什麼、怎麼讓它跑起來。

彙總判斷表

最後一列跟其他列的性質不同。前面幾列都在分配「這段文字該放哪個 surface」，而它是在說這段內容根本不是文字問題——寫下它的動機是防護，而註解不參與執行、改壞的當下不會發聲。本篇第一節允許留在檔頭的那類註解（「本檔不可初始化 UI 測試綁定」）就是這個形態的邊界案例：它守的是環境約束，而環境約束沒有任何測試接得住，所以留在檔頭是對的。判定方式與當場可執行的驗證見 #253 寫註解的動機是怕被改壞時要處理的是那個約束。

下一步路由

• 斷言本身的品質 → 斷言品質三問
• 那條會紅的測試該測什麼、與註解分工的全景 → 測試的價值發生在它變紅的那一刻
• 想寫的其實是防護註解、該不該改成一條測試 → #253 寫註解的動機是怕被改壞時要處理的是那個約束
• 這套紀律誕生的測試形態 → 語意級假後端與流程測試
• 「沒有機制守著就終將過期」推廣到整條文件鏈（spec / 設計文件 / 追溯表）→ #256 多份文件必然漂移

建立測試時：價值在未來的紅燈，不在當下的綠燈

寫測試的當下，程式是對的——不對的話會先修程式再讓測試過；寫的過程若抓到現有 bug，那份價值發生在先出現的那顆紅燈。所以測試寫完的那顆綠燈，確認的是「此刻的行為與此刻的預期一致」，而這件事作者當場已經驗證過。這條測試之後的防護價值全部發生在未來：某一次變更讓行為偏離預期、測試變紅、變更的人在合併之前就知道。

本篇談的是測試作為長存產物的防護價值。寫測試這個動作在當下逼出的介面設計回饋（測試先行時，介面由使用端先定義）、以及被當成規格文件閱讀的價值，是另外兩條軸、不在本篇的時間軸上——而 TDD 的紅綠循環，正是把「先出現的紅燈」制度化提前。綠燈給的部署信心也來自同一處：信心的大小等於它會紅的能力，一條恆真的斷言給不出任何信心。

這個時間差改變了建立測試時該問的問題：不是「現在的行為對不對」，是「未來哪一種改壞，要被這條測試擋下」。

兩個問題會選出不同的測試。一個批次操作有兩個入口按鈕，差別在合併完成後的收尾——一種回到編輯流程、一種直接進入下一階段；選了哪一種，程式記在一個用途值裡，而執行順序是先重設選取狀態、之後才讀取用途值來決定收尾。問「現在對不對」，寫出來的是主流程斷言：合併後清單變成一筆。問「哪種改壞要被擋」，看到的是另一件事：任何人把用途值加進重設的清除清單，讀取時拿到的就是預設值——第一種用途，於是第二種用途靜默走成第一種：不報錯、不彈窗，使用者按第二種入口、得到第一種收尾。這個問題指向的是這樣一條測試：「直接進入下一階段：不做編輯流程的收尾」。兩條測試在今天都綠，防護範圍完全不同（案例完整推導見註解防不了改壞）。

防護存不存在可以當場觀察、不必推測：在違反約束的位置故意加一行改動，跑測試，看 runner 印出的失敗輸出（+2 -1 是通過 / 失敗計數、[E] 標記錯誤）——

1+2 -1: 直接進入下一階段：不做編輯流程的收尾 [E]
2  Expected: Step:<Step.finished>
3    Actual: Step:<Step.editing>

紅了，防護存在；還原改動。建立一條防護型測試之後做一次這個動作，比讀十遍測試碼可靠——「有測試」與「那條測試會對這個違反發聲」是兩件事。

接手零測試的專案時，「未來哪種改壞要被擋」的第一批答案在風險集中處，起步順序見無測試 legacy 專案的起步順序；變更前先把現狀鎖住的測試形態是 characterization test——它的斷言對象是「現在的行為」而不是「正確的行為」，是防護視角的退位形式：依賴纏結或規格失傳、無法先寫正確性測試時，用它先把現狀鎖住。

變更時：型別裝不下的約束，測試是唯一在改壞當下發聲的機制

改功能、加功能、重構，三種變更都會經過別人寫下的程式。變更的人手上有哪些防護，差別在訊號出現的時機、以及能不能被忽略：

型別的訊號最早，但裝得下的約束窄——「不該是負數」交給非負型別，違反它的程式碼根本寫不出來；「必須活過某次重設」這種跨函式的讀寫順序，違反的程式碼寫得出來、而且編譯得過。跨時間必須恆真的條件（不變式）落在型別外面時，測試是唯一以行為為斷言對象、在改壞當下發聲的位置。前提是它會自動跑——掛在 pre-commit（commit 前自動執行的 git hook）或 CI 上，沒有人手動觸發它也發得了聲。

命名把約束帶到每個呼叫點——第一節的用途值取 purposeSurvivingReset 這種名字，動手的人在改之前會多看一眼。但 IDE 的批次 rename 與自動重構不讀語意，名字擋不下工具驅動的變更；它是有價值的輔助，不是防護的終點。

重構時測試有雙重角色，分界在斷言的對象。斷言行為的測試是重構的安全網——行為不變就綠，結構怎麼改都放心；斷言實作的測試是重構的阻力——內部調整就紅，而那顆紅燈不代表壞掉。

阻力長這樣（機制推導）：當初寫測試的人 mock 了內部協作者、斷言呼叫次數，那樣最容易讓覆蓋率達標——這正是機械約束被最便宜的路徑滿足的形態。沒人動結構的期間，這批測試跟斷行為的測試一樣綠；第一次重構，它們整批變紅，而行為一項也沒壞。紅燈是不是真的壞掉只能逐條打開人工判定，而那時最省事的動作是改測試遷就新結構、或放棄重構。邊界在斷言的對象：呼叫本身是對外契約時（如 outbox 的 publish 保證），次數與順序就是行為，斷它是安全網、不是阻力。

這條分界就是斷言品質三問的第一問（斷言的是行為嗎），防護視角補上它的理由：重構需要的是「行為被改壞才發聲」的訊號，對實作發聲的測試把訊號稀釋成噪音。

加功能時，既有測試定義舊行為的邊界。新功能動到共享可變狀態、舊測試紅，代表新功能改壞了舊契約——這顆紅燈正是建立時那個「未來哪種改壞」的兌現，它在合併之前就浮現，不必等使用者回報。

review 爭論時：測試與註解的分工

review 裡「這個約束該寫註解還是測試」的爭論，判準是這段資訊有沒有對應的斷言——存不存在一條會紅的斷言，不是造不造得出句子：

• 寫得出會紅的斷言（讀寫順序、時序耦合、狀態必須活過某次操作）→ 資訊的家是測試名稱。
• 斷言守不住的那一半——來源在 repo 之外的出處與當初的取捨（法規條號、稽核要求、後端契約為什麼長這樣）→ 家是 doc comment。
• 兩者可以同時成立：test('留存不得少於七年') 既有斷言、來源又在 repo 外——測試守行為、註解留出處，各寫各的那一半。
• 還有一類斷言寫得出來、但不穩定或成本過高：並行安全、性能量級這種依賴非確定因素的約束，硬掛上 pre-commit 就違反本模組自己的 flaky 紀律（見Flaky test 根因分類）。這類資訊的家仍是 doc comment，語意是使用契約而非防護；要升級成防護，走專用的 benchmark 或 stress pipeline、不進提交閘門。

防護意圖寫成註解，改壞的當下不產生任何訊號——註解不參與執行，作用只發生在有人剛好讀到的時候；當那條會紅的斷言已經存在時，那行註解更是一份沒有保護力的副本。更糟的是宣稱約束的註解會讓 reviewer 以為有人在守——半年後有人在重設函式補上一行清除，那次 diff 不包含註解所在的行，reviewer 讀到的是一段合理的清理程式碼。合併之後沒有任何報錯——使用者按第二種入口得到第一種收尾，要等有人回報才會被發現。

分工有邊界：測試涵蓋不到的 surface（設定檔、build script、schema 定義）註解是唯一載體；給下游用的公開 API，下游 clone 不到專案內部的測試檔，doc 在那裡是契約介面。完整的動機辨識、「先問約束能不能被消除」的判斷閘、與失效邊界見 #253 寫註解的動機是怕被改壞時，要處理的是那個約束。

拿到紅燈時：名稱承載意圖，reason 承載處置

失敗輸出回答「壞在哪」，測試名稱回答「為什麼這是刻意的」。第一節那條失敗輸出只給了症狀：預期進入下一階段、實際停在編輯階段。拿到紅燈的人下一個問題是「為什麼這個行為是刻意的」——承擔這個「為什麼」的是測試名稱。「直接進入下一階段：不做編輯流程的收尾」把意圖寫在名稱裡，紅燈的人讀名稱就知道自己撞到的是一條刻意的規則、不是漏網的 bug。

名稱說不出理由時走的是另一條路（機制推導）：紅燈的人查不出這條規則為誰存在，deadline 前最合理的動作是把斷言改成新行為、讓測試回綠——防護在它發聲的那一刻被解除，而那次 diff 在 review 裡讀起來只是一次正常的測試更新。所以名稱說不出這件事為什麼成立，先改名稱；改完仍說不出來，才考慮在測試旁留註解。

名稱、reason、skip 訊息、檔頭與 setup 註解的逐項紀律——包含 reason 寫失敗的後果與處置、分析詞彙不入程式碼——見測試註解與命名紀律，該篇文末的彙總判斷表把每類文字的落點列齊了。

下一步路由

• 測試文字的逐項紀律（名稱 / reason / skip / 檔頭）→ 測試註解與命名紀律
• 斷言該斷行為還是實作、能不能區分對錯 → 斷言品質三問
• 零測試專案的第一批防護從哪建 → 無測試 legacy 專案的起步順序
• 防護判準的原則層（動機辨識、消除判斷閘、破壞實測）→ #253 寫註解的動機是怕被改壞時，要處理的是那個約束
• 本篇批次操作案例的完整推導 → 註解防不了改壞
• 「測試是行為的權威載體」推到整條文件鏈的分級 → #256 多份文件必然漂移