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

バグ行（§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

例

悪い例：

システムは、対応するハンドラー関数に転送する前に、すべての受信リクエストが適切に認証されていることを確認する必要があります。

良い例：

V1: ∀ req → handler の前に auth check

悪い例：

ミドルウェアのトークン有効期限チェックで厳密な小なり比較演算子が使われていたため、有効期限ちょうどの時点でトークンが拒否されることが分かりました。

良い例：

B1: token < not ≤ → expiry boundary で reject。

悪い例：

/x の POST エンドポイントは JSON ボディを受け取り、作成された ID を含むオブジェクトと 200 レスポンスを返します。

良い例：

api: POST /x → 200 {id}

適用範囲

• ユーザーが文章での説明を求めている場合 → 通常の英語に切り替えます。
• 外部レビュー向けの仕様文書（RFC、提案書） → 通常の英語にします。
• コミットメッセージ → 通常の英語にします（Git の読者はそれを想定しています）。
• コード内の差分コメント → 通常の英語にします。

判断に迷った場合

語を削ることで事実が失われるなら、その語は残してください。Caveman は圧縮であり、切り捨てではありません。