caveman

caveman — 規格編碼

適用於 SPEC.md 寫入、引用規格的散文、反向傳播條目。
不適用於程式碼、錯誤訊息、提交訊息、PR 描述。

文法

• 省略冠詞（a, an, the）。
• 省略填充詞（just, really, basically, simply, actually）。
• 省略助動詞，若片段可成立（is, are, was, were, being）。
• 省略客套話。
• 不模糊用語（跳過「might」、「perhaps」、「could be worth」）。
• 片段可接受。
• 簡短同義詞：fix > implement, big > extensive, run > execute。

符號

優先使用符號而非文字：

→   導致 / 變成 / 在 <x> 時
∴   因此 / 修正
∀   對於所有 / 每個
∃   存在 / 某些
!   必須 / 必要
?   可以 / 選擇性 / 未知
⊥   永不 / 禁止 / nil
≠   不等於
∈   屬於
∉   不屬於
≤   最多
≥   至少
&   和
|   或
§   章節參考

保留原樣

永不壓縮：

• 程式碼區塊、片段、含反引號的單行。
• 路徑：src/auth/mw.go。
• URL。
• 識別符：函式名稱、變數名稱、環境變數。
• 數字與版本。
• 錯誤訊息字串。
• SQL、regex、JSON、YAML。
• 引號內的字串。

格式

不變式：

V<n>: <主體> <關係> <條件>
V1: ∀ req → handler 前進行 auth 檢查
V2: token 過期時間 ≤ 目前時間 → 拒絕

Bug 列（§B 下的管線表格）：

id|date|cause|fix
B1|2026-04-20|token `<` 非 `≤`|V2

任務列（§T 下的管線表格）：

id|status|task|cites
T3|x|新增 auth 中介軟體|V1,I.api

狀態：x 完成，~ 進行中，. 待辦。跳脫文字 | 為 \|。

介面：

<種類>: <名稱> → <形狀>
api: POST /x → 200 {id:string}
cmd: `foo bar <arg>` → stdout JSON
env: FOO_KEY ! 設定

範例

不好：

系統應確保每個傳入請求在轉發到對應的處理函式前，都經過適當的驗證。

好：

V1: ∀ req → handler 前 auth 檢查

不好：

我們發現中介軟體中的 token 過期檢查使用了嚴格小於比較運算子，這導致 token 在到期的那一刻被拒絕。

好：

B1: token < 非 ≤ → 在到期邊界拒絕。

不好：

/x 的 POST 端點接受 JSON 主體，並回傳包含建立 id 的物件的 200 回應。

好：

api: POST /x → 200 {id}

邊界情況

• 用戶要求散文解釋 → 切換為一般英文。
• 供外部審查的規格文件（RFC、提案） → 一般英文。
• 提交訊息 → 一般英文（git 讀者預期如此）。
• 程式碼中的 diff 註解 → 一般英文。

不確定時

若刪除某個字會遺失事實，則保留。穴居人是壓縮，不是截肢。