Refactoring Agent Systems Skill

Refactoring Agent Systems

Overview

Refactoring agent systems IS applying clean code principles to agent configurations.

Re-analyze after changes, compare before/after, fix remaining issues, simplify over-engineering.

Core principle: Refactoring without measurement is guessing. Analyze, then change, then verify.

Routing

Pattern: Skill Steps Handoff: none Next: none Chain: main (terminal)

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

Load review findings
Prioritize issues
Execute refactoring
Final verification
Produce refactoring report
Archive pipeline documents

Announce: "Created 6 tasks. Starting execution..."

Task 1: Load Review Findings

Goal: Load the review report as the basis for refactoring.

If review report path was provided (from reviewing-agent-systems):

Read the review report
Extract all Critical and Major issues
These are your refactoring targets

If no review report (standalone invocation):

Invoke reviewing-agent-systems skill first to produce a report
Then continue with the report's findings

Verification: Have a list of specific issues to fix from the review report.

Task 2: Prioritize Issues

Goal: Classify and order issues from the review report for fixing.

Priority order:

Critical — must fix before shipping
Major — should fix for quality
Minor — nice to have, fix if time permits

Present the prioritized list to user. Do NOT summarize — show each issue with its component, severity, and planned fix.

Ask: "這些修正項目正確嗎？要開始修正嗎？"

Verification: User has confirmed the prioritized fix list.

Task 3: Execute Refactoring

Goal: Fix remaining and new issues.

Refactoring actions (in priority order):

| Issue Type | Action | Method | |------------|--------|--------| | Duplicate logic across components | Merge or extract to rule | Main conversation edits | | Conflicting instructions | Unify or remove one | Main conversation edits | | Over-engineered component | Simplify (YAGNI) | Main conversation edits | | Weak skill trigger | Improve description | Main conversation edits | | Missing isolation | Add context: fork to agent | Main conversation edits | | CLAUDE.md too long | Move content to rules/skills | Main conversation edits | | Skill missing asset | Add scripts/, templates/, or references/ | Create directly — no user confirmation needed |

Important: All edits happen in main conversation. Never delegate refactoring writes to subagents.

For each refactoring action:

Identify the specific change
Make the edit
Verify the fix resolves the issue
Move to next action

Verification: All REMAINING and NEW issues addressed.

Task 4: Final Verification

Goal: Confirm no critical issues remain.

Re-run the relevant reviewer agents on components that were modified in Task 3.

Pass criteria:

Zero CRITICAL issues from any reviewer
All Major issues from the original review are resolved
No new issues introduced by refactoring

If critical issues remain: Return to Task 3 and fix.

Verification: All modified components pass their reviewer.

Task 5: Produce Refactoring Report

Goal: Document what was changed and why.

Write to: .rcc/{timestamp}-refactoring-report.md

Report format:

# Agent System Refactoring Report

**Date:** YYYY-MM-DD HH:MM

## Changes Made

| # | Component | Change | Rationale |
|---|-----------|--------|-----------|

## Before/After Comparison

| Metric | Before | After |
|--------|--------|-------|
| Components | N | N |
| Critical issues | N | 0 |
| Warnings | N | N |
| Total lines (CLAUDE.md) | N | N |

## Remaining Items (INFO)

- [Low priority items for future consideration]

Verification: Report accurately reflects all changes.

Task 6: Archive Pipeline Documents

Goal: Move all pipeline documents from the current run to the archive.

Steps:

Create archive directory: .rcc/archive/{YYYY-MM-DD}/
Move ALL *.md files from .rcc/ to the archive directory (excluding the archive/ directory itself)
Commit the archive move

mkdir -p .rcc/archive/{YYYY-MM-DD}
mv .rcc/*.md .rcc/archive/{YYYY-MM-DD}/
git add .rcc/
git commit -m "chore: archive pipeline documents from {YYYY-MM-DD}"

Replace {YYYY-MM-DD} with today's actual date.

If no documents exist in .rcc/: Skip this task (nothing to archive).

Verification: .rcc/ contains only the archive/ directory. All pipeline documents are in the dated archive subdirectory.

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

"Skip re-analysis, I just built this"
"No need to compare, everything is new"
"Use a subagent to make the edits"
"Skip final verification, I just fixed it"
"The report is busywork"
"Skip archiving, the docs aren't hurting anything"

All of these mean: You're about to leave mess behind. Follow the process.

Common Rationalizations

| Excuse | Reality | |--------|---------| | "Skip re-analysis" | Building introduces new issues. Always re-analyze. | | "Skip comparison" | Without before/after, you can't prove improvement. | | "Subagent edits" | Subagents can't write to .claude/. Use main conversation. | | "Skip verification" | Refactoring can break things. Verify. | | "Skip report" | Report documents decisions for future maintainers. | | "Skip archiving" | Accumulated documents confuse future pipeline runs. Archive. |

Agent Skills: Refactoring Agent Systems

Install this agent skill to your local

Skill Files