Naming Conventions skill for Codex

A name is right when a reader can predict what the thing is and does without opening it, the same concept has the same name everywhere in the codebase, and the casing matches the language and the layer it lives in. Consistency with the repo beats personal preference and beats this skill’s defaults.

Before naming anything

• Read AGENTS.md, style guides and lint config (eslint naming-convention rules, ruff N rules, golangci-lint revive, .editorconfig).
• Search for the concept’s existing name: rg -n -i "customer|client|account" src | head. Reuse the term already in use; if two terms compete, ask the user which wins.
• Check the domain language: names used by product, support and the database. Code should say invoice if the business says invoice, not bill in one module and charge in another.

Casing by language and layer

Context	Convention	Example
Python variables, functions, modules	snake_case	fetch_orders, order_service.py
Python classes, exceptions	PascalCase; exceptions end in Error	OrderService, PaymentDeclinedError
Python constants	UPPER_SNAKE_CASE	MAX_RETRIES
TypeScript/JS variables, functions	camelCase	fetchOrders
TypeScript types, interfaces, classes, React components	PascalCase, no I prefix	Order, OrderList
TS/JS files	Follow the repo; common: kebab-case.ts, components PascalCase.tsx	order-service.ts
Go exported / unexported	MixedCaps / mixedCaps; initialisms all caps	ServeHTTP, userID, parseURL
Go packages	short, lowercase, no underscores, not plural	orders, httputil
Rust	snake_case fns, vars, modules; PascalCase types and traits; SCREAMING_SNAKE_CASE consts	fn parse_line, struct LineParser
Java / Kotlin	camelCase members, PascalCase classes, lower.dot packages	com.acme.orders
SQL tables, columns	snake_case; pick plural or singular tables once and keep it	order_items.unit_price_cents
JSON / REST fields	Match existing API; default camelCase for JS consumers, snake_case if the API already uses it	createdAt
URLs and paths	lowercase kebab-case, plural collections	/v1/order-items/{id}
CLI flags	--kebab-case, short flags only for the most common	--dry-run, -n
Environment variables	UPPER_SNAKE_CASE, prefixed by app	ACME_DATABASE_URL
CSS classes	Follow the system in use (BEM, utility classes, CSS modules)	order-card__title

Rules that make names predictable

Kind	Rule	Good	Bad
Booleans	Read as a yes/no question: is, has, can, should	isActive, hasAccess	active, flag, status
Negation	Positive names; negate at the call site	isEnabled	isNotDisabled
Functions	Verb + object; side effects in the verb	sendInvoice, computeTotal	invoice, doStuff
Getters vs work	get is cheap and pure; expensive or remote work uses fetch, load, compute	fetchUser (HTTP)	getUser that does HTTP
Collections	Plural nouns; maps name both sides	orders, priceBySku	orderList, map1
Counts and indices	count, index, total suffix or prefix	retryCount, pageIndex	num, n beyond tiny scopes
Units	Put the unit in the name when the type does not carry it	timeoutMs, priceCents, sizeBytes	timeout, price
Time	Instants vs durations	createdAt, expiresAt, ttlSeconds	created, expiry
Async	Follow the repo: either no suffix (TS default) or a consistent one	loadConfig() returning Promise	mixed loadConfigAsync and loadConfig
Abbreviations	Spell out unless universal (id, url, http, db)	customerAddress	custAddr
Scope length	Short names in tiny scopes, descriptive names in wide ones	i in a 3-line loop	i across a 60-line function
Generic words	Avoid data, info, manager, helper, util, handle without a noun	invoiceRenderer	InvoiceManager doing five things

A name that needs And (validateAndSave) usually signals a function that should be two.

Files and modules

• One naming scheme per directory; check five neighbouring files before adding one.
• Name modules after what they contain (pricing, invoice_pdf), not their layer alone (utils, common, misc grow without bound).
• Test files mirror the source file: pricing.py -> test_pricing.py, pricing.ts -> pricing.test.ts, pricing.go -> pricing_test.go.
• Avoid names that differ only by case (Order.ts and order.ts): macOS and Windows default filesystems are case-insensitive and git will misbehave.

Renaming safely

Renames look trivial and break things outside the type checker’s view.

- [ ] 1. Find every occurrence in every form: camelCase, snake_case, kebab, plural, strings
- [ ] 2. Classify: internal symbol / public API / serialized (JSON, DB, events, cache keys, env, URLs)
- [ ] 3. Internal: use the IDE or language server rename, then rg for leftovers
- [ ] 4. Public or serialized: keep the old name working (alias, deprecation, dual-read)
- [ ] 5. Rename files with git mv so history follows
- [ ] 6. Build, typecheck, tests; rg again for the old name

rg -n -i "cust(omer)?_?addr(ess)?|customer-address" --hidden -g '!node_modules'
git mv src/custAddr.ts src/customer-address.ts

For mechanical renames across many files, a codemod or ast-grep rewrite is safer than regex replacement (see codemods). For serialized names, renaming a database column, JSON field, event type or env var is a migration: add the new name, write both, move readers, then remove the old name in a later release. Ask the user before changing any name that external clients, stored data or other services depend on.

Gotchas

• Text search misses dynamic access (obj[field], getattr, reflection, ORM string fields, templates). Search strings, configs and templates too.
• Renaming a Go exported identifier or a Python public function is a breaking change for library users (see semantic-versioning).
• Case-only file renames on case-insensitive filesystems need two steps: git mv order.ts order.tmp.ts && git mv order.tmp.ts Order.ts.
• Changing JSON field names in API responses breaks clients silently; contract tests or OpenAPI diffs catch it, eyes do not.
• Do not mix a broad rename with behaviour changes in one commit; reviewers cannot see the real change.

Output

When reviewing or proposing names:

| Location | Current | Proposed | Reason | Risk |
|---|---|---|---|---|
| src/billing/calc.ts:12 | `amt` | `amountCents` | unit and abbreviation | internal |
| api/orders.py:40 | `active` | `is_active` | boolean reads as question | JSON field - needs dual-write |
| (glossary) | user / account / customer | `customer` for paying orgs, `user` for logins | three terms for two concepts | discuss |

Offer to add agreed rules to AGENTS.md so future changes follow them; ask first.

Verification

• rg for the old name returns only intentional compatibility aliases and changelog lines.
• Build, typecheck, lint (with naming rules if configured) and tests pass.
• Serialized renames have a compatibility path and a removal date.