# Architecture-aware review

> Feed an architecture.json — the config of the sibling tool archlint, declaring layers and their allowed import edges — into the review prompt, so the reviewer can flag a diff that crosses a declared architectural boundary. A one-way read; CommitBrief never lints or enforces.

CommitBrief docs · v1.x · Reviewing

Canonical URL: https://commitbrief.com/docs/1.x/architecture-review

---

Architecture-aware review is a CommitBrief feature that reads your
repo's `architecture.json` — the config of the sibling tool archlint,
declaring **layers** and their **allowed / forbidden import edges** — and
feeds a compact summary into the review prompt, so the reviewer can flag
a diff that crosses a boundary your architecture forbids. A good
reviewer knows your architecture: which layers may depend on which, and
which dependencies are forbidden; this feature gives the model that same
map. New in v1.11.0 (ADR-0030).

## Where the map comes from

`architecture.json` is the public config of the sibling tool
[archlint](https://github.com/muhammetsafak/archlint), which
deterministically lints import-boundary rules. CommitBrief reuses that
same file:

```json
{
  "layers": { "domain": ["internal/domain"], "db": ["internal/db"] },
  "rules":  { "domain": [], "db": ["domain"] }
}
```

- **`layers`** maps a layer name to the path prefixes that belong to it.
- **`rules`** lists, per layer, the layers it is **allowed** to import.
  `[]` means it may import no other layer. In the example above, `db` may
  import `domain`, but `domain` may import nothing — so a new
  `domain → db` import is a boundary violation.

CommitBrief folds a summary of this into the prompt as a distinct
`<architecture_constraints>` block. The reviewer can then call out a
diff that, say, adds a `domain → db` dependency the architecture forbids.

## It reads — it does not enforce

This is a strict **one-way read** of archlint's config. CommitBrief
never lints the import graph and never enforces anything itself — it only
grounds the LLM so it can reason about the change. For the deterministic
gate, run `archlint check` in CI; architecture-aware review is the
*soft*, prose-level complement that catches a boundary slip in the same
pass as the rest of the review.

A missing or malformed `architecture.json` is a **transparent no-op** —
it never breaks a review.

## Cache behavior

Because the architecture summary folds into the system prompt, editing
`architecture.json` automatically **invalidates stale cached reviews** —
the next run reflects the new constraints. A repo *without* the file
produces a **byte-identical cache key** to before, so adding this feature
caused no mass cache invalidation.

## Turning it off and pointing it elsewhere

On by default. Skip it for one run, or disable it persistently:

```sh
# Per-run: review without the architecture block.
commitbrief --staged --no-architecture
```

```yaml
# Per-config.
review:
  architecture: true              # default true; --no-architecture is the per-run equivalent
  architecture_file: ""           # override the discovery path; empty = auto-discover architecture.json at the repo root
```

```sh
commitbrief config set review.architecture false
```

Point it at a non-default location with `review.architecture_file`
(relative to the repo root, or absolute).

Architecture-aware review applies to a normal `review` and to
[`dry-run`](/docs/1.x/configuration#dry-run); `remote pr` is unchanged.

## See also

- [Review rules](/docs/1.x/review-rules) — `COMMITBRIEF.md`, the
  prose rules that steer the review alongside the architecture map.
- [Configuration](/docs/1.x/configuration) — `review.architecture` and
  `review.architecture_file` in the config reference.
- [Safety and cost](/docs/1.x/safety-and-cost#cache) — how
  the prompt feeds the cache key.