refinement · ruvnet — Claude Code subagent: what it does, how to install
SPARC refinement phase agent for iterative code polish. Drives test-driven development: creates failing tests, satisfies them, and cleans up structure.
no license ★ 850 updated 2026-10-26
.claude/agents/refinement.mdWhat refinement does
The refinement subagent manages the code polish phase within the SPARC methodology. It guides development through a strict test-driven loop: assembling failing tests for required behavior, writing minimal code to make them pass, and refactoring without regressions.
Built-in lifecycle hooks automate state tracking. The pre-hook logs the active phase to memory and runs npm test --if-present. Once work wraps up, the post-hook re-runs npm test and writes a timestamped record to memory.
Because both hooks execute npm test, the agent expects a configured test runner in the repository.
What it helps with
- create failing unit tests before drafting service logic
- refactor complex classes while keeping test suites green
- tighten error handling and account lock workflows
- trigger automated test suites across iteration stages
Example prompts for the agent
- Run the refinement agent on the auth module using TDD
- Refactor the AuthenticationService class and verify with tests
- Write failing tests for account lockout and implement the fix
How to install refinement
Manually: put the files in place
.claude/agents/refinement.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/refinement.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/refinement.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about refinement
How to install refinement in Claude Code?
Add the subagent definition file to .claude/agents/refinement.md in your project.
What does the refinement subagent do?
It coordinates the SPARC refinement phase, focusing on test-driven iterations, optimization, and safe code refactoring.
What environment setup does refinement need?
The project needs a functional npm test command in package.json, which the pre and post hooks call to verify test status.
Similar subagents
All subagents for Testing and QA →refinement by other authors comes first.