Archprint

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 · Use in CI · Use with AI agents · Docs

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, 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.

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

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.

Try it yourself, nothing to install: open the demo in StackBlitz. The scan runs as soon as it opens, and the demo's README 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, 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 lists the rules with what is enforced and what is held for review, then adds a route and checks its own change with archprint before it reports back:

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:

In the terminal (cursor-agent), it does the same: lists the rules, then adds the route and checks it with archprint_check:

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]:

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.

Setup for Claude Desktop, Claude Code, Cursor and other clients is in 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.

# 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

The rules you already wrote down

Your CLAUDE.md or AGENTS.md probably states rules already ("never call fetch in a component", "packages/ui must not import the app"). Agents read them as guidance. archprint gap-report checks them against the code: your agent maps each rule-like sentence to one of a few fixed templates, quoting it, and Archprint verifies the mapping and measures it. Ask your agent "Which of the rules in our CLAUDE.md does the code actually follow?", or give the CLI the mapping file your agent wrote:

{

"rules": [ { "source": { "file": "CLAUDE.md", "quote": "Never call fetch directly in a component" }, "name": "no-fetch-in-components", "template": "forbid-usage", "files": ["src/components/**"], "usage": ["fetch"] } ] }

Each sentence comes back as enforce now (nothing breaks it today), enforce with a baseline (broken today, with the files and lines), already an archprint rule, check the mapping (the quote is not in the file, or the mapping matches no code), or guidance only. Archprint never calls a model: the agent only maps prose to a template, and every number in the report is computed from your code. Adopt the ones you approve with archprint generate --declare mapping.json (add --baseline for those the code breaks today): each becomes an ESLint rule whose error is your team's sentence, with its line in CLAUDE.md, and archprint check enforces it in pull requests. See the gap report for the templates.

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 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:

# 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 (on its own, --check writes nothing)

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

Adopt only the rules you choose, including reviewed layer boundaries

archprint generate apps/web --include-structural --rules AP-002,no-utils-to-app

Recommend a rule set from the evidence and the detected stack (fresh repos too)

archprint recommend apps/web

Check the rules your CLAUDE.md or AGENTS.md states against the code, from a mapping your agent wrote

archprint gap-report mapping.json .

Enforce the ones you approve (with --baseline, also those the code breaks today)

archprint generate apps/web --declare mapping.json

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

archprint migrate

Or build from source:

git clone https://github.com/Tommkruix/archprint

cd archprint npm ci npm run build node dist/cli.js scan

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 exc