Skip to content
Get packs

Architecture Survey

Finds and ranks code modules that are hard to change, without editing anything.

Source Download skill
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”
Step-by-step guide: how to use Architecture SurveyInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    architecture-survey.zip
  2. 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. 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.