Software architecture skill: 10 reviews Claude can run

The prompt

Read `src/lib/utils.ts` and `src/lib/helpers.ts`. For each exported function, decide which bounded context it really belongs to and propose a domain-specific home — never a generic `utils`/`helpers`/`common` name. Return a table: current function → proposed module (e.g. `pricing/OrderCalculator.ts`) → one-line reason. Flag any function that does two unrelated things and should be split. Do not rename anything yet; give me the move plan first.

What slides.md looks like

# Move plan — src/lib/utils.ts (14 functions)

  calcTax, applyDiscount, roundCurrency
    → pricing/OrderCalculator.ts        (all touch order totals)
  formatInvoiceNo, invoiceDueDate
    → billing/InvoiceFormatter.ts       (invoice-shaped, not generic)
  slugify
    → keep in text/Slug.ts              (cross-cutting, genuinely shared)
  parseAndEmail   ⚠ SPLIT
    → parsing/CsvRowParser.ts  +  notifications/Mailer.ts
      (one function doing two jobs — parse, then send)

Pairs with

The prompt

Here is the spec for a checkout service (`docs/checkout-spec.md`). Apply DDD: identify the bounded contexts, assign each domain entity to one context, and name the contexts with the team's ubiquitous language — not technical layers. For each context list its core entities and the one public operation other contexts call. Return it as a directory tree under `src/` with one folder per context. Keep domain logic out of any infrastructure folder.

What slides.md looks like

src/
  ordering/            # context: "placing an order"
    Order.ts  Cart.ts  PlaceOrder.ts        ← use case
    ports/ PaymentGateway.ts (interface)
  pricing/             # context: "what it costs"
    PriceList.ts  OrderCalculator.ts
  fulfilment/          # context: "getting it shipped"
    Shipment.ts  DispatchOrder.ts
  shared-kernel/
    Money.ts  CustomerId.ts                 ← value objects only
# infra adapters live in src/infrastructure/, never inside a context

Pairs with

The prompt

We are 4 engineers, deploying twice a week, ~200 req/s peak, one Postgres, no platform team. A stakeholder wants microservices. Argue the trade-off against THESE constraints: operational overhead, transaction boundaries, team cognitive load, and time-to-first-revenue. Recommend one of: monolith, modular monolith, or microservices — and say what would have to change for the answer to flip. Be specific; do not give a both-sides non-answer.

What slides.md looks like

Recommendation: modular monolith.

Why, against your constraints
  • 4 engineers, no platform team → microservices' ops tax (CI per
    service, distributed tracing, network failure modes) buys you
    nothing yet. It's a part-time SRE you don't have.
  • One Postgres + real money → keep transactions in-process; a
    saga across services to avoid a single COMMIT is pure downside.
  • Module boundaries (per ctx, use case 2) give you 80% of the
    decoupling with 0% of the network.

Flip the call when: a context needs independent scaling (e.g.
search at 10x the rest), OR headcount passes ~15 with >3 teams.

Pairs with

The prompt

Review `src/routes/orders.ts`. Apply the separation-of-concerns rules: no database queries in controllers, no business logic mixed into the HTTP layer, framework code out of the domain. List each violation with file:line, classify it (persistence / business-rule / framework-leak), and give the one-line fix — which layer the code should move to. Order findings worst-first. Keep the controller as a thin orchestrator.

What slides.md looks like

orders.ts — 3 violations

✗ business-rule  L41  discount math inlined in the POST handler
    → move to pricing/OrderCalculator.applyDiscount()
✗ persistence    L58  raw `db.query('SELECT … orders')` in route
    → move behind orders/ports/OrderRepository (interface)
✗ framework-leak L72  domain Order imports `express` Request type
    → pass a plain DTO into the use case; keep express at the edge

After: the handler is 9 lines — parse, call PlaceOrder, map result.

Pairs with

The prompt

We are about to write a custom retry wrapper, a custom form validator, and our own auth session store. For each, apply the library-first rule: name the established library that solves it (the skill cites `cockatiel` for retries as the canonical example), and state the one condition under which writing it ourselves is justified. If custom is the right call, say why in one line — security control, unique business logic, or dependency overkill.

What slides.md looks like

Library-first verdicts

retry wrapper   → use cockatiel (policies: retry, circuit-breaker,
                  timeout). Custom only if you need a backoff curve
                  the lib can't express — you don't.
form validation → use zod / valibot. Schema is data; hand-rolled
                  validators rot into a second source of truth.
auth sessions   → use the framework's session + Auth0/Supabase.
                  Custom ONLY if a compliance control forces full
                  control of token storage. Default: don't.

Rule of thumb: every line of custom code is a liability you must
test, document, and maintain. Borrow before you build.

Pairs with

The prompt

Apply the code-quality rules to `src/billing/processInvoice.ts`: flag every function over ~50 lines, any nesting deeper than 3 levels, and the file itself if it's over 200 lines. For each, propose the fix — early-return guard clauses to kill the arrow-of-doom, and extractions into smaller functions with domain names (no `helper2`). If the file is too big, propose the split into multiple files. Show the before/after shape of the worst offender.

What slides.md looks like

processInvoice.ts — 312 lines, splits into 3

worst offender: validateAndCharge() — 71 lines, 5-deep nesting
  fix: invert the pyramid with guard clauses

  // before                      // after
  if (inv) {                     if (!inv) return err('no invoice')
    if (inv.lines) {             if (!inv.lines.length) return err('empty')
      if (paid) { … }            if (!paid) return err('unpaid')
    }                            return charge(inv)   // happy path, flat
  }

split: → InvoiceValidator.ts · InvoiceCharger.ts · processInvoice.ts

Pairs with

The prompt

Turn these notes into an ADR. We debated event-driven vs. direct calls between the ordering and fulfilment contexts. Notes: `docs/meeting-2026-06.md`. Use the standard ADR shape — Context, Options considered (with the trade-off for each), Decision, Consequences (good and bad). Ground the reasoning in our actual constraints from the notes; don't invent a rationale we didn't discuss. Keep it under one page.

What slides.md looks like

# ADR-014: Ordering → Fulfilment integration

## Context
Order placement must trigger dispatch. Contexts deploy together
today (modular monolith, ADR-009).

## Options
1. Direct call PlaceOrder → DispatchOrder
     + simplest, in-process transaction
     − couples the two contexts at compile time
2. Domain event OrderPlaced, fulfilment subscribes
     + contexts stay decoupled; ready to split later
     − eventual consistency; needs an outbox for reliability

## Decision
Domain event via an in-process bus + transactional outbox.

## Consequences
+ Splitting fulfilment to its own service later is a config change.
− We accept eventual consistency on dispatch; surface it in the UI.

Pairs with

The prompt

Review this PR diff for the anti-patterns the architecture skill calls out: NIH syndrome (custom auth/state/validation where a standard library exists), generic-naming dumping grounds (`utils`, `helpers`, `common`, `shared`), and separation-of-concerns breaks (DB queries in controllers, business logic in UI components). For each hit, name the anti-pattern, the file:line, and the standard alternative. Skip style nits — only structural smells.

What slides.md looks like

PR #218 — 3 architectural smells

⚠ NIH            auth/session.ts  — hand-rolled JWT refresh
                 → use the framework session or Auth0; this is the
                   exact case the skill warns against owning.
⚠ generic-naming common/shared.ts — 9 unrelated exports added
                 → split by domain; "shared" hides coupling.
⚠ concern-leak   CartView.tsx L88 — tax calc inside the component
                 → move to pricing/; UI renders, it doesn't compute.

No correctness bugs found — these are design-debt flags.

Pairs with

The prompt

Apply the error-handling rules to `src/payments/charge.ts`. Find every bare `catch` that swallows or re-throws raw, every place a third-party error leaks past the domain boundary, and any failure with no typed result. Propose typed catch blocks and a domain error type (e.g. `PaymentDeclined`, `GatewayUnavailable`) so callers branch on meaning, not on string matching. Keep the happy path readable; don't drown it in try/catch.

What slides.md looks like

charge.ts — error-handling fixes

✗ L23  catch (e) { console.log(e) }   ← swallowed, charge looks ok
   → rethrow as GatewayUnavailable; let PlaceOrder decide retry
✗ L40  Stripe.CardError leaks to the HTTP layer
   → map at the adapter: CardError → PaymentDeclined(reason)
✗ no Result type — callers can't tell decline from outage

type ChargeError = PaymentDeclined | GatewayUnavailable
async function charge(o: Order): Promise<Result<Receipt, ChargeError>>

Pairs with

The prompt

Draft a short architecture-gate checklist I can drop in CLAUDE.md so the agent self-reviews before proposing a merge. Base it on the software-architecture skill: (1) no DB queries in controllers, (2) no new `utils/helpers/common/shared` files, (3) no custom code where an established library exists, (4) functions under ~50 lines, files under ~200, nesting under 3, (5) domain-named modules only. Phrase each as a yes/no the agent answers with file:line evidence.

What slides.md looks like

## Architecture gate (run before proposing a merge)

For this branch, answer each with evidence or "n/a":
  [ ] Any DB query added inside a controller?            (file:line)
  [ ] Any new utils/helpers/common/shared file?          (file:line)
  [ ] Any custom code a known library covers?            (which lib?)
  [ ] Any function > ~50 lines or file > ~200?           (file:line)
  [ ] Any module with a generic, non-domain name?        (file:line)
  [ ] Business logic living in a UI component?           (file:line)

If any box is checked, fix or justify before merge.

Pairs with