メニュー
Reviews naming quality and code obviousness via the isolation test, scope-length principle, and consistency audit. Use when names feel vague, something is hard to name (a design signal, not a vocabulary problem), or behavior isn't obvious on first read. Not for comment quality or documentation (use comments-docs).
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | naming-obviousness |
| description | Reviews naming quality and code obviousness via the isolation test, scope-length principle, and consistency audit. Use when names feel vague, something is hard to name (a design signal, not a vocabulary problem), or behavior isn't obvious on first read. Not for comment quality or documentation (use comments-docs). |
| argument-hint | [file or module path] |
| allowed-tools | Read, Grep |
When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.
Names are arguably the most important form of abstraction because a name claims what matters most about an entity. Because names appear at extreme frequency, mediocre names produce systemic complexity that no single example would suggest.
Read a name without surrounding context. Does it convey what the entity is?
byteCount, retryDelayMs, userAuthTokendata, x, process, handle, itemresult is acceptable for a method's return value but problematic at wider scopeGeneric names create false mental models because the reader's first assumption goes wrong and the name protects that wrong assumption from being questioned.
| Bad | Better | Why |
|---|---|---|
x / y (pixel coordinates) | columnIndex / rowIndex | Name what they index, not their axis |
connectStatus (boolean) | isConnected | Booleans should be predicates |
NULL_ACCOUNT_ID | ACCOUNT_NOT_CREATED | Say what it means, not what it is |
Too specific is also wrong. A parameter named filename on a method that accepts any path encodes a false constraint.
Too similar is also wrong. Related entities with near-identical names (config vs configuration, authKey vs authToken) force readers to memorize which is which. Names for related things should clarify the relationship, not obscure it.
Every word in a name should provide useful information.
| Pattern | Bad | Better | Why |
|---|---|---|---|
| Redundant noun | httpResponse | response | Context is already HTTP |
| Type-in-name | strName | name | IDEs make Hungarian notation unnecessary |
| Class echo | User.userName | User.name | Don't repeat the class name in its members |
When you struggle to find a precise name, the problem is design, not vocabulary.
| Symptom | Fix |
|---|---|
| The entity is doing two things | Split it |
| The abstraction isn't worked out | Clarify before naming |
| Two concepts have been conflated | Separate them |
Name length should scale with scope distance. i in a 3-line loop is clear. data at module scope is a defect.
A short name can be precise and still fail at long range because it carries no information when stripped of context. Verbosity doesn't compensate for vagueness. A name needs to be precise enough to create an accurate mental image that survives traveling to the use site.
The third requirement is critical. One name, two behaviors: the name looks consistent while concealing a semantic split. Short names are especially prone to this: pk for a primary key, a public key, or a private key, e for error, event, or element. Ambiguous short names across a codebase compound into real confusion.
"Software should be designed for ease of reading, not ease of writing." — John Ousterhout, A Philosophy of Software Design
Code is obvious when a first-time reader's guesses about behavior are correct.
The writer is the worst judge. When a reviewer says something isn't obvious, that's data.
Four recurring patterns that break obviousness:
Record<string, unknown> forces callers to cast and guess what keys exist. A named type would be self-documentingReadable hiding a Transform stream with different backpressure behaviorconnect() method that silently starts a background health-check threadReduce information needed (deep modules, information hiding), leverage what readers already know (conventions, expectations), present information explicitly (good names, comments).
Red flag signals for naming and obviousness are cataloged in red-flags (Vague Name, Hard to Pick Name, Non-obvious Code).
Evaluates whether abstractions provide a genuinely different way of thinking or are structurally shallow. Use when adjacent layers feel redundant, wrappers add boilerplate without depth, or an abstraction feels leaky. Not for a single module's interface-to-implementation ratio (use deep-modules) or information leakage across boundaries (use information-hiding).
Evaluates whether changes to existing code maintain or degrade design quality. Use when reviewing diffs, PRs, or recently modified files to judge whether each change looks designed-in or bolted-on. Not for scanning design smells (use red-flags) or assessing overall design investment (use strategic-mindset).
Reviews comment quality and documentation practices: the four comment types, comments-first workflow, and comment rot. Use when reviewing comments or docs, when comments just repeat the code, or when something is hard to describe in a sentence. Not for naming or code obviousness (use naming-obviousness).
Diagnoses whether complexity exists and where it comes from, using the three-symptom, two-root-cause framework. Use when code feels harder to work with than it should but the specific problem is unclear. Not for scanning known design smells (use red-flags) or evaluating a module's depth (use deep-modules).
Measures module depth: whether the interface is simple relative to the implementation behind it. Use when an interface has too many parameters or methods, many small classes each do too little, or methods just forward calls. Not for whether adjacent layers provide different abstractions (use abstraction-quality) or merging/splitting modules (use module-boundaries).
Generates and compares at least two fundamentally different design alternatives on concrete criteria before committing. Use when the user asks to design something twice, or before committing to any significant design of classes, modules, APIs, or architecture. Not for judging strategic vs. tactical investment in existing code (use strategic-mindset) or whether a change degrades design (use code-evolution).