Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

arch-review

/arch-review

Zleca świeży przegląd architektury kodu TypeScript modelowi bez kontekstu, a potem sprawdza jego uwagi w kodzie przed raportowaniem.

Repozytorium
dotfiles ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
3
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 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. 1. Build the digest
  2. 2. Write the prompt
  3. 3. Run it
  4. 4. Verify, then report
  5. Structure metrics
Sekcje z nagłówków SKILL.md, w oryginale · 170 linii, 1 359 słów
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

RepozytoriumWynikLicencja
Ta strona · david-crespo/dotfiles100MIT
ramboz/jig100MIT
ramboz/jig100MIT
ramboz/jig100MIT
andreibesleaga/gabbe100CC-BY-4.0
omexit/claude-skills-pack100MIT
axisrobo/ea-harness100MIT
sean-sunagaku/claude-code-plugin100MIT
babyworm/rtl-agent-team92MIT

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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.