conditional-normative-notation

Conditional Normative Notation: 条件付き規範記法

エージェント向けの規約（AGENTS.md / CLAUDE.md / .claude/rules/**）を、曖昧さなく書くための記法。 散文の指示を「要求度キーワード層」と「条件付きルール構造層」の2層に分解して記述する。

変換・執筆したい対象（散文の規約テキスト、または対象ファイルのパス）: $ARGUMENTS 引数が空のときは、ユーザーに対象を確認するか、現在の文脈で扱っている規約を対象とする。

なぜこの記法か

散文の指示（例:「テストはなるべく書くこと」）には2つの曖昧さが同居している。

1. 強制力の曖昧さ — 「なるべく」は禁止なのか推奨なのか、読み手によってブレる
2. 発動条件の曖昧さ — いつ適用されるのか（常時か、特定の状況だけか）が書かれていない

この2つを分離して明示するのが本記法の目的。強制力を RFC 2119 キーワードで、発動条件を IF で固定すると、LLM も人間も同じ解釈に収束し、将来 lint や CI で機械的に検証する余地も生まれる。

記法の2層構造

層1: 要求度キーワード (RFC 2119)

キーワードは RFC 2119 に規定された意味で解釈する。大文字で書くことで「これは規範であって地の文ではない」と宣言する。

• MUST — 絶対要件。違反は許されない
  • 使いどころ: 破壊的操作の確認、不可逆操作の前提条件
• PROHIBIT — 絶対禁止。RFC 2119 の MUST NOT と等価
  • 使いどころ: やると壊れる・取り返しがつかない行為
  • 採用理由: 先頭トークンで「これは禁止である」と読み取れる
• SHOULD — 原則やるべき。逸脱には正当な理由が要る
  • 使いどころ: 守ってほしい既定。例外を許容したい規範
• SHOULD NOT — 原則避けるべき。逸脱には正当な理由が要る
  • 使いどころ: 推奨されないが状況により許容
• MAY — 任意。やってもやらなくてもよい
  • 使いどころ: 判断を読み手に委ねたい

PROHIBIT MUST NOT を書く。禁止を表すときは PROHIBIT を使う。MUST NOT は RFC 2119 の仕様参照のときだけ文中で言及してよいが、ルール本文では使わない。

1行1キーワード原則

1行に複数の判断キーワード (MUST / PROHIBIT / SHOULD / MAY 等) を置かない。複数の判断があるときは THEN: で改行し、各キーワードをサブ項目として列挙する。

Bad:

IF: PR を作成する; THEN MUST: Issue をリンクする AND PROHIBIT: 検索なしに「関連 Issue なし」と断定する

Good:

IF: PR を作成する; THEN
  - MUST: 関連 Issue を検索しリンクする
  - PROHIBIT: 検索なしに「関連 Issue なし」と断定する

層2: 条件付きルール構造

ルールは原則として次の形式で書く。

IF: <条件>; THEN <キーワード>: <行動>

• 条件が成立しない場合、そのルールは適用されない（IF は「いつ読むべきか」のゲート）
• 複数条件は AND / OR で結合する
• 優先順位がある場合は番号付き手順で示す
• 条件が常に真（無条件の規範）なら IF を省き、キーワードから書き始めてよい

規約の冒頭に置く宣言文

新しく規約ファイルを作る／この記法を導入するときは、先頭に次の宣言を置く。これが無いと「大文字の MUST」が単なる強調と区別できない。

本ドキュメントにおけるキーワード「MUST」「SHOULD」「SHOULD NOT」「MAY」は、RFC 2119 に規定された意味で解釈すること。「PROHIBIT」は RFC 2119 の「MUST NOT」と同義であり、先頭トークンで禁止と認識しやすくするために使用する。

ルールは原則として `IF: <条件>; THEN <キーワード>: <行動>` の形式で記述する。条件が成立しない場合、そのルールは適用されない。複数条件はネストし、優先順位がある場合は番号付き手順で示す。1行に複数の判断キーワード（MUST / PROHIBIT / SHOULD / MAY）を置かない。複数の判断がある場合は THEN で改行し、各キーワードをサブ項目として列挙する。

本ドキュメントの各ルールは、ユーザーが「作業の進み方を予測できる」「意図しない破壊や先送りを避けられる」「確認待ちを減らして成果物を早く受け取れる」状態を作るために存在する。

ルール追加時の嬉しさ (user-value) 記述ルール

各ルールは、それが存在することでユーザーが具体的に何を得られるか (=「嬉しさ」) を背骨に持つ。形骸化を防ぐため、追加・更新時に必ず嬉しさを検討する。ただし全ルールに嬉しさ注釈を書くわけではない — 自明なら書かない。

• IF: ルールを追加 / 更新する; THEN MUST: 「ユーザーにとって何が嬉しいか」を検討する
  • IF: 嬉しさが容易に検討できる (一般的な理論で自明); THEN MUST: 嬉しさを書かない
    • 例: 「日本語で応答する → 翻訳コスト不要」「CI 失敗を直す → 中途半端な状態で引き継がせない」など、ルールの裏返しを書いているだけの自明なもの
  • IF: そのルールでユーザーがどう嬉しいかを自己調査しても判断できない; THEN MUST: その価値判断をユーザーに確認してから追加 / 更新する
• IF: 既存ルールを解釈する; THEN SHOULD: 命令文だけでなく、そのルールが守ろうとしているユーザー価値から判断する

嬉しさ注釈の書き方:

- IF: <条件>; THEN MUST: <行動>
  - 嬉しさ: <そのルールが守られることでユーザーが具体的に得られる状態>

嬉しさ注釈の判定基準:

• 残す: ルールだけでは理由がわからないもの (技術的背景、非自明な制約理由、ユーザー固有の判断軸)
• 削除: ルールの裏返しを書いているだけの自明なもの
• 統合: 「理由:」と「嬉しさ:」が実質同じ → 1 つにまとめる

1ルールの書き方（解剖）

1ルールは「条件」「キーワード」「行動」の3要素で構成する。それぞれに品質基準がある。

• 条件 (IF)** — 読み手が**真偽を一意に判定できること。「重要な変更のとき」は不可（重要かは主観）。「破壊的変更を実行しようとしている」は可（実行内容から判定できる）。
• キーワード — 後述の選び方に従い、強制力に見合うものを1つ選ぶ。
• 行動 (THEN)** — その項目単独を読んで**実施内容が一意に決まる粒度。「適切に対応する」は不可。「実行前にユーザーに確認する」は可。

キーワードの選び方

強制力は「破ったときに何が起きるか」で決める。迷ったら次の問いを順に当てる。

1. 破ると取り返しがつかない／実害が出るか → MUST / PROHIBIT
2. 破ってよいが正当な理由の提示を求めたいか → SHOULD / SHOULD NOT
3. どちらでも構わない（許可を明示したいだけ）か → MAY

過剰な MUST を避ける。 すべてを MUST にすると、本当に重要な規範が埋もれ、読み手は全体を「努力目標」として読み流す。MUST は「ここだけは絶対」という希少性があってこそ効く。例外を1つでも許容したいなら SHOULD にし、許容条件を別ルールとして切り出すほうが伝わる。

条件の結合と優先順位

AND / OR で結合する:

IF: ファイルを変更する AND テストが存在する; THEN MUST: 変更後にテストを実行する

優先順位・段階がある場合は番号付き手順で示す:

IF: 判断に必要な情報が不足している; THEN MUST: 以下を順に試みる
  1. 既存コード / ドキュメントを検索する
  2. それでも不明; THEN MUST: ユーザーに確認する

THEN の中で分岐させてもよい:

IF: スコープ外の問題を発見した; THEN:
  - 5分以内で安全に直せる; THEN MAY: 同一 PR に含める
  - それ以外; THEN MUST: 別 Issue として切り出す

散文 → 規範ルールへの変換手順

既存の散文規約をこの記法へ書き換えるときの手順。

1. 強制力を見極める — 「べき」「なるべく」「してもよい」を RFC 2119 キーワードへ写像する
2. 発動条件を抽出する — 「〜のときは」を IF に切り出す。条件が書かれていなければ「常時か？特定状況か？」を補う
3. 行動を一意化する — 主語・対象・動詞を補い、単独で実施できる粒度にする
4. 例外を別ルールに分ける — 「ただし〜」は条件違いの別ルールへ（1ルールに but を詰め込まない）

良い例 / 悪い例

Bad（散文・曖昧）:

重要な変更をするときは、なるべく事前に確認すること。

強制力（なるべく＝？）も条件（重要な変更＝？）も曖昧。

Good（条件付き規範記法）:

IF: 不可逆な操作（破壊的変更 / 外部送信 / 課金発生）を実行しようとしている; THEN MUST: 実行前にユーザーに確認する

---

Bad（MUST の乱用）:

IF: コードを書く; THEN MUST: コメントを書く
IF: コードを書く; THEN MUST: テストを書く
IF: コードを書く; THEN MUST: ドキュメントを書く

すべて MUST だと優先度が消え、読み手は全体を流し読みする。

Good（強制力を区別）:

IF: 公開 API を追加する; THEN MUST: 対応するドキュメントを書く
IF: ロジックを追加する; THEN SHOULD: 対応するテストを書く
IF: 関数が30行を超える; THEN MAY: コメントで意図を補足する

品質チェックリスト

書き終えたら次を自問する。1つでも No があれば直す。

• 冒頭に RFC 2119 の解釈宣言があるか (PROHIBIT を使うなら MUST NOT の同義語であることも宣言してあるか)
• 各ルールの IF は真偽を一意に判定できるか（主観に依存しないか）
• キーワードは強制力に見合っているか（MUST を乱用していないか）
• THEN の行動は単独で読んで実施内容が一意に決まるか
• 1行に複数の判断キーワード (MUST / PROHIBIT / SHOULD / MAY 等) を置いていないか
• 複数の判断は THEN: 改行 + サブ項目で列挙してあるか
• PROHIBIT / SHOULD NOT には、代わりに何をすべきか（代替）が添えてあるか
• 「ただし」「例外的に」を条件違いの別ルールへ分けたか
• 無条件の規範は IF を省いて簡潔に書いているか
• 嬉しさ注釈は「ルールだけでは理由がわからない」ものに限定して書いてあるか (自明な裏返しになっていないか)