naming

命名

ハブと同期する単一のリストです。ゲート naming は、プッシュ時と CI で機械的にチェックできる項目を確認し、それ以外はあなたの判断に委ねます。境界については references/lint.md を参照してください。

何かに名前を付ける前に、node .agents/skills/naming/scripts/config.mjs を実行し、現在のルールとしてその出力を読んでください。出力には、プロジェクトのオーバーライドをマージした references/naming.json が表示されます。

ルール

1. それぞれに使う単語は一つだけで、その単語は GLOSSARY.md にあるものを使います。まずそこを確認し、次に既存の型、DB テーブル、API ルートを確認してください。リポジトリで使われている単語を、依頼で使われた単語より優先します。

   良い例	悪い例	理由
   testimonial	customerQuote	依頼では「customer quotes」とされていましたが、リポジトリでは testimonial を使っています
   Testimonial 型、testimonials テーブル、/api/testimonials	Testimonial 型、reviews テーブル	どこでも、一つのものには一つの単語を使います
   order	order と並ぶ purchase	一つのものに二つの単語を使うと、検索が分散します

2. まだ単語がない場合は、term-check を実行し、結果をユーザーに提示して承認を得てから、そのファイルを管理する domain-modeling を通じて GLOSSARY.md に単語を追加します。

   良い例	悪い例	理由
   用語チェック済みで、GLOSSARY.md に記録された carryOver	PR で独自に作った carryOver	新しい単語にはユーザーの承認が必要です
   複数形 caseStudies とともに記録された caseStudy	記録のない caseStudy	次のエージェントが別の単語を選んでしまいます
   ロールのリストに追加された grid	リストはそのままで使われる Grid	定義済みリストにないロールは新しい単語です

3. 型ではなくロールに基づいて命名します。I や T の接頭辞、ハンガリアン記法、ノイズワードは使いません（naming.json の noiseWords を参照）。

   良い例	悪い例	理由
   User	IUser	I の接頭辞は使いません
   count	nCount	ハンガリアン記法は使いません
   accounts	accountList、accountData	ノイズワードは不要です。複数形だけで複数であることがわかります

4. 単語は省略せず、1 文字の名前やマジックナンバーは使いません。使用禁止の短縮語は naming.json の shortWords に記載されています。

   良い例	悪い例	理由
   options	opts	単語を省略しません
   error	e、err	1 文字や略語は使いません
   const MAX_RETRIES = 3	単独の 3	数値には名前が必要です

5. 呼び出し元ですでに示されていることは、名前に含めません。

   良い例	悪い例	理由
   user.name	user.userName	オブジェクトが user を示しています
   testimonials.add(item)	testimonials.addTestimonial(item)	コレクションが testimonial を示しています
   テーブル testimonials のフィールド name	フィールド testimonial_name	テーブルが testimonial を示しています

6. アクションの名前は、naming.json の prefixes にある動詞で始め、意味ごとに動詞を一つだけ使います。純粋な派生値には名詞を使ってもかまいません。

   良い例	悪い例	理由
   fetchTestimonials	それと並ぶ loadTestimonials	意味ごとに動詞は一つだけです。fetch はネットワーク経由で取得することを示します
   listUsers	getAllUsers	list は複数を意味します
   branchSha	getBranchSha	純粋な派生値には名詞を使ってもかまいません

   接頭辞は、その意味を約束します。get は読み取り専用、set は値を返さないことを示し、is はブール値を返します。また、find は結果がない場合もありますが、get はそうではありません。and を含む名前（saveAndNotify）は、二つの関数を意味します。

7. 保存するブール状態には形容詞だけを使います。チェックには is、has、can、should を使い、notX の形は使いません。

   良い例	悪い例	理由
   archived	isArchived	保存する状態には形容詞だけを使います
   isEmpty、canRetry	empty()、retryAllowed	チェックには接頭辞を付けます
   enabled	notDisabled	肯定形の名前だけを使います

8. エンティティには単数形、コレクションには複数形を使います。不規則な複数形は、単語の横に GLOSSARY.md へ記録してください。

   良い例	悪い例	理由
   型 Testimonial、ファイル testimonial.ts	型 Testimonials	単一のエンティティは単数形です
   テーブル、パス、フォルダー testimonials	テーブル testimonial	コレクションは複数形です
   GLOSSARY.md に複数形として記録された case_studies	case_studys	不規則な複数形は一度だけ記録します

9. enum は使いません。文字列リテラルのユニオン型、または as const オブジェクトを使います。識別子キーは naming.json の discriminant（kind）です。独自の値はケバブケースにし、外部 API からミラーする値はそのままにします。

   良い例	悪い例	理由
   type Status = 'open' | 'in-progress'	enum Status { Open }	enum は使いません
   { kind: 'pull-request' }	{ type: 'pull-request' }	識別子キーは kind です
   GitHub API の 'MERGED'	'merged'	ミラーする値はそのままにします

10. naming.json の parts から、名前の大きな単位から小さな単位へ組み立てます：project · area · entity · role · action · attribute · consumer。必要なパーツを選び、順序は維持します。各 artifacts エントリーにはパーツ、ケース、例が記載されています。role はリポジトリごとの固定リストです（artifacts.component.roles、artifacts.env.roles）。環境変数は artifacts.env.shape に従います。Payload CMS では、コレクションのスラッグ＝API パス＝テーブルです。スラッグはケバブケースかつ複数形（case-studies）にし、テーブルではハイフンをアンダースコアに置き換えます（case_studies）。

    良い例	悪い例	理由
    COLIN_SYNC_KEY_FOR_TWENTY	TWENTY_API_KEY	発行元、そのキーの用途、保持者の順です
    TestimonialGrid	GridTestimonial	エンティティを先にし、その後に役割を続けます
    testimonial.added	addTestimonial	イベントは過去に起きた事実であり、命令ではありません

11. 大文字・小文字の使い分けは、言語ガイドとリポジトリのリンターに従います。ファイル名とフォルダー名は小文字のケバブケースにします。ただし、既存のリポジトリ規約がこのルールに優先します。その場合は artifacts.file.case と artifacts.folder.case に設定します。ケースは1つ、またはリストで指定します（React コンポーネントとフックの場合は ["kebab", "PascalCase", "camelCase"]）。

    良い例	悪い例	理由
    render-pr-body.mjs	renderPrBody.mjs	ファイル名はケバブケースです
    src/components/case-studies/	src/components/case_studies/	フォルダー名はケバブケースです
    load をどこでも使っているリポジトリでの loadUser	その隣にある fetchUser	既存の規約が優先されます

12. 意味が変わりましたか？writing-rules のルール 204 に従い、同じ変更内ですべての箇所の名前を変更します。

    良い例	悪い例	理由
    コード、ドキュメント、DB で draft を proposal に一度の PR で変更	コードでは変更したが、ドキュメントにはまだ draft と記載	1つのものを2つの言葉で表しています
    値が上限でなくなった後の retryCount	maxRetries のまま	名前が実態と合いません
    名前の変更と GLOSSARY.md の更新	名前の変更のみ	用語集が情報源です

プロジェクトごとの上書き

上書きファイル：.skilly/naming.json。references/naming.json と同じ形式で、変更するキーのみを記述します。古い docs/agents/naming.json は .skilly/naming.json がない場合に限り読み込まれます。.skilly/naming.json に移してください。

マージ順：

1. references/naming.json
2. .skilly/config.json の bundles に記載された各バンドルの references/stacks/<bundle>.json。記載順に適用します。ファイルがない場合はスキップします。includes 経由でのみ参照されるバンドルは対象外です。
3. .skilly/naming.json

マージのルール：

• オブジェクトはキーごとにマージします。null はキーを削除します。
• 配列は末尾に追加し、重複を除去します。"-Data" はデフォルトの Data を削除します。
• スカラー値は上書きします。

{
  "prefixes": { "sync": { "meaning": "mirror to a remote system", "not": ["push", "mirror"] } },
  "noiseWords": ["-Data"],
  "allow": {
    "ctxTools": { "names": ["^ctx_"], "rules": ["short-word"], "why": "lean-ctx tool names." },
    "payload/migrations": null
  }
}

allow には名前付きエントリーを記述します。形式と抑制される内容については、references/lint.md を参照してください。

参照資料

• references/naming.json：プレフィックス、パーツ、成果物、短い単語、ノイズワード、同義語、識別子、許可リスト
• references/stacks/：バンドルごとのデフォルト設定。同じ形式です
• references/lint.md：ゲートでチェックする内容、判断する内容、リポジトリごとの例外
• references/biome.json：利用者向けのオプトイン Biome ブロック
• scripts/config.mjs：統合済みの設定を出力します
• scripts/check.mjs：ブランチで変更されたファイルに対してゲートを実行します