Architecture Survey
Ranks module-level deepening candidates such as shallow modules and wrong seams.
Install
npx skills add Yeachan-Heo/oh-my-claudecode --skill architecture-survey -g -a claude-code -y- Repository
- Yeachan-Heo/oh-my-claudecode40.5k
- Category
- Engineering
- Updated
- 3d ago
- License
- MIT
- Context cost
- Lightabout 1,186 tokens
- Runs scripts
- No, instructions only
What it does
Periodic architecture survey, walks the module graph and reports ranked deepening candidates (shallow modules, hypothetical seams, logic behind the wrong seam). Survey, not rescue: it finds candidates and hands them to the captain; it never refactors on its own.
A surveyor charts the reef; the captain decides whether to dredge. The survey reads the water, reports what it found with evidence, and stops. It is the maintenance twin of the loft: where the loft answers one design question before building, the survey answers "where is this repo getting harder to change, and what would deepen it" after building.
When to survey
- Periodically, every few days of active building, or after a batch of tickets lands.
- Out of turn, when the repo starts feeling harder to change than it was last week: edits touching more files than they should, interfaces growing to satisfy one caller, tests that must be updated in lockstep for unrelated reasons.
Optional argument narrows the survey to a directory or area; with no argument, survey the whole repo.
The survey
- Read the repo's architecture principles (CLAUDE.md, ADRs) and the seeded seam vocabulary in
docs/standards/architecture.md, the definitions of seam and deep module. - Walk the module graph of the target area, and when no direction was given, weight the walk toward the yard's busy water: read a good stretch of the commit history first and let the areas that keep coming up pull the survey, because deepening pays off where future edits will land. A scattered history with no hot spot widens the net.
- Look for three finding classes:
- Shallow modules, wide interface, thin behavior; callers know more than the module hides.
- Hypothetical seams, a boundary crossed by exactly one adapter with no second caller; checkable by counting callers.
- Logic behind the wrong seam, behavior living on the far side of a boundary that does not own its data.
Apply the demolition test to every suspect: if the module were removed, would its complexity vanish (a pass-through wearing a uniform) or reappear across its callers (load-bearing)? Only load-bearing shallowness is a finding.
