Claude Code skill automates codebase architecture sweep and files refactor issues
u/MineInternational495 built a Claude Code skill called `ralph-architecture-sweep` that autonomously scans a codebase for architecture-deepening opportunities and files them as self-contained, ready-to-implement issues — without pushing any changes.
Score breakdown
The tool shifts architecture analysis from a manual, abandonment-prone ritual to an automated, delta-aware agent sweep that produces immediately actionable, independently-grabbable refactor tickets without touching the codebase until a human approves.
- 01The skill is invoked with `/ralph-architecture-sweep` and can target a whole repo or a specific subsystem, package, or directory.
- 02It forks a `ralph/*` worktree off the remote default branch to detect already-shipped refactors and avoid re-proposing them (delta-aware).
- 03Analysis runs one sub-agent per area; no code is pushed — the developer reviews all issues before merging or implementing.
u/MineInternational495 describes a repetitive manual workflow they automated: reading through subsystems, applying a "deletion test" (would deleting this module reduce or redistribute complexity?), and writing up refactors as self-contained tickets. The methodology draws on Ousterhout's *A Philosophy of Software Design* and Matt Pocock's improve-codebase-architecture skills. The result is `ralph-architecture-sweep`, a Claude Code skill that drives the `ralph` autonomous loop (`frankbria/ralph-claude-code`) to perform this analysis automatically via the `/ralph-architecture-sweep` command.
One notable design choice: because headless `ralph` only commits at the end of an iteration, a long analysis call that drops would lose all progress.
The skill asks for scope (whole repo or a specific subsystem/package/directory), then forks a `ralph/*` worktree off the remote default branch so it can see already-shipped refactors and avoid re-proposing them — the "delta-aware" design. It then sweeps for architecture-deepening candidates using one sub-agent per area, producing vertical-slice issues (deep module + all call sites repointed + tests at the new interface + old copies deleted) and a per-area PRD under `.scratch/`. One notable design choice: because headless `ralph` only commits at the end of an iteration, a long analysis call that drops would lose all progress. The skill sidesteps this by driving the sweep through short sub-agents, making it robust to dropped calls. Nothing is pushed automatically — the developer reviews issues before merging or implementing, though `ralph` can optionally be chained to implement them. The tool installs via `npx ralph-architecture-sweep` from the project root (or `--global`), is MIT licensed, and uses ADRs as a no-go list to prevent agents from re-proposing already-decided architectural choices.
Key facts
- 01The skill is invoked with `/ralph-architecture-sweep` and can target a whole repo or a specific subsystem, package, or directory.
- 02It forks a `ralph/*` worktree off the remote default branch to detect already-shipped refactors and avoid re-proposing them (delta-aware).
- 03Analysis runs one sub-agent per area; no code is pushed — the developer reviews all issues before merging or implementing.
- 04Each generated issue is a vertical slice: deep module refactor + every call site repointed + tests at the new interface + old copies deleted.
- 05A per-area PRD is written to `.scratch/` alongside each issue.
- 06Short sub-agents are used instead of a single long analysis call to avoid losing work if a call drops, since headless `ralph` only commits at the end of an iteration.
- 07Installs via `npx ralph-architecture-sweep` (or `--global`), MIT licensed; ADRs serve as a no-go list to block re-proposing already-decided architectural choices.
Topics
Summary and scoring are generated automatically from the original article. We always link back to the publisher and never republish images or paywalled content. Last processed Jun 14, 2026 · 09:08 UTC. How this works →