agentleFS
unlockers-aiunlockers-ai/unlockers-skills-library/skills/review-architecture/SKILL.md

review-architecture

Skill4 starsChanged 3 months agoMITView on GitHub

Review branch or pull-request changes for architectural fit — layering, ports and adapters, dependency direction, package boundaries. Use when a change adds a collaborator, crosses a package boundary, or introduces a new seam.

15 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use review-correctness.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • navjyotnishantSkill

    review-correctness

    Use this skill when the user asks to "review my changes for bugs", "check this diff for correctness", "did I introduce a regression", or wants a correctness-focused review of the current commit or uncommitted work before pushing. Reviews the changed lines and their blast radius for logic errors, regressions, unhandled edge cases, and missing validation. Works in any git repo; nothing here is project-specific.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Test reaching across the boundary it is meant to respect

    line 81
  2. Distinctive:

    Check the seams: Every new external collaborator — HTTP, DB, queue, filesystem, clock, randomness, subprocess — should enter through a port …

    line 83
  3. Distinctive:

    If the project has ADRs or active design specs, close with an Alignment section stating whether the change satisfies them.

    line 106

“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Architecture Review Skill

Reviews changes for architectural fit: are boundaries respected, are the seams in the right place, and can this be extended without infrastructure leaking into the domain?

Protocol: docs/review-protocol.md — arguments, ref resolution, exhaustiveness, severity levels, report shape. Read it first. Its § 4 Be exhaustive is mandatory; the lens steps it refers to are steps 3–5 (Map the dependency direction, Apply the architecture lens, Check the seams) below.

Also read: the project's conventions doc (AGENTS.md, CLAUDE.md, CONTRIBUTING.md — whichever exists), docs/design-patterns.md and docs/hexagonal-architecture-rules.md — the latter only where the codebase is actually hexagonal (see step 2), and often only for part of it: one-shot scripts and static-site builds reviewed against the hexagon produce findings nobody will act on. If the project keeps ADRs or design specs, check whether an active one constrains the touched area.

Process

  1. Resolve refs and gather the diff — per review-protocol.md.
  2. Learn the existing architecture before judging it. For each touched package, read its README, its entry point, and one or two existing modules. Determine what style the codebase is actually in — hexagonal, layered, event-driven, transaction-script — and review against that, not against a preferred style. A change that is idiomatic for a layered codebase is not a finding because you would have written it hexagonally.
  3. Map the dependency direction. For each new import crossing a package or layer boundary, note which way it points. Most architectural findings are an arrow pointing the wrong way.
  4. Apply the architecture lens

    Critical (boundary violations):

    • One deployable importing another deployable's internals
    • Shared library importing from an application
    • Domain layer importing an adapter or infrastructure module — the inverted dependency
    • A new SDK / HTTP / DB / broker call placed directly in domain or service code instead of behind a port
    • A concrete adapter constructed inside domain code instead of injected
    • Direct clock, filesystem, randomness or environment access where a port already exists
    • Bypassing an established abstraction with a raw client
    • State written to a module global or singleton instead of an explicit owner

    Major (design cost, paid later):

    • New external collaborator with no port — no seam means untestable
    • Optional constructor dependency added "to simplify tests" (use a Fake instead)
    • New shared mutable state across components
    • One bounded context reaching into another's models or storage
    • A "manager"/"service" class accumulating unrelated responsibilities
    • Behaviour that obviously belongs on an entity pushed into a service (anaemic model)
    • Config object threaded through many layers instead of injecting the resolved value
    • New public API duplicating an abstraction that already exists nearby
    • Multiple side effects with no transaction and no stated decision to go without one — ask what state is left behind when the second write fails after the first succeeded
    • Controller doing more than a few lines of work instead of delegating to a use case
    • A use case interleaving reads, decisions and writes past the signals in hexagonal-architecture-rules.md rule 2 — three functional cases, a second catch, a second read-port or write-port call
    • An adapter reading an inbound payload field by field (.get("status")) where the provider publishes a schema — rule 5

    Minor (alignment):

    • Module in the wrong folder for what it actually is (adapter living under services)
    • Public symbol not exported where its peers are
    • Naming that fights the established vocabulary
    • Test reaching across the boundary it is meant to respect
  5. Check the seams. Every new external collaborator — HTTP, DB, queue, filesystem, clock, randomness, subprocess — should enter through a port with at least one Fake or Null implementation. Constructors should require all collaborators in production.
  6. Confirm § 4 of the protocol is satisfied, then generate report → reviews/architecture-review-issues.md

Severity Model

SeverityIndicators
CriticalHard boundary violation; direct infrastructure call in domain; abstraction bypassed
MajorMissing seam or port; optional collaborator; god class; cross-context leakage; config tunnelling; untransacted multiple side effects; deciding and applying interleaved
MinorMisplaced module; naming drift; missing export

Output Format

Per review-protocol.md, with two extra fields on each finding:

**Principle violated:** e.g. dependency inversion / package boundary / seam-at-boundary
**Suggestion:** the concrete refactor — introduce port `X`, move the call into adapter `Y`

If the project has ADRs or active design specs, close with an Alignment section stating whether the change satisfies them. Drift from a merged, authoritative spec is Critical; drift from a draft is Major.

Example Usage

review-architecture              # Current branch vs main
review-architecture feat/foo     # Specific branch
review-architecture feat/foo dev # Different base
review-architecture 3574         # PR/MR by number

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.