arch-review
/arch-review
Zleca świeży przegląd architektury kodu TypeScript modelowi bez kontekstu, a potem sprawdza jego uwagi w kodzie przed raportowaniem.
- Autor
- david-crespo ↗
- Repozytorium
- dotfiles ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 12.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 6
- Skrypty
- 3
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: digest.sh, imports.mjs, metrics.mjs
Co robi i kiedy
Zleca świeży przegląd architektury kodu TypeScript modelowi bez kontekstu, a potem sprawdza jego uwagi w kodzie przed raportowaniem.
Oryginalny opis (EN)
Get a context-free architecture review of a TypeScript codebase: build a digest of every file's size, leading comment and exported declarations, give it to a bare Opus `claude -p` with no tools and no project or planning context, then check its findings against the code before reporting. Also measures structure (dependency graph, function sizes, single-use helpers) across revisions. Use when the user wants a fresh or outside read on a codebase's architecture or data model, for example after a big refactor, or to check whether a refactor or a reviewer's suggestion made the structure better or w
Jak działa
- 1. Build the digest
- 2. Write the prompt
- 3. Run it
- 4. Verify, then report
- Structure metrics
Podgląd SKILL.md
---
name: arch-review
description: "Get a context-free architecture review of a TypeScript codebase: build a digest of every file's size, leading comment and exported declarations, give it to a bare Opus `claude -p` with no tools and no project or planning context, then check its findings against the code before reporting. Also measures structure (dependency graph, function sizes, single-use helpers) across revisions. Use when the user wants a fresh or outside read on a codebase's architecture or data model, for example after a big refactor, or to check whether a refactor or a reviewer's suggestion made the structure better or worse."
---
# Context-free architecture review
The reviewer sees only the code's structure: what each file is called, how
big it is, what its header comment says it does, what it imports, and what
it exports. It
gets no tools, no plans, no notes and no history, so it judges the code as
it reads to a newcomer. That makes it good at finding where the types, names
and comments describe a different system from the one that runs. It can't
see function bodies, so verify its claims before relaying them.
## 1. Build the digest
From the repo root:
```
~/.claude/skills/arch-review/digest.sh [--cli <command>] [--exclude <regex>] [--full <file>]... <scratchpad>/digest.md
```
- `--cli` adds the command's `--help` and each subcommand's (Commander-style
help). Pass it when the repo is a CLI, since the command tree is part of
the model.
- `--exclude` drops paths matching a regex, such as generated code or
helper scripts outside the app. `scripts/` and `*.config.*` files are
already left out.
- `--full` (repeatable) shows a file's whole source instead of its
declarations. Use it for the few files the focus question is about,
such as the composition root or the class that owns the model, so the
reviewer reads their bodies rather than guessing at them. The whole
non-test source of a ~10k line repo is around 360 KB, so a handful of
full files costs little.
- Each file lists the repo files it imports (found by a text scan in
`imports.mjs`, including type-only and dynamic imports), and a section
above the files counts imports between top-level directories, so the
reviewer can see which way dependencies run.
- It includes AGENTS.md, CLAUDE.md and README.md when they're under 20 KB.
It leaves out `.claude/`, which is where planning notes live.
- It prints the digest's size and any file with exports but no
declarations. Fix those gaps before sending: the reviewer will say it
couldn't see them, and its findings about them will be guesses. A ~10k
line repo comes to about 105 KB, which fits easily.
Skim the digest before sending it.
## 2. Write the prompt
Fill in `prompt.md` from this skill's directory and write it to the
scratchpad with the digest appended:
- `{{name}}`, `{{size}}`: the repo name and its line count (`tokei`).
- `{{context}}`: only facts a newcomer would need to judge it fairly, such
as "It's a personal tool with one user, in a private repo." Leave out
your own conclusions, the plan, and what was just changed. The point is
a read without them.
- `{{cli_line}}`: "the CLI's help text, " when you passed `--cli`; empty
otherwise.
- `{{focus}}`: what the user wants judged most, for example "the data
model: the types in core/model.ts and how the rest of the code is
organized around them".
Drop the CLI question when there's no CLI. Add questions the user asks for,
but keep the instructions to number the findings, say what's inferred, and
skip nits.
## 3. Run it
Run it from an empty directory, so no project CLAUDE.md loads. Use the
Bash tool with `allowed_domains: ["api.anthropic.com"]` and
`run_in_background: true`. It takes a few minutes.
```bash
cd "$(mktemp -d)" && claude -p --model opus --tools "" \
--system-prompt "You are a senior software engineer reviewing the architecture of a codebase from a structural digest. You have no other context about the project or its history." \
--setting-sources "" --strict-mcp-config < <scratchpad>/review-prompt.txt > <scratchpad>/review.md
```
## 4. Verify, then report
Check each finding against the code before passing it on. In the first run,
most findings held, and the misses followed patterns:
- **Stale wording in the code misleads it.** The reviewer will take
comments and names at their word. When a finding rests on a comment
that's out of date (a model comment still describing an operation by
its old name), the user may tell you the finding is wrong. The real fix
is then the comment or name, so the next reader isn't misled either.
- **"Could cause a bug" claims are guesses about bodies.** It flagged two
workspace-root helpers that could disagree. One turned out to be used
only for an error hint. Find the call sites before repeating a claim
like that.
- **Gaps in the digest show up as inferred findings.** If it says a file
had no declarations, fix the digest and consider running it again.
Before relaying a finding that proposes moving code, measure it (below).
Reviewers agree on moves that read well in the digest but make the graph
worse.
Report findings in the reviewer's order, numbered, each marked confirmed,
partly right or wrong, with the file reference. Then give your own view on
what to do first. Save the review next to the repo's notes
(`.claude/notes/<YYYY-MM-DD>-arch-review.md`) with the digest command used,
so a later run can be compared against it. The review has more than a
couple of numbered findings, so offer to put them in a tracker (the tracker
skill).
## Structure metrics
`metrics.mjs` measures a repo's structure, one column per revision, so a
refactor or a proposed move can be judged by more than how it reads. Run it
from the repo root:
```
node ~/.claude/skills/arch-review/metrics.mjs [--exclude <regex>] [--list] [<rev>...]
```
With no revs it measures the working copy. Revs are jj revsets for single
commits (git revs in a plain git repo), including hidden ones by commit ID,
so an abandoned attempt or an earlier state from `jj evolog` can go in a
column. To measure a commit against its parent, pass `<rev>- <rev>`. `--list` prints the last
column's single-use helpers. Exclude e2e harnesses, mocks and generated code
the same way as for the digest.
What the rows mean:
- **Dependency graph**, from `imports.mjs`, type-only imports included.
- ACD is the average number of files each file depends on, itself
included.
- NCCD is the total of that over all files, divided by the total for a
balanced binary tree of the same size (Lakos), so 1 is a tree's
coupling and higher is more coupled.
- Propagation cost is that same total over n²: the share of the code a
change in one file can reach.
- Redundant edges are imports a longer path already implies.
- "Edges toward less stable files" counts imports of a file that itself
depends on more than it's depended on (Martin's stable dependencies
principle).
- **Functions**, from `functions.yml`: declarations, methods, and functions
assigned to a variable, not inline callbacks.
- **Single-use helpers**: non-exported functions or private methods called
once in their file, not counting React components. This is the row that
tracks splitting code into many small pieces. The share of short
functions doesn't, since most short functions are ordinary methods and
path helpers.
Compare columns of the same repo; no threshold means anything on its own.
The numbers can be gamed (merging files cuts edges), so use them to check a
judgment, not to make one. Each single-use helper still has to earn its name.
How the rows behaved when checked against refactors the user had already
judged:
- A move that two outside reviewers agreed on, and that the user rejected,
made every graph row worse: a longer import chain, higher ACD, more
redundant edges, one more edge toward a less stable file.
- Splitting one long function into six single-use helpers raised the
single-use count by four. The two-function split the user preferred
brought it below where it started.
- Across several dozen of the user's cleanup commits in a larger repo, lines
went down in about three quarters and named functions more often than
not. Single-use helpers mostly went down. The graph rows rarely moved,
since most cleanups stay inside a file, and when they did, they usually
improved.
- Pulling code out into its own file usually reads as slightly worse on the
graph (one more file, a few more edges), even when the user considered it
an improvement. Judge those on readability instead.
So in a cleanup the user likes, the code usually gets shorter, has fewer
functions, and the graph doesn't get worse. A change that adds lines and
single-use helpers while calling itself a cleanup is worth questioning.
Pliki w paczce (6)
- SKILL.md 9 KB
- digest.sh 5 KB
- functions.yml 1 KB
- imports.mjs 3 KB
- metrics.mjs 10 KB
- prompt.md 1 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · david-crespo/dotfiles | 100 | MIT |
| ramboz/jig | 100 | MIT |
| ramboz/jig | 100 | MIT |
| ramboz/jig | 100 | MIT |
| andreibesleaga/gabbe | 100 | CC-BY-4.0 |
| omexit/claude-skills-pack | 100 | MIT |
| axisrobo/ea-harness | 100 | MIT |
| sean-sunagaku/claude-code-plugin | 100 | MIT |
| babyworm/rtl-agent-team | 92 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 72820dfcabbe (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100arch-export
Przygotowuje oczyszczony opis architektury do przekazania zewnętrznemu modelowi, który nie ma dostępu do repozytorium. - 85arch-check
Sprawdza kod funkcji pod kątem reguł architektury z karty projektu: warstwy zależności, cykle, zakazane wzorce i rozmiar plików. - 100peer-review
Zleca niezależny przegląd zmian w kodzie podagentowi code-reviewer tylko do odczytu, a potem klasyfikuje uwagi i poprawia je przed otwarciem pull requesta. - 100arch-index
Buduje i waliduje plik .arch/index.json, czyli mapę komponentów architektury na katalogi i pliki przypięte do commita, oraz wykrywa dryf strukturalny kodu. - 100structure-review
Przegląda i porządkuje strukturę istniejącego kodu, zwłaszcza wygenerowanego przez AI, przed scaleniem dużej zmiany. - 100arch-tutor
Czyta repozytorium i tłumaczy właścicielowi jego architekturę: mapę warstw, ścieżkę jednego żądania, zadania w tle i wdrożenie.