archprint

# Archprint

[![npm version](https://img.shields.io/npm/v/archprint.svg)](https://www.npmjs.com/package/archprint)
[![CI](https://github.com/Tommkruix/archprint/actions/workflows/ci.yml/badge.svg)](https://github.com/Tommkruix/archprint/actions/workflows/ci.yml)
[![npm downloads](https://img.shields.io/npm/dm/archprint.svg)](https://www.npmjs.com/package/archprint)
[![license](https://img.shields.io/npm/l/archprint.svg)](./LICENSE)
[![docs](https://img.shields.io/badge/docs-live-blue)](https://tommkruix.github.io/archprint/)
[![Glama MCP server score](https://glama.ai/mcp/servers/Tommkruix/archprint/badges/score.svg)](https://glama.ai/mcp/servers/Tommkruix/archprint)

**Mine the architecture rules your repo already enforces, with the evidence attached.**

**[Try it in your browser](https://stackblitz.com/github/Tommkruix/archprint-demo)**, nothing to install ·
[Quick start](#quick-start) · [Use in CI](#use-in-ci) · [Use with AI agents](#use-it-with-ai-coding-agents) · [Docs](https://tommkruix.github.io/archprint/)

## What it does, in plain words

Every codebase has unwritten rules. "Pages never talk to the database directly." "Shared code never reaches back
into the app." Nobody wrote them down, but the code follows them, until one day someone (or an AI assistant)
breaks one without noticing.

Archprint reads a TypeScript project, finds the rules its code already follows, and shows you the proof for each
one: how many files follow it, which files break it, and how sure it is. The rules you trust become automatic
checks in the tools your team already runs, so a break is caught the next time lint runs (in your editor, a
pre-commit hook or CI), not weeks later in review.

Think of it as a building inspector who surveys the house first and writes down how it was actually built,
instead of handing you a rulebook from somewhere else.

- **For developers and tech leads:** inferred, evidence-backed lint rules for ESLint and dependency-cruiser,
  generated with `init`, connected with `wire`, and removed with `eject`.
- **For reviewers:** `archprint check` flags only the rule breaks a pull request introduces, inline on GitHub,
  never the existing backlog.
- **For teams using AI coding agents:** Claude Code, Cursor and other agents can ask Archprint for the project's
  rules, with the evidence, before they write code.
- **For anyone evaluating a codebase:** a quick, honest picture of how a project is actually structured.

Your `CLAUDE.md` is guidance. Your lint rules are enforcement. Archprint closes the gap by generating the
enforcement from patterns your codebase already demonstrates, so you adopt rules you can trust instead of
authoring them by hand.

## See it in action

The recordings below use [archprint-demo](https://github.com/Tommkruix/archprint-demo), a small Next.js API whose
routes reach the database only through a service layer.

**1. Find the rules your code already follows.** Each rule comes with its evidence.

![archprint scan listing the rules a Next.js API already follows, with the evidence for each](docs/public/demo/scan.gif)

**2. See why one rule is trusted.** The confidence check, step by step.

![archprint explain showing the confidence gate behind AP-001](docs/public/demo/explain.gif)

**3. Turn the rules on, watch a break get caught, and remove it all again.** Archprint writes its files, adds one
line to your ESLint config, lint flags a route that imports the database directly, and `eject` restores your
project exactly.

![archprint init and wire adding the rules to ESLint, lint catching a route that imports the database, and eject restoring the config exactly](docs/public/demo/enforce.gif)

**Try it yourself, nothing to install:** [open the demo in StackBlitz](https://stackblitz.com/github/Tommkruix/archprint-demo).
The scan runs as soon as it opens, and the [demo's README](https://github.com/Tommkruix/archprint-demo#try-it)
walks through enforcing a rule in ESLint, breaking it, and asking for the rules over MCP.

## Use it with AI coding agents

AI coding agents can ask Archprint for a project's rules through
[MCP](https://modelcontextprotocol.io), an open standard that lets agents use outside tools. You ask in plain
words; the agent calls Archprint on its own and answers with the evidence. Archprint only reports. Enforcement
still runs in your linter.

**Claude Code** calls Archprint by itself when you ask about the architecture:

![Claude Code answering "What architecture rules does this repo already follow?" by calling archprint](docs/public/demo/claude-code.gif)

**Cursor works the same way.** In these recordings Cursor was set to Grok 4.7, not Claude. In the desktop app's
chat, its agent called Archprint's scan tool on its own; this screenshot shows the tool result and the answer:

![Cursor's desktop chat, running Grok 4.7, answering from archprint's scan result: the rules and lib/db.ts as the one exception](docs/public/demo/cursor-app.png)

In the terminal (`cursor-agent`), it asks once before running the tool, then answers from it:

![Cursor's terminal agent, running Grok 4.7, approving archprint_scan once and answering with the rules and lib/db.ts as the one exception](docs/public/demo/cursor.gif)

### Measured: the same question with and without Archprint

We asked Claude Code (Opus 5.5) "What architecture rules does this repo already follow?" on the demo app (70
files), five runs each way. Median [range]:

|                   | Without Archprint         | With Archprint            |
| ----------------- | ------------------------- | ------------------------- |
| Tokens read       | 81k [58k to 96k]          | 52k [52k to 52k]          |
| Tokens written    | 1.1k [1.1k to 1.4k]       | 0.6k [0.6k to 0.6k]       |
| Cost per question | $0.083 [$0.078 to $0.153] | $0.037 [$0.032 to $0.076] |
| Time              | 17 s [15 to 19]           | 10 s [9 to 31]            |
| Tool calls        | 5 [4 to 10]               | 2 [2 to 2]                |

What the answers showed:

- Both found the main rule: routes reach the database only through `lib/services/`.
- With Archprint, every run gave the evidence for each rule and named the one file that breaks one (`lib/db.ts`
  reads `process.env` outside the config layer). No run without it noticed that.
- Without Archprint, Claude also described naming conventions Archprint does not check.

Read these numbers with care: about 50k of the tokens read in both columns are Claude Code's own system prompt,
and this is one small repo; larger ones are not measured yet.
[Method, harness and every answer](https://github.com/Tommkruix/archprint-demo/tree/main/bench).

Setup for Claude Desktop, Claude Code, Cursor and other clients is in [MCP setup](#mcp-setup).

## Quick start

Requires Node 20 or newer. Run these in a folder with a `tsconfig.json`. In a monorepo, `scan` and `recommend`
also accept the root and cover every app, while `init` and `generate` work on one app at a time (for example
`apps/web`); at a root with several apps they stop, list the apps, and ask you to rerun with one.

```bash
# 1. See the rules your code already follows, with the evidence. Changes nothing.
npx archprint scan .

# 2. Ask why one rule is trusted (use a rule label from the scan)
npx archprint explain AP-001 .

# 3. Set up enforcement for the rules your code already follows cleanly,
#    and record what to review or adopt next in .archprint/config.json
npx archprint init .

# 4. Connect the generated rules to your ESLint / dependency-cruiser config (one managed line)
npx archprint wire

# 5. Run your linter as usual. Your code passes today; a new import that breaks a rule fails.
npx eslint .

# To undo everything, exactly:
npx archprint eject
```

**See it catch something.** After step 4, break a rule on purpose: for example, make a route file import your
database client directly, then run your linter. That is the whole loop the
[demo](https://stackblitz.com/github/Tommkruix/archprint-demo) walks through in the browser.

To keep it in the project instead of using `npx`: `npm install --save-dev archprint`.

More commands for a deliberate, step-by-step setup:

```bash
# Inspect the evidence behind one rule
archprint explain AP-002 apps/web

# Write the auto-trusted (mechanical) rules to .archprint/, only for the linters your repo uses.
# Structural-inference rules are held for review; add --include-structural to emit them too.
archprint generate apps/web

# Confirm the generated rules pass on your repo before wiring
archprint generate apps/web --check

# Generate a single rule by id after reviewing it (including a SUGGEST rule)
archprint generate apps/web --rule AP-001

# Recommend a rule set from the evidence and the detected stack (fresh repos too)
archprint recommend apps/web

# Upgrading from 0.5.x? Move an older archprint-rules/ setup to the .archprint layout
archprint migrate
```

Or build from source:

```bash
git clone https://github.com/Tommkruix/archprint
cd archprint
npm ci
npm run build
node dist/cli.js scan <path-to-your-app>
```

## How it decides what to trust

Archprint is deliberately cautious: one wrong rule hurts more than no rule. Every candidate rule passes two checks
before it is turned on for you.

**1. Is there enough evidence?** Seeing 5 of 5 files follow a pattern is not proof; 40 of 40 is. Archprint scores
each rule with a **Wilson score lower bound**, a standard statistical measure that combines how often the rule
holds with how many files it was checked on. Each rule lands in one of three groups:

- **AUTO** (enforceable): the 95% lower bound on conformance is at least 90%, with at most 3 exceptions and a
  confidently classified role.
- **SUGGEST** (provisional): the pattern holds in at least 80% of files and the role is at least 50% certain,
  but one AUTO condition fails: the confidence floor is under 90% (too few files, or too many that break it),
  more than 3 files break it, or the role is under 80% certain. Surfaced for review, not auto-