Refactor structure - split god objects, break circular deps, improve separation of concerns
Refactors codebase architecture by splitting god objects, breaking circular dependencies, and improving separation of concerns.
/plugin marketplace add Shavakan/claude-marketplace/plugin install shavakan-commands@shavakanImprove code structure: split god objects, break circular dependencies, improve separation of concerns.
Safety requirements:
Run prerequisite check:
# Get the plugin root (where scripts are located)
PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
# Validate plugin root is under home directory
if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
echo "ERROR: Invalid plugin root path"
exit 1
fi
# Run prerequisites check and source output
PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
if [[ ! -f "$PREREQ_SCRIPT" ]]; then
echo "ERROR: Prerequisites script not found at $PREREQ_SCRIPT"
exit 1
fi
# Capture output to temp file and source it
PREREQ_OUTPUT=$(mktemp)
if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
source "$PREREQ_OUTPUT"
rm "$PREREQ_OUTPUT"
else
cat "$PREREQ_OUTPUT"
rm "$PREREQ_OUTPUT"
exit 1
fi
This exports: TEST_CMD, BACKUP_BRANCH, LOG_FILE
$ARGUMENTS
Identify and fix architecture issues that make code hard to maintain: god objects, circular dependencies, poor layer separation, high complexity, and long parameter lists.
God objects - Files >300 lines or classes with too many responsibilities (detect via file size, import count, mixed concerns)
Circular dependencies - Module A imports B, B imports A (creates tight coupling, import errors)
Poor separation - Files mixing layers (controller + service + repository in one file, UI with business logic)
High complexity - Functions with cyclomatic complexity >10, deeply nested conditionals, >50 lines
Long parameter lists - Functions with 5+ parameters (should use options objects)
Scan codebase for architecture smells using appropriate analysis tools for the language. For each issue found:
Present findings with prioritization:
Gate: User must review full audit before proceeding.
Present audit findings with impact assessment:
Refactor architecture issues?
□ Safest - Extract complex functions + convert long param lists
□ Low risk - Split god objects by domain boundaries
□ Medium risk - Break circular deps + separate mixed layers
□ High risk - Major architectural refactoring
□ Custom - Select specific issues
□ Cancel
Gate: Get user approval on which issues and risk level to address.
For each approved issue:
Split god objects:
Break circular dependencies:
Separate layers:
Reduce complexity:
Simplify parameters:
Critical: Each refactoring must preserve exact behavior. Tests must pass. If tests fail, rollback and investigate the difference.
Gate: Tests must pass before moving to next refactoring.
Summarize improvements: god objects split (N → M files), circular deps broken (N cycles eliminated), complexity reduced (N functions simplified), maintainability impact.
Delete the backup branch after successful completion:
git branch -D "$BACKUP_BRANCH"
Extract cohesive responsibilities into focused modules:
// Before: UserService (847 lines, does everything)
class UserService {
authenticate() { }
updateProfile() { }
sendNotification() { }
}
// After: Split by domain
class AuthService { authenticate() { } }
class ProfileService { updateProfile() { } }
class NotificationService { sendNotification() { } }
Extract shared types or introduce interfaces:
// Before: User imports Post, Post imports User
// Create shared type
interface UserSummary { id: string; name: string; }
// User can import Post (full)
// Post only imports UserSummary (breaks cycle)
Controller → Service → Repository:
// Before: Everything in one function
async function createOrder(req, res) {
if (!req.body.items) return res.status(400).send();
const total = calculateTotal(req.body.items);
const order = await db.orders.create({...});
res.json(order);
}
// After: Proper layering
// Controller: HTTP handling only
// Service: Business logic
// Repository: Database access
CRITICAL:
If tests fail: Rollback immediately, identify the specific change that broke behavior, understand why it's different from original.
Review with code-reviewer agent before pushing:
Use shavakan-agents:code-reviewer to verify refactorings don't introduce issues.
/shavakan-commands:cleanup - Full repository audit/shavakan-commands:cleanup-dead-code - Remove unused code/shavakan-commands:cleanup-duplication - Remove code duplication