Architecture Map

Measures the real graph. Ranks the five worst problems.

What it does

Loads when it is needed

Your agent loads it when the user wants to understand, onboard onto or improve a codebase's structure. It carries 5 rules and reads a profile.md with your details before it starts, so the output matches your brand and project.

Same prompt, with and without

Map the architecture before a refactor

Prompt · I'm new to this repo and we want to split it up next quarter. Map the real architecture and tell me what to fix first.

Repo: 214 TS files, ~38k lines. Measured import counts (importer -> imported, count of files):
  api/* -> services/orders: 31 files; api/* -> db/client: 27 files (routes query the DB directly)
  services/orders -> services/billing: 9; services/billing -> services/orders: 7 (cycle)
  services/billing -> services/customers: 6; services/customers -> services/billing: 4 (cycle)
  utils/helpers.ts: imported by 88 files, 1,940 lines, 61 exports
  services/orders/index.ts: 2,310 lines, changed in 74 of last 200 commits
  db/client: imported by 52 files across api, services, jobs
  jobs/* -> api/*: 5 files (cron jobs call HTTP route handlers)
  No file in web/ imports from services/ or db/. Tests: 41 files, 0 in services/billing.
Top-level dirs: api, services, db, jobs, utils, web, config.

Profile used: Project: order and payments API; Stack: TypeScript, Express, Stripe, Postgres; Strictness: Standard; Conventions: none beyond eslint

Without the skill

Worked from your numbers only; no code read. The intended layering is probably api -> services -> db, but the imports say otherwise: - 27 api files query the DB directly; `db/client` has 52 importers. - orders, billing and customers form one tangled unit (two cycles). - `services/orders/index.ts` is the hub: 2,310 lines, 31 api importers, changed in 74 of 200 commits. - Jobs call HTTP handlers, so the layering is inverted. - `utils/helpers.ts`: 1,940 lines, 61 exports, 88 importers (41% of files). - `web/` is already clean. `services/billing` has Stripe flows, two cycles and 0 of 41 test files. Fix first, in order: 1. Characterization tests for billing's Stripe-facing paths, before moving anything. 2. Break the two cycles: list the symbols crossing each edge, then invert one direction with an interface, events or lower-level shared types. 3. Make jobs call services, not api (5 files). 4. Ratchet the db leak: ESLint `no-restricted-imports` for `api/* -> db/client`, baseline the 27 offenders, drain as you touch them. 5. Carve up `orders/index.ts` after 1-2. 6. Split `helpers.ts` opportunistically, not in one pass. For next quarter: `web` and a jobs worker can split; orders/billing/customers stay one deployable until the cycles are gone. Caveats: these are file-level counts, so a cycle may be longer than the pairs you measured. `orders/index.ts` may be partly a barrel. Churn doesn't say bug fix or feature. To confirm: `npx madge --circular --extensions ts services/` and `npx depcruise`.

With the skill

Built only from the counts you gave; unmeasured cells are marked n/m with the command to run. Draft `architecture.md`, not saved. Shape: `api/*` calls `services/orders` (31 files), but 27 routes skip the service layer and hit `db/client` (52 importers overall). orders <-> billing (9/7) and billing <-> customers (6/4) are cycles. `jobs/*` call HTTP handlers in `api/*`. `web/` is clean. Top five, scored on blast radius, change cost, risk and fix cost: 1. `services/orders/index.ts` god module, 16. 2,310 lines, 31 importers, changed in 74 of 200 commits (37%). 2. orders/billing/customers cycles, 16. Blocks any split. 3. Routes query the DB directly, 14. 27 files, no seam to move the data layer. 4. `services/billing` has 0 of 41 test files, 14. It's the Stripe money path and sits in two cycles. 5. `utils/helpers.ts`, 12. 1,940 lines, 61 exports, 88 importers. Just below the cut: jobs calling api handlers (about 12), step 8. Plan, each step mergeable alone: 1. Characterization tests for billing, Stripe mocked. Guard: coverage threshold on billing. 2. Repositories behind `db/`; ESLint `no-restricted-imports` on `db/client` in `api/**` with a shrinking allowlist. 3-4. Break billing->customers, then billing->orders. Guard: `madge --circular` in CI. 5. Split `orders/index.ts`, `max-lines` at 2,080, lowered each PR. 6. Split `helpers.ts` behind a re-export shim. 7. Empty the allowlist. 8. Jobs call services. After steps 1-4 the three modules are acyclic and splittable. Splitting earlier just moves the coupling over a network. Rerun with `madge --json` and `git log --name-only` to fill the n/m cells. Start with step 1?

Both answers from the same model (Claude sonnet), 2026-10-17. The one without the skill was written in a separate session that never saw it. Shortened where marked with …

Install

One command, in your project

It detects your agent; add --agent all for every agent.

npx proskills-cli add architecture-map --order <order id from your receipt>

Or copy the skill folder (the one holding SKILL.md) into the directory your agent reads, then restart it or start a new session.

Agent	This project	Every project
Claude Code	.claude/skills/	~/.claude/skills/
Cursor	.agents/skills/ (or .cursor/skills/)	~/.cursor/skills/
Codex	.agents/skills/	~/.agents/skills/
Gemini CLI	.agents/skills/ (or .gemini/skills/)	~/.gemini/skills/

Changelog

What changed

v1.0.0 · 2026-10-17
- First versioned release: Map the real import graph, rank the five costliest problems, fix them in green steps.
- Scanned 100/100 before release.

Keep it current with npx proskills-cli update; your profile.md is never touched. Everyone who bought it gets the update free and an email when it lands.

Same collection

More from Code Review

The scan checks spec compliance, token cost, clarity and security patterns. A clean scan is not a guarantee: static scanners can be evaded. Scan any skill yourself.