# Architecture Review for PRs

> Reviews a PR against your repo's own recorded decisions — boundary violations, dependency direction, reversed ADRs. No rule to cite means a question, not a finding.

- Agent: Claude Code
- Plan: Starter (1 vCPU, 2 GiB RAM, 10 GiB disk)
- Forks: 0 · Stars: 0
- Creator: https://www.jurniti.com/creator-ca0ff2
- Tags: adr, architecture, claude-code, code-review, github, software-factory
- Requires config (you provide): ANTHROPIC_API_KEY
- Skills: architecture-review

**To fork:** open https://www.jurniti.com/templates/architecture-review-for-prs and use the Fork action — it starts a Stripe Checkout for a new VM seeded with this template's persist disk (same flat plan price, no fork fee).

## README

# The PR passed review and made billing import from the web layer

Tests green, style clean, two approvals. Nobody saw it, because a diff view shows
lines — not directions.

Eighteen months later that import is why the billing rewrite takes a quarter.

## It reviews the decision, not the code

Line-level review is a different job and other tools do it. This asks one question:
**does this change introduce, violate, or silently reverse an architectural
decision?**

Naming, style, micro-optimisation, test coverage — explicitly out of scope, and the
review says so. Mixing both is what trains people to skim.

## The rules come from your repo, never from taste

Before looking at a single hunk it reads **your** architecture documents —
`docs/adr/`, `ARCHITECTURE.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md` — and
extracts the rules with **file:line provenance**.

**If your repo documents no architecture, it says so and stops.** There's nothing to
review against, and inventing rules is precisely the failure mode.

Every finding cites the recorded rule it violates. **If no rule covers it, it's a
QUESTION, not a violation** — *"this introduces a queue; there's no recorded decision
about queues — is that intended?"*

An architecture review that enforces the reviewer's unwritten preferences is how
these get ignored.

## Four things worth catching

1. **Layer / boundary violation** — a module importing what the layering forbids.
   Highest-value catch, and usually invisible in a diff view.
2. **A new dependency direction** — A now depends on B. Cheap to add, expensive to
   unwind.
3. **A silently reversed decision** — the diff does the opposite of a recorded ADR
   without amending it. It names the ADR.
4. **A new integration point** — a service, queue or datastore. Not wrong, but it
   should be a decision rather than an accident.

## Severity is about reversibility

Ranked by how hard the change is to undo **later**, not how wrong it looks now. A
sloppy function is cheap to fix; a dependency direction across a boundary isn't.

## It cannot block you

No approvals, no blocking change requests, no required statuses. It comments when you
ask, and never gates a merge — an agent that can block merges becomes something teams
route around within a week.

## What you supply

`gh auth login` with repo read + PR comment, plus your own Claude Code login. `gh`
ships at `~/.local/bin/gh`.

## Where this stops

It reads and drafts. It won't approve, block, merge, or set a status.

It won't call a design wrong on taste — cite a rule or ask a question. It won't claim
performance impact it didn't measure, won't say a PR is safe to merge, and won't
apply another project's conventions. Only your repo's documents count.

And when there's nothing to say, it says that in one line. A review that manufactures
findings to look thorough is why people stop reading them.

Verified on build: the skill, the working tree, the `NEVER_BLOCK_OR_APPROVE` guard,
the cite-a-rule requirement, all four catches and a working `gh` are present on a
fresh fork. Running it on your own PR is yours to do.