Engineering Principles

Respect Prior Art.

An agent will happily generate thousands of lines of code with no opinion about deep modules, bounded contexts, or what happens when the network fails. Those opinions exist — engineers spent decades earning them and wrote them down, in books like A Philosophy of Software Design, Clean Code, Domain-Driven Design, and Release It!. Engineering Principles lets you choose which of those 378 time-tested, attributed principles govern your repository, resolves the places where the masters disagree, and ships the result as rules and skills your agents follow automatically.

Get started in one minute

You need Node.js version 20 or newer. That's it.

npx agent-engineering-principles

Or from a checkout:

git clone <this-repo-url>
cd agent-engineering-principles
npm start

Your browser opens the workspace. To let the app write files into one of your projects, point it at that project — either now:

npx agent-engineering-principles --project /path/to/your/repo   # (npm start -- --project … from a checkout)

…or later, by typing the path into the Export panel inside the app.

Using the app

The workspace has three panels — work left to right:

1. Pick a book (left panel). Each book shows its cover and a short note on when to lean on it. Click one to browse its principles, or search across all 378.
2. Read a principle (middle panel). Click any principle to expand it. You'll see the same rule at three sizes — Compact (one line), Standard (adds when and why), and Detailed (adds an example, an exception, and how to verify) — plus a before/after code sample you can flip between TypeScript, Python, and Go.
3. Add it at the size you want, using the button on that column.
4. Configure it (right panel). Click a selected principle to set its strength — Required (must hold), Preferred (yields only to stronger concerns), or Advisory (expert input) — and optionally Always apply. Drag to reorder.
5. Resolve conflicts. If two selections pull in opposite directions (say, Clean Code's small functions vs. APoSD's deep modules), a red finding appears with concrete ways to settle it. Export stays locked until you decide — on purpose.
6. Preview and ship. Preview skill shows the exact files that will be generated, byte for byte. Then either download them or click Install to Project.

After an install, the app tells you the one thing left to do: review and commit the files. Everything else is already wired.

What you get, and where it goes

| File | Who reads it | What happens on install | | --- | --- | --- | | engineering-principles.md | Every coding agent, always | Placed at your repo root and referenced from AGENTS.md, CLAUDE.md, and .cursor/rules/ — existing content in those files is never touched, only a clearly marked section is added | | SKILL.md (+ attribution) | Claude Code and other skill-aware agents | Placed in .claude/skills/engineering-rules/; loads automatically for matching tasks, or on demand via /engineering-rules | | engineering-rules.md | Humans | Download only — a readable document with full book-and-chapter provenance | | profile.json | You, later | Saved to .engineering-principles/profile.json — the editable source everything above is regenerated from. Commit it to share the policy with your team |

Use the checkboxes in the Export panel to generate the always-on rules, the skill, or both. Not sure what a file is for? Click "What are these files?" in the app.

Good to know

• Your work saves itself. Selections persist in your browser as you go; closing the tab loses nothing.
• Installs can't destroy your files. Every write is previewed first, and the app refuses to overwrite anything it didn't create — or anything you've hand-edited — without your explicit confirmation.
• Same input, same output. Generation is deterministic with no AI involved; a given profile always produces byte-identical files.
• Private by default. No telemetry, no accounts. The only network use is fetching book covers and publisher blurbs for display (from Open Library and Google Books); everything else — including all generation and installs — is fully local, and the app works offline with generated cover art. Blurbs missing? Google's free shared quota is sometimes exhausted; add your own free API key once in the browser console: localStorage.setItem('engineering-principles:gbooks-key', 'YOUR_KEY').
• Everything is credited. Each principle names its book, author, and source rule, and attribution travels inside every generated file.

For developers

npm test          # builds the catalog and runs the full suite (unit + Playwright browser tests)

Layout: catalog/ (curated principle sources — one JSON file each), scripts/ (the deterministic catalog builder), server/ (stdlib HTTP server + install safety), client/ (vanilla-JS UI, no build step — edit and refresh), shared/ (generators and validation used by both sides), upstream/ (the vendored source catalog). Product decisions live in docs/specs/. To add or edit a principle: change its file in catalog/, run npm run build:canonical, refresh.

Credits and license

Built on the agent-rules-books corpus by Maciej Ciemborowicz (MIT), which distills the source books into rule sets — the vendored catalog lives in upstream/, and the original project's documentation is preserved at docs/upstream-README.md.

All principle texts are meaning-preserving representations of ideas from the credited books. Original copyright remains with the books' authors and publishers — this project adds curation, variants, examples, and tooling, and takes no credit for the underlying ideas.

MIT License.