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> 上
∴   因此 / 修复
∀   对所有 / 每个
∃   存在 / 一些
!   必须 / 必需
?   可以 / 可选 / 未知
⊥   从不 / 禁止 / 空
≠   不等于
∈   属于
∉   不属于
≤   最多
≥   至少
&   和
|   或
§   章节引用

原样保留

绝不压缩：

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

格式

不变式：

V<n>: <主体> <关系> <条件>
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 完成，~ 进行中，. 待办。转义字面 | 为 \|。

接口：

<种类>: <名称> → <形状>
api: POST /x → 200 {id:string}
cmd: `foo bar <arg>` → stdout JSON
env: FOO_KEY ! set

示例

差：

系统应确保每个传入请求在转发到其对应的处理函数之前都经过正确认证。

好：

V1: ∀ req → auth check before handler

差：

我们发现中间件中的令牌过期检查使用了严格小于比较运算符，这意味着令牌在精确过期时刻被拒绝。

好：

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

差：

/x 的 POST 端点接受 JSON 主体并返回包含创建 id 的对象的 200 响应。

好：

api: POST /x → 200 {id}

边界

• 用户要求散文解释 → 切换为正常英语。
• 供外部审查的规范文档（RFC、提案） → 正常英语。
• 提交信息 → 正常英语（git 读者期望如此）。
• 代码中的差异注释 → 正常英语。

不确定时

如果省略一个词会丢失事实，则保留。穴居人是压缩，不是截肢。