#434

AGENTS.md

@@ -13,6 +13,28 @@
   秘匿版も安全な全体件数には含めるが、公開明細・内訳・検索件数とは分離する。
   秘匿属性を条件・軸・ソート・差分件数から推測できる実装を禁止する。
 
+## Mandatory naming contract
+
+- メソッド・関数など、実際に処理を実行する callable の名前以外の自前識別子に
+  動詞を使用しない。状態は名詞・形容詞・形容詞的な語で表す。今後の全開発に適用する。
+- 変数、引数、プロパティ、型定義内の項目、API・URL パラメータ、JSON キー、
+  DB カラムにも適用する。`is_` / `is`、`has_` / `has`、`can_` / `can`、
+  `should_` / `should` などの動詞・助動詞由来の接頭辞を使用しない。
+  状態を格納する識別子に `show`、`enable` 等の動詞も使用しない。
+- 形容詞で状態を表せる場合はその語を使う。例：`is_latest` / `isLatest` は
+  `latest`、`is_active` は `active`、`is_deleted` は `deleted`、
+  `is_visible` は `visible`、表示状態は `visible`、有効状態は `enabled`。
+- 名詞で真偽値を表す場合は原則 `_flg`、camelCase では `Flg` を付ける。
+  例：`is_admin` は `admin_flg`、`is_owner` は `owner_flg`、
+  `isAdmin` は `adminFlg`。クエリパラメータでは意味が明確なら接尾辞を省略できる。
+- callable の `setState`、`onChange` 等や、外部ライブラリ・フレームワーク所定の
+  API 名は変更しない。外部値を自前の状態へ保持する場合は境界で適切な別名を付ける。
+  言語固有の表記規約を維持し、予約語や曖昧さは規則を満たす明確な代替名で避ける。
+- 改名時は Frontend / Backend、URL、API、出力の名称を整合させる。
+  旧 URL・API の互換性は入出力境界で扱い、旧命名を新しい内部コードへ伝播させない。
+  DB の改名は既存データを保持する追加マイグレーションで扱い、適用済みのものを
+  書き換えない。メソッド名・外部 API・文字列値等を機械的な一括置換で破壊しない。
+
 ## Project overview
 
 BTRC Hub / タグ広場 is a split Rails API and React frontend repository.