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。

符号

优先使用符号，而非文字：

→   leads to / becomes / on <x>
∴   therefore / fix
∀   for all / every
∃   exists / some
!   must / required
?   may / optional / unknown
⊥   never / forbidden / nil
≠   not equal
∈   in
∉   not in
≤   at most
≥   at least
&   and
|   or
§   section reference

原样保留

绝不压缩：

• 代码块、代码片段、带反引号的单行代码。
• 路径：src/auth/mw.go。
• URL。
• 标识符：函数名、变量名、环境变量。
• 数字和版本号。
• 错误消息字符串。
• SQL、正则表达式、JSON、YAML。
• 引号中的字符串。

格式

不变量：

V<n>: <subject> <relation> <condition>
V1: ∀ req → auth check before handler
V2: token expiry ≤ current_time → reject

Bug 行（§B 下的管道表格）：

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

任务行（§T 下的管道表格）：

id|status|task|cites
T3|x|add auth mw|V1,I.api

状态：x 已完成，~ 进行中，. 待办。字面量 | 转义为 \|。

接口：

<kind>: <name> → <shape>
api: POST /x → 200 {id:string}
cmd: `foo bar <arg>` → stdout JSON
env: FOO_KEY ! set

示例

错误：

The system should ensure that every incoming request is properly authenticated before being forwarded to its corresponding handler function.

正确：

V1: ∀ req → auth check before handler

错误：

We discovered that the token expiration check in the middleware was using a strict less-than comparison operator, which meant tokens were being rejected at the exact moment of their expiry.

正确：

B1: token < not ≤ → reject @ expiry boundary.

错误：

The POST endpoint at /x accepts a JSON body and returns a 200 response with an object containing the created id.

正确：

api: POST /x → 200 {id}

适用范围

• 用户要求用散文解释 → 切换为常规英语。
• 面向外部评审的规范文档（RFC、提案）→ 使用常规英语。
• 提交消息 → 使用常规英语（Git 读者对此有预期）。
• 代码中的差异注释 → 使用常规英语。

不确定时

如果删掉某个词会丢失事实，就保留它。Caveman 是压缩，不是删减。