avoid-ambiguous-suffixes

Original source / Raw SKILL.md

---
name: avoid-ambiguous-suffixes
description: 命名・設計レビューにおいて、Manager / Util / Facade / Service / Runtime / Engine など意味が一意に定まらないサフィックスの使用を検出し、責務・境界・契約が明確に伝わる命名へ導くためのスキル。
---

# 目的
- 型・モジュール・トレイト名から責務・境界・契約が即座に推測できる状態を保つ
- 曖昧な語による責務の吸い込み・肥大化・境界崩壊を防ぐ
- ドメイン語彙を優先し、アーキテクチャ語による意味の希薄化を避ける

# 基本原則（普遍ルール）
- 命名は「何をするか」ではなく「何であるか」を表す
- 名前は責務・境界・依存方向を最小限の語で符号化する
- プロジェクト内で意味が一意に定義できない語はサフィックスとして使わない

# 禁止・非推奨サフィックス

## 新規命名では、以下のサフィックスを使用しない
- Manager
- Util
- Facade
- Service
- Runtime
- Engine

## 非推奨理由（共通）
- 意味が一意に決まらない
- 責務の境界を示さない
- 依存してよい／いけない層が名前から推測できない
- 将来の責務追加の受け皿になりやすい

# 例外ルール
- 外部 API / OSS / フレームワーク由来の名称は無理に改名しない
- 既存コードにおいては、責務が明文化されている場合のみ例外的に許容できる
- 例外を設ける場合は、その語の意味をプロジェクト命名規約に明記すること

# 要注意サフィックス（Driver / Stub）
- Driver は原則として「ハードウェアに対するドライバ」の文脈でのみ許容する
- ハードウェア文脈以外で Driver を使うと誤解を招くため避ける
- テスト文脈の Driver は許容するが、必ず *TestDriver をサフィックスにする
- Stub は必ず *TestStub とし、単独の *Stub は禁止する
- 例: TickDriver はハードウェアドライバなので許容、ManualTestDriver はテスト文脈なので許容

# レビュー時の判定フロー
1. 対象の型・トレイト・モジュール名を確認する
2. 禁止・非推奨サフィックスを含むかを確認する
3. 含む場合、次の質問に答える
   - この名前だけで責務を一文で説明できるか？
   - 依存してよい層・してはいけない層が推測できるか？
4. できない場合は、具体名への置換案を提示する
5. 既存命名規約（*Shared / *Handle など）との整合を確認する
6. 命名変更が確定したら、参照箇所・ドキュメント・spec を更新する

# 置換の考え方
- 動作より役割（Role）・責務（Responsibility）・構造（Structure）を優先する
- 複数責務が見える場合は、命名ではなく設計を分割する
- 「便利そうだからまとめる」を禁止し、「名前で境界を作る」ことを優先する

# 責務別 命名パターン例

## データ保持・管理
- *Registry
- *Catalog
- *Index
- *Table
- *Store

## 選択・分岐・方針
- *Policy
- *Selector
- *Router

## 仲介・調停・制御
- *Coordinator
- *Dispatcher
- *Controller

## 生成・構築
- *Factory
- *Builder

## 変換・適合
- *Adapter
- *Bridge
- *Mapper

## 実行・評価（Runtime / Engine の代替）
- *Executor
- *Scheduler
- *Evaluator

# 迷ったときの確認事項（強制チェック）
- この型は何を所有しているか（状態・ライフサイクル）
- 単一責務として説明できるか
- 名前から依存方向・利用範囲が推測できるか
- ドメインの言葉として会話に耐えるか

# よくあるアンチパターン
- XxxManager = 「Xxxに関することを全部やる箱」
- Util = 「設計されていない再利用コード」
- Service = 「層や責務が未整理な処理の寄せ集め」
- Engine / Runtime = 「何が動くのか分からない実行体」

# 最終チェック（レビュー用一句）
「この名前だけ見て、何に依存してよいか分かるか？」
分からないなら、その名前はまだ設計途中である。