spec-citationlisted

> 註:本文中所有 §條號(§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「條號=公開介面」的實例。 - **主檔由擁有者管理(法則