Spec Citation

註:本文中所有 §條號(§101、§205、§300-306 …)皆為示意編號,用來示範引用形式,非任何真實文件的實際條號。

規格引用紀律(Spec Citation Discipline)

什麼時候用

任何「一份規格/設計文件被別的東西引用」的專案——測試斷言註「依 §101」、程式碼註解寫「見 §205」、 計畫文件寫「主規格 §300-306」、記憶檔用「§410-415」當座標。這些引用是活的:規格一改,引用可能 指錯地方而無聲失效。此技能講怎麼改規格而不弄斷引用。

通用法則

法則 1:§條號 = 活引用,不是裝飾

章節/條號一旦被別處引用,它就是一個穩定的公開介面(像函式簽章)。引用者靠它定位「規格的哪一段」。 改規格時把條號當 API 對待:別隨意重編號、別讓既有條號指向不同內容。

法則 2:語意錨點優先於行號

行號會漂移(上面插一行,下面全錯位);語意錨點(章節標題、§條號、獨特短語)穩定。

• 引用時:優先寫「§101 達成率家族」而非「第 101 行」。
• 定位時:用 grep 找 §101 或標題文字,別靠記憶的行號。
• 這也是為什麼編輯工具要用「唯一文字錨點」而非行號來定位。

法則 3:改規格前,先查有沒有現役批次引用該區段

「現役批次」= 正在進行、或近期會 resume 的工作(有分支、有計畫、有記憶座標指向它)。 編輯規格某段前,先搜全 repo 有沒有測試/碼/計畫/記憶引用它:

grep -rn "§101\|達成率家族" .        # 條號 + 語意錨點都搜

有引用 → 那段是「被佔用的介面」,改它要同步改所有引用方(像改函式簽章要改所有 caller)。

法則 4:現役引用區段「之前」不准插行(保編號穩定)

要新增規格內容時,插入點的選擇會影響既有條號:

• 在被引用區段之後 / 檔尾追加 → 既有條號不動,引用不斷。安全,預設這樣做。
• 在被引用區段之前插入(尤其會推移後面編號的)→ 後面所有條號位移,引用集體指錯。禁止,除非 同步更新所有引用方。
• 新段落給新條號(接續最大號),別插進舊號中間。
• 不重編號(硬線):錨點的價值就是「永遠不變」,重編號等於毀掉這個價值。若你認為非重編不可, 停下來,把它當成一個獨立的工程提案交給擁有者決定,不要自行遷移——一個人默默重編號、順手改幾個 引用,幾乎必然漏掉某個引用方而無聲失效。

法則 5:非本人管理的規格,只讀不改

規格常由「擁有者」(人)管理(工作樹編輯、手動維護)。若規格檔標明由某人管理 → 只引用、不代改; 要補內容用獨立的設計/計畫文件引用它,不動主檔。改主檔前先確認授權。

本專案案發現場(佐證,非通用必需)

• 座標系統:某財務報表自動化專案的主規格檔用 §<行號附近> 當座標(§101/§205/ §300-306…),被測試 ground-truth 註解(規格條號欄位="§101")、程式碼註解、計畫/spec 文件、 記憶檔四處引用。衝突樣本集 的每筆 ground-truth 都註規格條號「可追溯、非標註者主觀」——這正是 法則 1「條號=公開介面」的實例。
• 主檔由擁有者管理(法則 5):主規格由擁有者於工作樹手動維護。第三批動工時 發現 主規格檔 在工作樹被擁有者改動 → 不碰、不 commit,只在獨立的 spec/plan 文件 引用它的 §300-306 等。這是「非本人管理只讀不改」的實例。
• 語意錨點救場(法則 2):條號名義上是「行號附近」,但實際定位一律 grep §條號 或章節標題文字, 從不靠行號記憶——因為擁有者隨時在插補內容,行號早就漂了,條號當語意標籤才穩。