Human Readable Refactor

A Claude Code skill for behavior-preserving refactors that turn noisy, over-commented, over-abstracted, or “vibe-coded” code into clear, idiomatic, repository-native code.

The goal is not to falsify authorship or bypass disclosure requirements. The goal is to reduce technical debt: clearer names, fewer redundant comments, simpler control flow, and less duplication.

What this skill does

human-readable-refactor helps Claude Code perform a focused cleanup pass over a file, directory, branch diff, or selected subsystem.

It looks for:

• comments that merely restate obvious code;
• vague names such as data, result, item, helper, manager, processor, or handleThing;
• unclear function boundaries;
• dead code and unused private helpers;
• duplicated logic;
• speculative abstractions with one caller or one implementation;
• inconsistent naming, logging, error handling, or formatting compared with nearby code;
• broad defensive branches that make code harder to read without preserving a known behavior requirement.

It prefers:

• domain-specific names;
• small behavior-preserving diffs;
• straightforward control flow;
• comments that explain why, not what;
• local repository conventions over generic style advice;
• tests, type checks, linting, or builds as evidence that behavior was preserved.

What this skill does not do

This skill is not intended to:

• hide AI usage from maintainers, employers, clients, or repository policies;
• bypass AI-code detectors;
• rewrite Git history, authorship, commit metadata, or provenance;
• make broad architecture changes;
• change public APIs, routes, serialized fields, database schemas, config keys, event names, or error semantics without explicit approval;
• introduce new dependencies;
• perform formatting churn across unrelated files.

Use it as a maintainability refactor tool.

Repository layout

Recommended layout:

human-readable-refactor/
├── README.md
└── .claude/
    └── skills/
        └── human-readable-refactor/
            └── SKILL.md

Claude Code loads the skill from the SKILL.md file. The directory name becomes the slash command name:

/human-readable-refactor

Installation

Option 1: Install into one project

Copy the skill directory into the target repository:

mkdir -p /path/to/project/.claude/skills
cp -R .claude/skills/human-readable-refactor /path/to/project/.claude/skills/

Then start Claude Code from that project:

cd /path/to/project
claude

Use the skill:

/human-readable-refactor src/payments

Option 2: Install as a personal skill

Copy the skill into your personal Claude Code skills directory:

mkdir -p ~/.claude/skills
cp -R .claude/skills/human-readable-refactor ~/.claude/skills/

The command will then be available across your projects:

/human-readable-refactor path/to/code

Option 3: Symlink during development

For local development of this skill, symlink it instead of copying it:

mkdir -p ~/.claude/skills
ln -s "$PWD/.claude/skills/human-readable-refactor" ~/.claude/skills/human-readable-refactor

This makes edits to SKILL.md available without repeatedly copying files.

Usage

Refactor one file

/human-readable-refactor src/payments/discounts.ts

Refactor a directory

/human-readable-refactor src/payments

Refactor only the current diff

/human-readable-refactor current git diff only. Do not touch unrelated files.

Run an audit before editing

/human-readable-refactor Audit src/payments for noisy comments, vague names, duplication, dead code, and over-abstraction. Do not edit files yet.

Keep public APIs stable

/human-readable-refactor Refactor src/api/users.ts for readability. Preserve all exported names, route names, response shapes, error semantics, and tests.

Comments-only cleanup

/human-readable-refactor Perform a comments-only cleanup on src/reports/exporter.ts. Do not change executable code.

Naming-only cleanup

/human-readable-refactor Perform a naming-only refactor on src/checkout. Rename only private/local identifiers. Do not rename public exports or serialized fields.

Recommended workflow

For larger codebases, use the skill in multiple small passes instead of asking for one large rewrite.

1. Audit pass

Ask for a read-only audit first:

/human-readable-refactor Audit src/billing. Do not edit. Return cleanup opportunities ranked by impact and behavior risk.

Expected output:

• files or areas with the most noise;
• comments to delete, rewrite, or keep;
• names to improve;
• duplication or dead-code candidates;
• over-abstraction candidates;
• public API risks;
• suggested verification commands.

2. Low-risk cleanup pass

Apply only safe edits:

/human-readable-refactor Apply only low-risk behavior-preserving cleanup to src/billing. Keep public APIs stable and run relevant tests.

3. Focused follow-up passes

Use narrower prompts for risky areas:

/human-readable-refactor Simplify private helpers in src/billing/invoice-calculator.ts. Do not change exported symbols.

/human-readable-refactor Deduplicate validation logic in src/billing. Preserve error messages exactly.

/human-readable-refactor Rename vague local variables in src/billing. Do not rename API fields, database columns, or snapshot keys.

Refactor rules baked into the skill

The skill instructs Claude Code to:

1. inspect nearby code before editing;
2. infer local naming, commenting, error-handling, logging, and abstraction conventions;
3. preserve observable behavior;
4. avoid public-contract changes unless explicitly requested;
5. prefer deletion, renaming, simplification, and deduplication over new abstractions;
6. remove comments that narrate obvious code;
7. keep comments that explain constraints, invariants, tradeoffs, or external API quirks;
8. run the narrowest relevant verification command after changes;
9. report what changed, how it was verified, and what risks remain.

Comment policy

Delete comments like:

// Loop through all users
for (const user of users) {
  // Check if user is active
  if (user.active) {
    // Add user to result
    result.push(user)
  }
}

Prefer code that explains itself:

const activeUsers = users.filter((user) => user.active)

Keep comments like:

// Stripe sends duplicate webhook events, so this must stay idempotent.

// Keep this mapping stable; mobile clients cache these enum values.

// The upstream API returns cents as strings for currencies without minor units.

Naming policy

Avoid generic names unless they are already established domain terms in the repository.

Weak names:

data
result
item
obj
temp
helper
manager
processor
handler
utils
processData
handleThing

Better names are based on the domain and local conventions:

invoiceLines
eligibleDiscounts
paymentAttempt
shippingQuote
normalizedEmail
createRefundRequest
calculateInvoiceTotal

The skill should avoid renaming public exports or serialized fields unless you explicitly request a migration.

Verification

The skill should run the narrowest useful check after editing, such as:

npm test -- src/payments
npm run typecheck
npm run lint
pytest tests/payments
cargo test payments
go test ./internal/payments/...

The exact command depends on the project. If no verification command is available, the final response should say so clearly and mark the change as unverified.

Example final report

A good final response from Claude Code should look like this:

Summary
- Removed redundant comments from discount calculation flow.
- Renamed private locals to match billing-domain terminology.
- Inlined a one-off helper used only once.
- Preserved public exports and response shapes.

Files changed
- src/payments/discounts.ts
- src/payments/discounts.test.ts

Verification
- npm test -- src/payments/discounts.test.ts: passed
- npm run typecheck: passed

Behavior-preservation notes
- No exported names changed.
- Existing tests pass.
- Error messages and API response fields were left unchanged.

Skipped
- Did not rename calculateDiscount because it is exported.
- Did not deduplicate tax handling because it crosses module boundaries and needs a separate review.

License

MIT