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.
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.
Improve the names in:
Only if [DOMAIN_GLOSSARY] is given: Domain glossary: Only if [CONVENTIONS] is given: Conventions:
- 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.
- 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).
- 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, notgetUser); 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. - 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.
- 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.
- Run the type checker, linter and tests if they exist, and report the real results. Behaviour must not change.
- 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.
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
use in
npx @hermes-hq/hodios install improve-naming --target claude-codenpx skills add hermes-hq/hodios-dist --skill improve-naming -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of RefactoringCode 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-reviewerSimplify 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-functionExtract 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-moduleReduce 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-duplicationPlan 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-refactorRemove 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