# Spec Citation

> 規格引用紀律——當規格文件的「章節/條號」被測試、程式碼、其他文件、或多階段計畫引用時,如何安全地編輯規格而不破壞這些引用。用於任何「規格被引用」的專案:改規格前先查現役引用、保護被引用區段、語意錨點優先於行號。

- Skill: `poloplay0114/spec-citation-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add poloplay0114/spec-citation-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poloplay0114/spec-citation-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: poloplay0114 (https://skillmd.com/u/poloplay0114)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/poloplay0114/spec-citation-2

---


> 註:本文中所有 §條號(§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 `§條號` 或章節標題文字,
  從不靠行號記憶——因為擁有者隨時在插補內容,行號早就漂了,條號當語意標籤才穩。