Dev Loop Refactor Guide

Use when the user asks to refactor a long function or class safely, remove code smells, extract methods, untangle legacy code, or improve structure without changing behavior. Produces a step-by-step refactoring plan with characterization tests. Not for tracking debt backlogs (use dev-loop-tech-debt-tracker) or system migrations (use enterprise-legacy-migration).

45 stars 6 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add j4flmao/agent-skills --skill dev-loop-refactor-guide
Manual install
git clone --depth 1 https://github.com/j4flmao/agent-skills.git /tmp/agent-skills
mkdir -p ~/.claude/skills
cp -r /tmp/agent-skills/skills/dev-loop/refactor-guide ~/.claude/skills/dev-loop-refactor-guide

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Refactoring Guide

## Purpose
Systematically improve code structure, readability, maintainability, and extensibility without changing external behavior — applying proven refactoring techniques, identifying code smells, and establishing refactoring workflows that reduce technical debt safely.

## Agent Protocol

### Trigger
Exact user phrases: "refactor", "code smell", "technical debt", "improve code", "clean up code", "extract method", "restructure", "modernize", "legacy code", "refactoring strategy", "decouple", "extract class".

### Input Context
- Codebase size and age (new project → legacy codebase)
- Language and framework (affects available refactoring tools)
- Current pain points (duplication, long methods, tight coupling, slow tests)
- Test coverage (% and quality)
- Refactoring goal (improve readability, enable new feature, reduce bugs, pay down debt)
- Risk tolerance (safety-critical, high-traffic, low-risk internal tool)

### Output Artifact
Refactoring plan with prioritized code smells, technique application, and verification strategy.

### Response Format
```
Target: {module/files}
Smells: {smell -> location}
Safety net: {existing tests | characterization tests to add}
Steps (each behavior-preserving, committed separately): {technique -> change}
Verification: {tests/commands}
Risk: {low|med|high} — rollback {plan}
```

### Completion Criteria
- [ ] Code smells identified and cataloged
- [ ] Refactoring techniques selected for each smell
Read the full skill on GitHub

Details

Skill name
dev-loop-refactor-guide
Path
skills/dev-loop/refactor-guide/SKILL.md
License
MIT
Repo updated
17 November 2026

FAQ

What does the Dev Loop Refactor Guide skill do?

Use when the user asks to refactor a long function or class safely, remove code smells, extract methods, untangle legacy code, or improve structure without changing behavior. Produces a step-by-step refactoring plan with characterization tests. Not for tracking debt backlogs (use dev-loop-tech-debt-tracker) or system migrations (use enterprise-legacy-migration).

How do I install the Dev Loop Refactor Guide skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add j4flmao/agent-skills --skill dev-loop-refactor-guide. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Dev Loop Refactor Guide popular?

It lives in j4flmao/agent-skills, which has 45 GitHub stars and 6 forks.

Related skills

Agent Observability

45

j4flmao/agent-skills

Use when the user asks about agent observability, tracing agent reasoning, debugging an agent loop, OpenTelemetry GenAI spans for LLM calls, LLM cost tracking per agent, agent audit logs or hallucination/eval monitoring in production. Produces instrumentation config, trace schema, dashboards, alerts and cost attribution. Not for generic service tracing without LLMs (use devops-opentelemetry).

DevOps & Cloud

AI Agent Architectures

45

j4flmao/agent-skills

Use when the user asks to build an AI agent, design an agent that calls tools and keeps memory, write an agent system prompt or pick an agent framework (Claude Agent SDK, OpenAI Agents SDK, LangGraph). Produces an architecture brief covering loop, tools, memory, guardrails and evals, routing depth to child skills. Not for workflow patterns (use ai-agentic-workflows).

AI, LLMs & Agents

AI Agent Core Loop

45

j4flmao/agent-skills

Use when the user asks about the agent loop, ReAct vs plan-and-solve, re-planning, Reflexion, an agent stuck in a loop, max iterations or termination conditions. Produces a loop spec or patch with state, success predicate, caps and no-progress detection. Not for overall agent design (use ai-agent-architectures) or tool schemas (use tool-calling-principles).

AI, LLMs & Agents

Dev Loop Tech Debt Tracker

45

j4flmao/agent-skills

Use when the user asks to track technical debt, build a tech debt register, prioritize debt by interest and cost, measure code health, or set a debt budget per sprint. Produces a debt inventory with scoring and a paydown plan. Not for doing the refactor (use dev-loop-refactor-guide) or quality gates (use qc).

Software Development

Dev Loop Debugging Strategy

45

j4flmao/agent-skills

Use when the user reports a bug, error message, stack trace, crash, memory leak, flaky failure or asks to find the cause or do root cause analysis. Produces a hypothesis-driven debugging plan: reproduce, isolate, bisect, instrument, fix and regression test. Not for speeding up slow code (use dev-loop-performance-profiler).

Software Development

Devops Internal Developer Platform

45

j4flmao/agent-skills

Use when the user asks to build an internal developer portal with Backstage, Backstage plugins, software templates and Scaffolder custom actions, the software catalog entity model, TechDocs, the permission framework, or golden path templates. Produces Backstage implementation designs. Not for platform team strategy and maturity (use devops-platform-engineering).

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.