There is a lazy habit in the adoption of AI agents in engineering teams: creating an AGENTS.md (or CLAUDE.md, or .cursorrules) with a single line like "OBEY Clean Code by Robert C. Martin" and considering the job done. The intuition is reasonable, the model knows the book, it was trained on thousands of blogs about the subject, mentioning it should be enough. It is not enough. And now there is measurement.
Maciej Ciemborowicz, author of the repository ciembor/agent-rules-books (1.4k stars, MIT), published an uncomfortably clear experiment. Same starting codebase (a deliberately vibe-coded helpdesk CLI), same model (GPT-5.5, high reasoning), same refactor plan, only the content of the AGENTS.md changes. One branch uses only the line "obey Clean Code". The other uses the mini rule set distilled from the book. The result, judged by ChatGPT on the question "which code better implements Ousterhout's principles?", was 74 to 46. Twenty-eight extra points of architectural quality, at the sole cost of swapping one line of text for about 50 lines of concrete rules.
Why just citing the book does not work
The intuitive reflex is to think that the model "knows" Clean Code because the entire book is in the training corpus. Knowing and applying consistently are not the same thing. The LLM has sparse activations over the book, references, quotes, isolated examples, blogs about the book, posts that disagree with the book, contradictions between 2008 Uncle Bob and 2020 Uncle Bob. Asking it to "obey Clean Code" lets the model navigate that entire cloud without an operational anchor. What comes out is a weighted average of what circulates in the corpus, not the specific decisions the book defends.
A set of concrete rules, on the other hand, does three things the mention alone does not. (1) It reduces entropy, the model does not have to guess which interpretation of "clean" to use, it receives the interpretation ready-made. (2) It fits in the attention, 50 lines of rules are always in the context, the entire book never is. (3) It resists dilution over long sessions, the more the agent iterates, the further the book mention drifts from the current attention span; an explicit rule in AGENTS.md gets re-read at every file decision.
What the repo delivers in practice
The agent-rules-books distills 13 canonical software engineering books into rule sets ready to paste into AGENTS.md, into CLAUDE.md, into Cursor rules, or to become Claude Code skills. The list is exactly what you would expect to see on the shelf of anyone who takes engineering seriously:
- Clean Code (Robert C. Martin), local readability, naming, small functions, single responsibility
- Clean Architecture (Martin), stable boundaries, dependency rule, isolation of details
- A Philosophy of Software Design (Ousterhout), deep modules, simple interfaces, reduction of cognitive load
- Code Complete (McConnell), disciplined construction, defensive programming, flow control
- Refactoring (Fowler), small steps, code smells, separation of refactor and feature
- Refactoring.Guru, practical catalog of smells and treatment techniques
- Patterns of Enterprise Application Architecture (Fowler), Repository, Unit of Work, Data Mapper, etc.
- Domain-Driven Design (Evans), domain modeling, bounded contexts, ubiquitous language
- Domain-Driven Design Distilled (Vernon), DDD without excessive ceremony
- Implementing DDD (Vernon), aggregates, domain events, integrations
- Designing Data-Intensive Applications (Kleppmann), replication, partitioning, consistency, schema evolution
- Release It! (Nygard), circuit breaker, bulkhead, timeout, backpressure
- The Pragmatic Programmer (Hunt/Thomas), DRY, orthogonality, automation, fast feedback
- Working Effectively with Legacy Code (Feathers), characterization tests, seams, dependency breaking
Each one comes in three sizes: full (canonical, 12-60KB), mini (recommended for real use, 3-8KB) and nano (tight-budget fallback, 1-3KB). This stratification is not aesthetic. It is the honest admission that context is a finite resource and that every byte of the system prompt competes with the real task.
Full vs Mini vs Nano: the economics of the context budget
Here is the detail many people ignore: the size of the rule set changes the economics of the entire session. An AGENTS.md with 60KB of Clean Architecture full + DDD full + DDIA full is impressive to read, and pathologically expensive to use. Each turn of the agent pays those tokens in latency and in accuracy points displaced from the real task. It is exactly the same pattern that the post on the cost of ritualistic abstraction denounced: ceremony that does not fit the budget becomes a recurring tax.
The mini solves this with pragmatism worthy of respect. In around 5KB per book, it delivers: when to use it, primary bias to correct, decision rules (12-15 items), trigger rules (when to apply), and a final checklist. It is the operational distillation that fits in the model's attention during a long session. The choice between full/mini/nano should be made exactly like the choice of any other dependency: how much value does it deliver, how much budget does it consume, is the trade worth it?
The methodological detail that matters most: Reek barely saw the difference
This is the point that separates it from pure marketing experiment. When Ciemborowicz ran the Reek linter (a code smells analyzer for Ruby) on both branches, the result was 1,083 smells in the "just mention the book" branch against 1,077 smells in the branch with mini rules. Practically a technical tie on the automatic meter. The gain was not on the surface, it was not a better-named variable, a shorter function, or a cleaner import. It was architectural: module depth, responsibility boundaries, information hiding, the amount of code the reader has to understand at once to change something.
This finding has a huge practical implication for those who measure quality only with SonarQube, ESLint or similar: if your only criterion is a static warning count, you are blind to the real gain from architecture rules. The linter measures what fits in an AST. The design rule measures what fits in the head of the next engineer who will touch the code. The two measure different things, and the industry, for two decades, has optimized only the first.
How to choose the right books for your team (do not copy all of them)
The temptation when looking at 13 books is to paste them all into the AGENTS.md. Do not do this. The books conflict with each other on important points, heavy DDD vs DDD Distilled vs A Philosophy of Software Design have different views on how much abstraction to introduce. Stacking conflict does not give the agent "the best of all"; it gives a confused average.
The healthy heuristic is to choose 2 to 3 books based on the dominant use case of the repository. Useful patterns:
- New product codebase, without large debt: Clean Code (mini) + A Philosophy of Software Design (mini). Focus on readability + deep modules.
- Legacy codebase with low test coverage: Working Effectively with Legacy Code (mini) + Refactoring (mini). Seams first, transformations later.
- Critical production service (payments, authentication): Release It! (mini) + Clean Architecture (mini). Operational resilience + immutable boundaries.
- System with a rich domain and complex business rules: DDD Distilled (mini) + Implementing DDD (mini). DDD in the right dose, without academic ceremony.
- Data pipeline, ETL, events: DDIA (mini) + Pragmatic Programmer (mini). Semantic consistency + automation.
Combining more than 3 sets is usually a symptom of architectural indecision, it is easier to choose everything than to look at the reality of the code. Resist.
The limits of the experiment, and why it still matters
Ciemborowicz himself is honest about the limitations: it was a single case, judged by an LLM (ChatGPT) with a subjective prompt, on a project deliberately bad to serve as a guinea pig. It is not a benchmark. It is not paired against other rule sets (Cursor official, awesome-prompts, etc.). It has no replications in different languages. As he wrote himself, it should be treated as an "early qualitative signal, not benchmark".
Even so, the direction of the signal is too strong to be ignored. Doubling the specificity of the instruction substantially improved the architectural output, and this matches the intuition anyone who has been prompt-engineering for more than six months already has: being specific beats being elegant. The adoption cost is absurdly low (copying 50 lines of markdown), and the downside is negligible (if the rules conflict with your style, you edit or remove them). It is the definition of asymmetric upside.
Pragmatic adoption, the 30-minute path
Most teams get stuck in the "I will study all the options before choosing" phase. Skip that phase. The short cycle is the following:
- Choose 1 book that matches the most visible pain of the repository right now. Clean Code if the problem is readability. Release It! if the problem is stability. DDD Distilled if the problem is a confused model.
- Paste the mini set into the
AGENTS.md(orCLAUDE.md, or Cursor rules). Do not edit it the first time, observe the agent operating with the raw set. - Do a real feature with the agent following the rules. Compare it with an equivalent PR from last week, done without the rules. Look specifically at: module depth, number of open files, function size, boundary clarity.
- Iterate: edit the set by removing rules that conflict with your team's style, adding 2-3 specific to your domain.
- Only now consider adding a second book, if you feel something is missing. More than 3 books is a sign that you are avoiding the decision.
The game changed: AGENTS.md is no longer decoration
For two years, AGENTS.md was a file that teams created for completeness, "let's put some generic rules". The agent-rules-books does what needed to be done: it treats the file as a first-order engineering artifact, with versioning (full/mini/nano), a validation methodology, and curation from the sources the industry already recognizes as canonical. It is not the only way. But it is the first that combines methodological rigor with an MIT license and immediate practical use.
For those who still believe that mentioning the book is enough, the number 74 to 46 should be sufficient. For those who already suspected it, the repo delivers the shortcut. The adoption cost is a morning. The gain is architectural and cumulative. In a team where half of the interactions with the code go through an agent, ignoring this optimization is a conscious decision to pay a recurring tax in quality, for the sole benefit of looking minimalist in the AGENTS.md.