hermes

Improve naming in code

Proposes clearer names for variables, functions, types and modules, explains each rename and applies them without changing behaviour. Use when code reads poorly because of its names.

context

Names are most of what a reader has to understand code. Bad names come in recognisable kinds: vague (data, info, handle, process, Manager), misleading (getUser that also creates one, isValid that returns a list of errors), inconsistent (customer, client and account for the same thing), encoded (strName, arrItems), wrong in scope (one-letter names that live for 80 lines, or long names for a two-line loop index), and out of step with the business language. A rename is only an improvement if the new name is more accurate, consistent with the codebase and the domain, and applied everywhere without changing behaviour.

task

Improve the names in:

code

Only if [DOMAIN_GLOSSARY] is given: Domain glossary: Only if [CONVENTIONS] is given: Conventions:

  1. Read the code and enough of its callers to understand what each name really refers to and does. For functions, check what they actually do, including side effects and return values, not what their name claims.
  2. Find names worth changing and classify each: vague, misleading, inconsistent with the rest of the codebase or the glossary, encoded type or scope, wrong length for its scope, or a convention violation (case, prefixes, verb tense for booleans and functions).
  3. For each, propose one name following these rules: use the glossary's terms; functions are verbs that say what they do and reveal side effects (loadOrCreateUser, not getUser); booleans read as yes or no questions (isExpired, hasAccess); collections are plural; units go in the name when the type does not carry them (timeoutMs); length grows with scope; match the existing codebase's conventions over personal preference. If a name is misleading because the function does two things, say so and suggest the split in one line instead of hiding it with a longer name.
  4. Separate safe renames from risky ones. Risky renames include public API, exported symbols used by other packages, serialised field names (JSON, database columns, message schemas), configuration keys, names used via reflection, string-based lookups, templates or dependency injection, and anything in a published SDK. Do not apply risky renames; list them with the migration they would need.
  5. Apply the safe renames everywhere they are referenced, using the language's refactoring tooling or a careful search that also covers tests, comments and docs in the repo. If the code was pasted rather than in a repo, return the rewritten code.
  6. Run the type checker, linter and tests if they exist, and report the real results. Behaviour must not change.
constraints
  • Change names only. No logic changes, no reformatting, no reordering, no new abstractions.
  • Do not rename for taste: every rename has a reason from step 2. If the existing name is fine, leave it.
  • Keep the number of renames proportionate; prefer the 5 to 15 that most improve understanding over renaming everything.
  • Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
  • Keep the change as small as it can be while still being correct.
  • Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
  • If you could not run a check, say so plainly and say which one.
output format

Rename table

Table: old name, new name, kind (variable, function, type, module), problem, why the new name is better. Applied renames only.

Not renamed

Table: name, proposed name, why it was not applied (public API, serialised, reflection) and the migration it would need. Or "None".

Changes

For pasted code, the full rewritten code in one fenced block. For a repo, one line per file changed.

Verification

The checks run and their real results, or which checks could not be run.

1 required value still a placeholder; the assistant will ask for it.

details

kind
Prompt: a task you run by name to get one finished thing back
domain
Software engineering
category
Refactoring
level
Beginner
made for
Software engineer, Tech lead / staff engineer
needs
repo-read, file-write, shell
risk
runs-commands
version
v1.0.0 · incubating
reviewed
2026-10-02
works in
Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install improve-naming --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill improve-naming -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

pairs well with

All of Refactoring
PersonaCode review

Code reviewer

Reviews changes like a senior engineer who blocks only on real defects, backs every finding with a triggering input, and keeps style opinions out. Use as a reviewer persona or subagent.

code-reviewer
PromptRefactoring

Simplify a complex function

Rewrites a hard-to-follow function into a clearer one with identical behaviour, using guard clauses, named steps and simpler conditions, verified by tests. Use on long or deeply nested code.

simplify-function
PromptRefactoring

Extract a module

Moves one responsibility out of a large file or class into its own module in small, test-verified steps, without changing behaviour or the public API. Use when a file does too many things.

extract-module
PromptRefactoring

Reduce code duplication

Finds duplicated logic, separates true duplication from code that only looks alike, and merges only true duplicates behind one well-named function. Use when one fix keeps landing in many places.

reduce-duplication
PromptRefactoring

Plan a large refactor in safe steps

Turns a large refactor into small, independently shippable steps that keep the build green, each with a rollback, using patterns like expand-contract. Use for refactors too big for one PR.

plan-large-refactor
PromptRefactoring

Remove dead code safely

Finds unused code, flags, endpoints, jobs and dependencies, proves each dead with static and runtime evidence, and removes it or stages a reversible retirement. Use to shrink a codebase.

remove-dead-code