@kekkai/blueprintArchitecture as Code
Translates your frontend architecture into ESLint rules and an AI agent contract.
Skip to content
Why you need it
What letting an AI write your code quietly costs — and what blueprint does about each.
Placement
The AI ships a working feature — and drops the new files wherever was convenient. A few sessions later, nothing lives where it should.
→ blueprint pins where each layer’s code belongs — and lint blocks the crossing
See how →Single responsibility
“Just make it work” — so the AI keeps piling responsibilities into one file until it does five jobs and owns none.
→ blueprint writes single-responsibility into the contract, and lint enforces the mechanical minimum
See how →File size
Every AI edit grows the file. Three months in, one module is 6,000 lines — and every future agent has to load all of it to touch one function.
→ blueprint caps file size before it starts costing you tokens
See how →Readability
The feature passes. But the AI optimized for done, not for the next reader — and the next reader is another agent that now can’t navigate it.
→ blueprint briefs every session on the same readability bar
See how →Consistency
Every session, the AI re-derives your architecture from scratch — and each one guesses differently.
→ blueprint gives every session the same written contract
See how →Adoption
Point this at a 3-year repo and you’d expect 4,000 errors — so the team disables it on day one.
→ blueprint locks today’s debt, gates only what’s new
See how →Write Once. Generate Everything
blueprint.config.mjs
eslint.config.mjs
docs/architecture-handbook.md
CLAUDE.md · AGENTS.md · …
inspect · deps · rules
Edit the config, regenerate, and every artifact moves together — they cannot drift, because they are all translations of the same source. See them verbatim in What init Generates.
Quick start
Two ways to adopt on an existing repo. You paste almost nothing — init --authoring writes the playbook that tells the agent the rest: run it to the end, and what "done" means.
Hands-off
Hand your agent a prompt — it runs start to finish on its own.
paste to your agent
Run npx @kekkai/blueprint init --authoring to adopt @kekkai/blueprint in this repo.
What each acceptance step guards, and the full flow: AI-Assisted Adoption.
Philosophy
Blueprint's engineering philosophy has these facets — all compiling into your repo as lint rules and an agent contract:
01Layer architectureWhere code lives, what may import what.
02Component shapeHow a unit is sized and split.
03Core beliefsOne source of truth, cost, dead code, and more.
04Working disciplineRuntime load, dead code, refactor moves.
Blueprint doesn't cover your framework's best practices — so pair it with the resource for your stack:
- React & Next.js — vercel-labs/agent-skills: installable best-practice skills from Vercel Engineering, alongside the blueprint contract, so the agent gets your structure rules and the framework's idioms.
- Vue — vuejs/docs: the official documentation source; point your agent at it for API ground truth, pairs with the Vue preset.
Blueprint governs where code goes; your framework's resource covers how it's written — together they narrow the gap between "it compiles" and "it's good". See the full reasoning in the philosophy.