ciembor/agent-rules-books: AGENTS.md Rules and Skills for Codex, Cursor and Claude Code

The gap ciembor/agent-rules-books fills between a blank prompt and a style guide

A coding agent asked to refactor a function has no opinion about naming, module boundaries or where a domain concept belongs. It will happily inline a value object, split a cohesive class into three anemic ones, or introduce a framework dependency into the middle of a domain layer, because nothing in the prompt says otherwise. Teams usually respond by pasting a few paragraphs of house style into AGENTS.md or .cursorrules and calling it done. Those paragraphs are written under deadline, reflect one person's preferences, and rarely cite anything.

This repository takes a different route. It converts well-known software engineering books into Markdown rule sets that agents can load as context. The README lists the sources: Clean Code, Clean Architecture, Refactoring, Domain-Driven Design, Domain-Driven Design Distilled, Implementing Domain-Driven Design, Patterns of Enterprise Application Architecture, A Philosophy of Software Design, Code Complete, Designing Data-Intensive Applications, Release It!, The Pragmatic Programmer and Working Effectively with Legacy Code. The intended audience is engineers who already use Codex, Cursor or Claude Code on a real codebase and want the agent's review comments to come from a shared, citable body of practice rather than from vibes.

The repository describes its rule sets as "MIT licensed universal project rules for coding agents" and notes that they are tool-agnostic. That matters: the same Markdown can be dropped into an AGENTS.md file, loaded as a Claude Code skill, or scoped to a directory in Cursor. Nothing in the rule files themselves is bound to one editor.

How the rule sets are structured: nano, mini and full

Every book directory contains three Markdown files: a canonical `full` version, a `mini` version, and a `nano` version. The README states that `mini` is "the recommended version for most real task use" and that `nano` is "the compact fallback for very tight context budgets", while `full` is "the canonical complete source and reference version".

The release matrix in the README quantifies the difference. Domain-Driven Design is the largest: the full file is 979 lines, 523 rules and 42424 bytes, while its mini file is 48 lines, 30 rules and 5683 bytes, and its nano file is 39 lines, 21 rules and 2266 bytes. Clean Code is the smallest full file at 297 lines, 220 rules and 13851 bytes, with a nano version of 32 lines, 14 rules and 1235 bytes. The README also explains the counting convention: `lines` is the physical line count from `wc -l`, `rules` counts Markdown list items using what it calls "the deterministic release convention", and `size` is raw bytes from `wc -c`.

That three-tier design is the most interesting engineering decision in the project. Context windows are finite, and a 42424-byte rule file competes directly with the source code the agent needs to read. Splitting each book into a short default and a long reference lets you load the compressed version during normal work and pull the full file only when you are doing an architecture review. The trade-off is that you now maintain three artifacts per book, and the nano versions are aggressive: Clean Code's nano file carries 14 rules for the entire book, which is a lossy summary by construction.

Each book directory also contains a standard `SKILL.md` entrypoint. According to the README, the skill loads the corresponding `mini` rule set by default and keeps the `full` file available as deeper reference material. That is a sensible default: the agent gets a compact working set immediately and can reach for the long version on demand.

Installing the book skills with the Agent Skills CLI

The README gives a single prerequisite: install Node.js with npm. The Skills CLI itself does not need a separate install, because it runs through `npx`.

To see what is available before committing anything to disk, list the skills:

npx skills add ciembor/agent-rules-books --list

This prints the available book skills without installing them. If the list looks right, install everything:

npx skills add ciembor/agent-rules-books --all

If you would rather not load every book into every session, install one skill at a time. The README gives this example for Refactoring:

npx skills add ciembor/agent-rules-books --skill refactoring

After installation, the skill resolves through the `SKILL.md` entrypoint in the book's directory and loads the `mini` rule set by default, with the `full` file kept as reference. The README points to docs/USAGE.md for manual, scoped, always-on and editor-specific installation patterns, and to docs/COMPATIBILITY.md for which books work together. If you prefer not to use the CLI at all, the rule files are plain Markdown in the repository, so copying one into your project's AGENTS.md is a legitimate path that the README acknowledges.

Where this approach breaks down

The rules are prose, and prose does not enforce itself. Nothing in this repository runs a check, fails a build, or blocks a commit. An agent that loads the Clean Architecture rule set can still place a database call inside an entity, because the rule is a sentence in a Markdown file and the agent's compliance is probabilistic. If you need a guarantee, you need a linter or a type system, not a rule set.

There is also a real risk of contradictory advice. Clean Architecture and Domain-Driven Design both push toward explicit boundaries, but they use different vocabularies and sometimes different priorities. Load three or four books at once and the agent receives a large, partly overlapping instruction set. The README does not document how conflicts between books are resolved, and it points readers to docs/CRITICISM.md for "constructive criticism from Reddit", which suggests the maintainers are aware that the approach has detractors.

The nano versions deserve particular scepticism. Reducing a 979-line, 523-rule DDD file to 39 lines and 21 rules is a compression ratio of roughly 25 to 1. Something is lost, and the README does not describe what the compression preserves or discards. Treat nano as a last resort for tight context budgets, not as a default.

Finally, the fit is wrong for some projects entirely. A short-lived script, a prototype, or a codebase with no domain model gains little from DDD or Clean Architecture rules, and the added context may crowd out the actual task. The repository is a library of opinions, and opinions about architecture are only useful when there is architecture to discuss.

How this differs from a linter, a formatter or a generic prompt library

The closest alternative is not another rule repository but the tools engineers already run: ESLint, Ruff, golangci-lint, Prettier, Checkstyle. The difference in approach is fundamental. A linter encodes a rule as an executable check with a pass or fail result. It will tell you that a function exceeds a complexity threshold, every time, deterministically. This repository encodes a rule as a sentence an agent may or may not follow. Linters cannot express "prefer a deeper module over a shallow one" or "keep the ubiquitous language consistent across the bounded context", which is exactly the territory these rule sets occupy. The two are complementary, not substitutes, and the README makes no claim that they replace static analysis.

The other alternative is writing your own AGENTS.md. That is what most teams do, and it has a real advantage: your rules reflect your codebase, your naming, your deployment constraints. The trade-off is provenance and coverage. A hand-written file usually covers the five things that went wrong last sprint. A rule set derived from Refactoring or A Philosophy of Software Design covers a much wider surface, and you can point a reviewer at the book when a rule is contested. The cost is that the rules are generic by design, so you will still need a project-specific layer on top.

There is also a middle path the README hints at rather than documents: scoped rules. Cursor and Claude Code both support directory-level instruction files, and docs/USAGE.md is where the repository says it covers "always-on vs on-demand usage, skills, scoped rules, and the preferred setup for each editor". If you only want DDD rules to apply inside a `domain/` directory, that is the file to read.

Maintenance, versioning and what the MIT licence means here

The repository is not archived, and the last push was on 2026-09-10. Releases are tagged and numbered: v0.3 on 2026-05-02, v0.4 on 2026-05-03, v0.5 on 2026-05-04. The README's header advertises v0.6. The three releases in early May landed within three days of each other, which is a burst pattern rather than a steady cadence, and the gap between v0.5 and the current README version is roughly four months. CHANGELOG.md exists at the repository root and the README points to it for release history.

Upgrade cost is low in the mechanical sense. The artifacts are Markdown files and a `SKILL.md` per book, so an upgrade means re-running the install command or replacing files. There is no compiled dependency, no runtime, no migration. The real cost is behavioural: if a rule set changes between versions, your agent's review behaviour changes with it, and there is no automated way to detect that from the repository alone. Pin the version you install if you care about reproducibility.

On licensing, the repository is MIT. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. Two caveats worth stating plainly, without giving legal advice. First, MIT covers the repository's own contents; the books that inspired the rule sets are separately copyrighted, and the README describes the files as "inspired by" those books rather than as excerpts from them. Second, if you fork and redistribute the rule sets inside a commercial product, the MIT notice travels with them. Read LICENSE at the repository root for the exact terms.

Editorial conclusion

Adopt it if you already run Codex, Cursor or Claude Code on a codebase where design review matters and you want the agent to hold a consistent set of heuristics drawn from named books. Skip it if you want a linter, a formatter or anything that enforces rules mechanically, because this repository ships prose, not tooling. Before wiring it into a team workflow, read docs/CRITICISM.md and docs/COMPATIBILITY.md, then decide which of the three sizes (nano, mini, full) fits your context budget.

Frequently asked questions

Official sources

1. ciembor/agent-rules-books on GitHub
2. License: MIT
3. Project website
4. README
5. Releases