A comprehensive set of AI agents designed to systematically analyze, plan, execute, and report on code refactoring tasks within Claude Code environments.
When using Claude Code for large-scale software development, projects often face rapid architectural complexity growth. Common issues include:
- Code Duplication: Similar logic scattered across multiple files
- Large Files: Monolithic files that are difficult to maintain
- Scattered Functionality: Related features spread across different modules
- Mixed File Types: Test files, documentation, and source code intermingled
- AI-Generated Artifacts: Small tests and documentation files that need consolidation
These issues compound over time, making codebases increasingly difficult to maintain and extend.
This project provides a 4-phase structured approach to code refactoring using specialized Claude Code agents:
- Analyzes codebase health using quantitative metrics
- Identifies code smells and architectural issues
- Provides a 5-tier recommendation system:
- Strongly Recommend - Critical issues requiring immediate attention
- Highly Recommend - Significant issues affecting maintainability
- Recommend - Moderate issues worth addressing
- Can Wait - Minor issues that can be deferred
- Not Needed - Codebase is in good condition
- Creates detailed refactoring strategy based on assessment
- Ensures comprehensive test coverage before refactoring
- Plans step-by-step execution with safety checkpoints
- Prioritizes maintaining functional consistency throughout the process
- Implements refactoring plan with strict adherence to the strategy
- Runs automated tests after each modification step
- Maintains system stability through continuous validation
- Stops immediately if any tests fail
- Generates comprehensive before/after analysis
- Quantifies improvements in code metrics
- Documents consolidated files and removed duplications
- Provides actionable insights for future development
CCRefactorAgents/
├── README.md # This file
├── judgment-agent.md # Phase 1: Code health assessment agent
├── planning-agent.md # Phase 2: Refactoring strategy planning agent
├── execution-agent.md # Phase 3: Safe refactoring execution agent
└── reporting-agent.md # Phase 4: Results analysis and reporting agent
-
Add Agents to Claude Code:
/agents
-
Manual Configuration for Each Agent:
- Select "Manual Configuration"
- Copy the content from the respective
.mdfiles:judgment-agent.mdfor assessmentplanning-agent.mdfor planningexecution-agent.mdfor executionreporting-agent.mdfor reporting
- Paste into the System Prompt field
- Tool Selection: Select ALL available tools for maximum effectiveness
- Assessment & Planning: Use Claude Opus for deeper analysis and strategic thinking
- Execution & Reporting: Use Claude Sonnet for efficient implementation and documentation
- All Phases: Use Claude Sonnet for balanced performance and cost
- Alternative: Use Gemini CLI for assessment and planning phases
Copy the agent prompts directly into your Claude Code session when needed:
# Assessment Phase - paste judgment-agent.md content
# Planning Phase - paste planning-agent.md content
# Execution Phase - paste execution-agent.md content
# Reporting Phase - paste reporting-agent.md contentEach agent is designed to be used sequentially within Claude Code:
# Use the judgment-agent.md prompt with your codebase
# Input: Your entire codebase
# Output: Health assessment with 5-tier recommendation# Use the planning-agent.md prompt if refactoring is recommended
# Input: Assessment report + codebase
# Output: Detailed refactoring plan with test requirements# Use the execution-agent.md prompt after plan approval
# Input: Refactoring plan + codebase + test runner
# Output: Step-by-step execution with test validation# Use the reporting-agent.md prompt after successful execution
# Input: Before/after codebase snapshots + initial assessment
# Output: Quantified improvement report- Safety-First Approach: Every refactoring step includes test validation
- Quantitative Analysis: Data-driven decisions based on concrete metrics
- Incremental Progress: Small, verifiable steps prevent system breakage
- Comprehensive Documentation: Clear planning and reporting for accountability
- Claude Code Optimized: Designed specifically for Claude Code workflows
The agents monitor and improve:
- Code duplication percentage
- Average file length
- Function complexity
- Module cohesion
- Test coverage
- Documentation consolidation
- File organization
This is an open-source project. Contributions are welcome through:
- Bug reports and feature requests
- Agent prompt improvements
- Additional metrics and analysis capabilities
- Documentation enhancements
MIT License - Feel free to use, modify, and distribute these agents for your projects.
Each agent follows a structured prompt format with:
- Role Definition: Clear agent responsibility
- Task Context: Background and objectives
- Input/Output Specifications: Defined data formats
- Rules and Constraints: Safety and quality guidelines
- Step-by-Step Thinking: Logical processing flow
- Example Interactions: Usage demonstrations
This systematic approach ensures consistent, reliable refactoring outcomes across different codebases and project types.