Architecture Survey
Finds and ranks code modules that are hard to change, without editing anything.
- Repository
- Yeachan-Heo/oh-my-claudecode
- Stars
- 40,512
- Licence
- MIT
- Files
- 1 file
What it does
When invoked, the agent walks a codebase's module structure (optionally limited to one folder) and looks for three kinds of design trouble: shallow modules with wide interfaces and thin behavior, boundaries with only one real user, and logic sitting on the wrong side of a boundary. It produces a ranked written report with file-level evidence, a suggested fix for each candidate, and a risk note, then recommends the one change to make first. It is explicitly report-only: it does not refactor or modify files.
Great for
- Teams doing periodic maintenance on a codebase that feels harder to change over time
- Developers who want a prioritized list of structural refactoring candidates before planning work
- Tech leads reviewing a repo after a batch of feature tickets has landed
Skip it if
- Projects that need automated enforcement or pass/fail checks, since the skill itself says its findings are heuristic, low-confidence judgments (the mechanical checks belong to a separate audit tool)
- Anyone expecting the agent to fix or refactor code automatically, since the skill forbids edits by design
- Repos without the surrounding conventions it assumes (CLAUDE.md, ADRs, docs/standards/architecture.md, a commit history); the reasoning becomes weaker without them
Try asking
- “Survey the whole repo for modules that are hard to change and rank them by leverage against risk”
- “Survey only the src/payments directory for shallow modules and hypothetical seams”
- “Run an architecture survey now that this week's tickets have landed, and tell me the top recommendation”
- “Take the top survey candidate and walk me through a design interview on what deepening it would involve”
Install in 3 steps
- 1
Download the skill
The ZIP contains the 1 original files, the MIT licence and an attribution note.
architecture-survey.zip - 2
Add it to your agent
Claude Code (all projects)
mkdir -p ~/.claude/skills && unzip architecture-survey.zip -d ~/.claude/skills/Claude Code / Agent SDK (this project only)
mkdir -p .claude/skills && unzip architecture-survey.zip -d .claude/skills/Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.
- 3
Ask for the task
No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.
Get better results
- Give it a directory or area as the argument for a faster, focused survey instead of the whole repo
- Review the candidates yourself before acting; the findings are judgment calls the skill itself rates as low confidence
- If you decide to act on a finding, ask for the design interview in the same session while the evidence is fresh
What's inside
- SKILL.md
Redistributed unmodified from Yeachan-Heo/oh-my-claudecode under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.