Standing Mandates
- NEVER rank by how a file looks. Scan where the history says change happens, and rank by counts. A small
pass-through file nobody touches looks worst and is cheapest to spot; deepening it pays nothing, and it pushes the
hot module the team fights every week down the list.
- NEVER propose an interface, signature, or file split, and never edit code, until the user picks a candidate. A design
for the wrong candidate is the work the user then has to read and discard.
- NEVER re-argue a recorded decision. A candidate that contradicts an ADR appears only with its ADR id and the friction
that justifies reopening it; a refactor an ADR already forbids is not listed.
Goal: every candidate row carries its three counts, the closing tally recounts to the table, and the run stops at the
user's pick.
Architecture Review
Finds where deepening a shallow module would make the next change cheaper — in code that already exists — and
stops at a ranked list. "Shallow" = an interface nearly as complex as what it hides, so callers must know the inside.
Not for a greenfield or from-scratch design (develop:architecture-workflow); layer or dependency-rule review of
a design you hand over (develop:clean-architecture); modelling the domain or its boundaries
(develop:domain-driven-design).
Process
- Scope. The user named a module or pain point → scan that and skip step 2. Otherwise step 2. Which repo,
which window? Missing → default to the repo at hand, 90 days; say so in one line and proceed.
- Hot spots. Run
git log --since="90 days ago" --name-only --format= | sort | uniq -c | sort -rn | head -30 and show the command
with its top rows. Generated files, lockfiles, and vendored paths are dropped, and the drop is named. Churn
spread flat across many files = no hot spot: widen the window once (180 days) and say it was widened; still flat →
report that and stop, do not invent a target.
- Discover decisions (alongside step 2). Look for
docs/adr/, adr/, decisions/, CONTEXT.md, GLOSSARY.md. Read the ones that
touch the hot spots. None found → write "no ADRs or glossary found" and proceed. Name modules in the glossary's
words when one exists.
- Find shallow modules among the hot spots. For each hot file or directory, read it and its callers. Signals: the
interface (exports, parameters, config) is about as large as the body; understanding one concept means hopping
across many small files; logic was extracted for testability while the real bugs sit in how it is called; callers
reach through it to its internals. Apply the deletion test as defined in
develop:clean-architecture — it does not
get restated here. "Complexity reappears across callers" keeps the row; "vanishes" drops it (a pass-through is a
simpler fix, not a deepening).
- Count, then rank. Per candidate, three counts, each re-runnable (run them for all candidates in one batch):
- Commits touching it in the window (
git log --since=… --oneline -- <path> | wc -l)
- Importers/callers (grep; name the command)
- Deletion test result:
reappears in <n> callers or vanishes
Confidence is a function of those counts, not a feeling: high = commits ≥ 10 and callers ≥ 5 and the
complexity reappears; medium = two of the three; low = one. Sort by commits × callers. A count that cannot
be obtained is written [확인 필요: ○○], counts as not met, and the row cannot be high.
- ADR check. Compare each candidate with the ADRs found. Contradiction → keep the row only if the friction is
concrete (cite the commits or callers); tag it
conflicts ADR-<id>.
- Stop. Present the table and ask which candidate to take. After the pick, and only then, proceed to
interface options for that one — this skill ends at the list.
Output Template
## Architecture review — <repo or path>, <window>
Hot spots: `<git log command>` · dropped: <generated/lock paths or none>
Decisions found: <ADR ids / glossary file> | no ADRs or glossary found
| # | Candidate (path) | Commits | Callers | Deletion test | Confidence | ADR |
|---|------------------|---------|---------|---------------|------------|-----|
| 1 | <path> | 14 | 9 | reappears in 9 callers | high | — |
Why #1: <one line, citing its counts — not an adjective>
Dropped after the deletion test: <path — vanishes> ...
<n> hot spots scanned · <k> candidates (<h> high)
Which one do you want to take? (No interface proposal until you pick.)
What Claude Does / What You Do
| Claude |
You |
| Runs the history scan, counts, and the deletion test per candidate |
Name the module or pain point if you already know it |
| Reads ADRs and flags the one id a candidate contradicts |
Say whether an ADR is still binding |
| Ranks by counts and stops at the table |
Pick the candidate; decide whether to proceed |
Related Skills
develop:clean-architecture — owns the deletion test and the dependency rule.
develop:architecture-workflow — no code yet; design from the start.
develop:domain-driven-design — the names or boundaries are what is wrong.
develop:service-boundary-validator — the candidate is a whole service.
1---2name: architecture-review3effort: high4description: >-5 Use when an existing codebase feels hard to change and you want ranked refactor targets from git history, not a redesign. Triggers on: "어디부터 리팩토링할까", "코드가 얽혀서 손대기 힘들어", "where should we refactor this repo".6scenarios:7 - "Our repo is painful to change — find the modules worth deepening first"8 - "Review the architecture of this codebase and rank where refactoring would pay off"9 - "Which files keep changing and are too shallow to test well?"10 - "코드베이스가 너무 얽혀 있어, 어디부터 구조를 손봐야 할지 후보를 뽑아줘"11 - "자주 바뀌는데 테스트하기 어려운 모듈이 뭔지 찾아줘"12compatibility:13 recommended:14 - think-tool15 optional:16 - sequential-thinking17 remote_mcp_note: >-18 think-tool이 있으면 후보마다 삭제 테스트 결과와 ADR 충돌을 따져보는 데 도움이 됩니다.19 Claude 설정 → MCP Servers에서 remote SSE 엔드포인트를 추가하세요.20metadata:21 source: https://skillmd.com/skills/newkayak12/architecture-review22---2324## Standing Mandates2526- NEVER rank by how a file looks. Scan where the history says change happens, and rank by counts. A small27 pass-through file nobody touches looks worst and is cheapest to spot; deepening it pays nothing, and it pushes the28 hot module the team fights every week down the list.29- NEVER propose an interface, signature, or file split, and never edit code, until the user picks a candidate. A design30 for the wrong candidate is the work the user then has to read and discard.31- NEVER re-argue a recorded decision. A candidate that contradicts an ADR appears only with its ADR id and the friction32 that justifies reopening it; a refactor an ADR already forbids is not listed.3334Goal: every candidate row carries its three counts, the closing tally recounts to the table, and the run stops at the35user's pick.3637# Architecture Review3839Finds where deepening a shallow module would make the next change cheaper — in code that already exists — and40stops at a ranked list. "Shallow" = an interface nearly as complex as what it hides, so callers must know the inside.4142**Not for** a greenfield or from-scratch design (`develop:architecture-workflow`); layer or dependency-rule review of43a design you hand over (`develop:clean-architecture`); modelling the domain or its boundaries44(`develop:domain-driven-design`).4546## Process47481. **Scope.** The user named a module or pain point → scan that and skip step 2. Otherwise step 2. Which repo,49 which window? Missing → default to the repo at hand, 90 days; say so in one line and proceed.502. **Hot spots.** Run51 `git log --since="90 days ago" --name-only --format= | sort | uniq -c | sort -rn | head -30` and show the command52 with its top rows. Generated files, lockfiles, and vendored paths are dropped, and the drop is named. Churn53 spread flat across many files = no hot spot: widen the window once (180 days) and say it was widened; still flat →54 report that and stop, do not invent a target.553. **Discover decisions** (alongside step 2). Look for `docs/adr/`, `adr/`, `decisions/`, `CONTEXT.md`, `GLOSSARY.md`. Read the ones that56 touch the hot spots. None found → write "no ADRs or glossary found" and proceed. Name modules in the glossary's57 words when one exists.584. **Find shallow modules among the hot spots.** For each hot file or directory, read it and its callers. Signals: the59 interface (exports, parameters, config) is about as large as the body; understanding one concept means hopping60 across many small files; logic was extracted for testability while the real bugs sit in how it is called; callers61 reach through it to its internals. Apply the deletion test as defined in `develop:clean-architecture` — it does not62 get restated here. "Complexity reappears across callers" keeps the row; "vanishes" drops it (a pass-through is a63 simpler fix, not a deepening).645. **Count, then rank.** Per candidate, three counts, each re-runnable (run them for all candidates in one batch):65 - **Commits** touching it in the window (`git log --since=… --oneline -- <path> | wc -l`)66 - **Importers/callers** (grep; name the command)67 - **Deletion test** result: `reappears in <n> callers` or `vanishes`68 Confidence is a function of those counts, not a feeling: **high** = commits ≥ 10 and callers ≥ 5 and the69 complexity reappears; **medium** = two of the three; **low** = one. Sort by commits × callers. A count that cannot70 be obtained is written `[확인 필요: ○○]`, counts as not met, and the row cannot be high.716. **ADR check.** Compare each candidate with the ADRs found. Contradiction → keep the row only if the friction is72 concrete (cite the commits or callers); tag it `conflicts ADR-<id>`.737. **Stop.** Present the table and ask which candidate to take. After the pick, and only then, proceed to74 interface options for that one — this skill ends at the list.757677## Output Template7879```80## Architecture review — <repo or path>, <window>8182Hot spots: `<git log command>` · dropped: <generated/lock paths or none>83Decisions found: <ADR ids / glossary file> | no ADRs or glossary found8485| # | Candidate (path) | Commits | Callers | Deletion test | Confidence | ADR |86|---|------------------|---------|---------|---------------|------------|-----|87| 1 | <path> | 14 | 9 | reappears in 9 callers | high | — |8889Why #1: <one line, citing its counts — not an adjective>90Dropped after the deletion test: <path — vanishes> ...9192<n> hot spots scanned · <k> candidates (<h> high)9394Which one do you want to take? (No interface proposal until you pick.)95```9697## What Claude Does / What You Do9899| Claude | You |100|--------|-----|101| Runs the history scan, counts, and the deletion test per candidate | Name the module or pain point if you already know it |102| Reads ADRs and flags the one id a candidate contradicts | Say whether an ADR is still binding |103| Ranks by counts and stops at the table | Pick the candidate; decide whether to proceed |104105## Related Skills106107- `develop:clean-architecture` — owns the deletion test and the dependency rule.108- `develop:architecture-workflow` — no code yet; design from the start.109- `develop:domain-driven-design` — the names or boundaries are what is wrong.110- `develop:service-boundary-validator` — the candidate is a whole service.