[opensourcedex]

agent-rules-books is a free, open source ai development platforms project written in several languages and released under MIT. It has 3,170 GitHub stars, 552 forks and 5 open issues, and was last pushed 2 months ago. On this registry it ranks #139 of 155 tracked projects in AI Development Platforms, with 5 head-to-head comparisons available. It gained 278 stars over the last 30 tracked days.

What is agent-rules-books?

agent-rules-books is an MIT-licensed, tool-agnostic collection of AGENTS.md rules and agent skills, distilled from classic software engineering books, that installs into AI coding agents such as Codex, Cursor and Claude Code to steer them toward better refactoring, architecture, domain-driven design and code quality.

What it is

The project provides ready-to-use rule sets for coding agents, each one derived from a well-known book on software design, architecture, refactoring, legacy code, reliability or data-intensive systems. Covered titles include Clean Code, Clean Architecture, Code Complete, Refactoring, Domain-Driven Design, Designing Data-Intensive Applications and A Philosophy of Software Design. Every rule set ships in three tool-agnostic Markdown versions: mini, described as the recommended version for most real task use; nano, a compact fallback for very tight context budgets; and full, the canonical complete source and reference version. Each book directory contains a standard SKILL.md entrypoint that loads the mini rule set by default while keeping the full file available as deeper reference material.

The concrete problem it solves is the blank page that greets anyone writing agent instructions. Instead of hand-authoring project rules and hoping they capture decades of accumulated engineering judgement, a user installs curated rule sets that already encode the practices from these books. It lives in the emerging agent skills and AGENTS.md ecosystem, alongside the open Agent Skills CLI, and it replaces the ad hoc, self-written rule files that teams otherwise maintain separately for Codex, Cursor and Claude Code. The rules are deliberately tool-agnostic Markdown, which is what lets a single source serve all three editors.

Key capabilities

  • Three release tiers per book — mini, nano and full — so the same rule set scales from recommended everyday use down to very tight context budgets.
  • A standard SKILL.md entrypoint in every book directory, allowing installation through the open Agent Skills CLI.
  • Skills CLI commands for bulk and selective installs: npx skills add ciembor/agent-rules-books --all, --list to preview without installing, and --skill refactoring to install a single rule set.
  • docs/USAGE.md documents always-on versus on-demand usage, skills, scoped rules and the preferred setup for each of Codex, Claude Code and Cursor.
  • A release matrix reporting deterministic metrics per rule set, including line counts from wc -l, rule counts from a fixed counting convention, and raw byte sizes from wc -c.
  • Rule sets spanning refactoring, code quality, clean architecture, domain-driven design and data-intensive systems.
  • CRITICISM.md collects constructive criticism from Reddit, and CHANGELOG.md records release history, with the current line at v0.6.

Who uses it and how

  • Teams running more than one AI coding agent, using a shared Markdown rule source so Codex, Cursor and Claude Code behave consistently.
  • Developers working under tight context limits, who install the nano version instead of the recommended mini one.
  • Engineers doing refactoring or legacy-code work, who install the targeted refactoring skill rather than the whole collection.
  • Architects and domain-modelling practitioners applying the Clean Architecture and Domain-Driven Design rule sets as always-on or scoped rules.
  • Contributors who read CRITICISM.md before adopting, and track changes through CHANGELOG.md.

Getting started

Install Node.js with npm, then install every book skill with npx skills add ciembor/agent-rules-books --all; skills itself does not need separate installation. For editor-specific, manual or scoped setups, follow docs/USAGE.md.

How it compares

No list of paid products this project replaces is provided in the facts, and no directly comparable tool is named, so it stands alone in this registry. What the facts do establish is its position across three agent ecosystems at once — Codex, Cursor and Claude Code — served from one MIT-licensed Markdown source rather than per-editor rule formats.

When to use it — and when not to

There is nothing to operate: no database, storage layer or SMTP service is mentioned, because the deliverable is Markdown plus a Node.js-based CLI install. It is a poor fit for anyone expecting a hosted product, and the rule sets are distilled summaries of the source books rather than replacements for reading them. The facts also show that a CRITICISM.md file exists, which signals the maintainers consider the rule sets debatable rather than settled.

project readme (upstream, from github) — read inline

Polish Repo badge skills.sh

AI agents Rules / Skills from
Programming Books v0.6

AGENTS.md rules / skills for Codex, Cursor, Claude Code, distilled from classic software engineering books about refactoring, architecture, DDD and code quality.

About · Installation · Rules / Skills · Books List · Usage · Books Compatibility

About

MIT licensed universal project rules for coding agents.

This repository contains ready-to-use rule sets inspired by well-known books on software design, architecture, refactoring, legacy code, reliability, and data-intensive systems.

For editor-specific setup in Codex, Claude Code, and Cursor, see USAGE.md. It covers always-on vs on-demand usage, skills, scoped rules, and the preferred setup for each editor.

Each rule set is released in three tool-agnostic Markdown versions:

  • mini: the recommended version for most real task use
  • nano: the compact fallback for very tight context budgets
  • full: the canonical complete source and reference version

For constructive criticism from Reddit, see CRITICISM.md.

For release history, see CHANGELOG.md.

Installation as Skills

Prerequisite: install Node.js with npm. You can run the Skills CLI through npx without installing skills separately.

Install all book skills with the open Agent Skills CLI:

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

List available skills without installing:

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

Install one selected skill:

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

Every book directory contains a standard SKILL.md entrypoint. The skill loads the corresponding mini rule set by default and keeps the full file available as deeper reference material.

If you prefer another setup, see USAGE.md for manual, scoped, always-on, and editor-specific installation patterns.

Release Matrix

Metrics:

  • lines: physical line count from wc -l
  • rules: Markdown list items counted with the deterministic release convention
  • size: raw bytes from wc -c
Rule Set Full file Full lines Full rules Full size Mini file Mini lines Mini rules Mini size Nano file Nano lines Nano rules Nano size
A Philosophy of Software Design full 370 177 13561 B mini 46 28 5774 B nano 35 17 2258 B
Clean Architecture full 515 289 17782 B mini 49 31 5486 B nano 36 18 2254 B
Clean Code full 297 220 13851 B mini 47 29 3804 B nano 32 14 1235 B
Code Complete full 354 180 12407 B mini 56 38 6717 B nano 41 23 2544 B
Designing Data-Intensive Applications full 393 205 16084 B mini 55 37 6949 B nano 34 16 2575 B
Domain-Driven Design full 979 523 42424 B mini 48 30 5683 B nano 39 21 2266 B
Domain-Driven Design Distilled full 317 158 11351 B mini 56 38 6438 B nano 41 23 2535 B
Implementing Domain-Driven Design full 337 177 12848 B mini 57 39 7333 B nano 37 19 2723 B
Patterns of Enterprise Application Architecture full 404 196 15501 B mini 54 36 8099 B nano 35 17 2823 B
Refactoring full 433 242 17866 B mini 49 31 5167 B nano 37 19 1986 B
Release It! full 382 204 13542 B mini 48 30 6372 B nano 38 20 2205 B
The Pragmatic Programmer full 359 179 13398 B mini 65 47 7165 B nano 44 26 2263 B
Working Effectively with Legacy Code full 371 193 13817 B mini 50 32 5707 B nano 35 17 1792 B
Refactoring.Guru full 765 478 62561 B mini 64 46 6287 B nano 41 23 2593 B

Books List

A Philosophy of Software Design

Author: John Ousterhout

The book focuses on fighting complexity through deep modules, simple interfaces, information hiding, and design choices that reduce cognitive load. This rule set is especially useful for API design, module design, and refactoring shallow abstractions.

Clean Architecture

Author: Robert C. Martin

The book describes designing systems around stable boundaries, the dependency rule, and the separation of business policies from details such as frameworks, databases, and UI. This rule set helps keep code resistant to technology churn.

Clean Code

Author: Robert C. Martin

The book focuses on readability, naming, small functions, responsibilities, tests, and simplicity. This rule set is a strong default for everyday coding and code review.

Code Complete

Author: Steve McConnell

The book covers a broad range of software construction practices: routine design, variables, classes, control flow, defensive programming, coding standards, and testing. This rule set helps agents make disciplined implementation decisions.

Designing Data-Intensive Applications

Author: Martin Kleppmann

The book covers reliability, scalability, consistency, replication, partitioning, transactions, data streams, and schema evolution. This rule set is intended for systems where data ownership, event flows, and consistency semantics matter.

Domain-Driven Design

Author: Eric Evans

The book introduces domain modeling, ubiquitous language, bounded contexts, tactical patterns, and strategic design. This rule set helps agents think in terms of the business model rather than tables, controllers, or DTOs.

Domain-Driven Design Distilled

Author: Vaughn Vernon

The book is a short, practical introduction to DDD. It focuses on subdomains, bounded contexts, context mapping, and basic tactical patterns. This rule set is a good fit when you want the benefits of DDD without excessive ceremony.

Implementing Domain-Driven Design

Author: Vaughn Vernon

The book shows how to apply DDD in real systems: aggregates, domain events, contexts, integrations, and application architecture. This rule set is more implementation-focused than domain-driven-design-distilled.

Patterns of Enterprise Application Architecture

Author: Martin Fowler

The book catalogues enterprise application patterns: layers, service layer, transaction script, domain model, data mapper, repository, unit of work, identity map, DTO, and integration patterns. This rule set helps choose an appropriate pattern instead of mixing responsibilities accidentally.

Refactoring

Author: Martin Fowler

The book describes safe ways to improve code structure without changing observable behavior. This rule set emphasizes small steps, tests, code smell detection, and keeping refactoring separate from feature changes.

Refactoring.Guru

Source: Refactoring.Guru

The site provides a practical refactoring process, code smell catalog, and catalog of refactoring techniques. This rule set is useful when an agent needs to diagnose smells, choose a safe treatment, preserve behavior, and stop before cleanup turns into uncontrolled redesign.

Release It!

Author: Michael T. Nygard

The book focuses on systems that survive production reality: failures, overload, timeouts, retries, circuit breakers, bulkheads, backpressure, observability, and deployment behavior. This rule set is useful for services, APIs, queues, integrations, and critical production paths.

The Pragmatic Programmer

Authors: Andrew Hunt, David Thomas

The book describes a pragmatic approach to software development: responsibility, DRY at the knowledge level, orthogonality, automation, fast feedback, prototyping, and adaptability. This rule set works well as a general engineering layer.

Working Effectively with Legacy Code

Author: Michael Feathers

The book explains how to safely change difficult, poorly tested code: characterization tests, seams, dependency breaking, sprout method, wrap method, and incremental risk reduction. This rule set is best for legacy work where the first goal is regaining control.

For choosing rule sets, skills, and delivery patterns, see USAGE.md. For combining multiple books, see COMPATIBILITY.md. For the book extraction workflow, see ADDING_THE_BOOK.md.

Does it work?

The first validation experiment used vibe-coded-crap, a deliberately generated helpdesk CLI project. The project as vibe-coded application generated with Codex, GPT-5.4 mini, reasoning medium, through continuous development across 80 tasks from BACKLOG.md. The project exists specifically for testing different AGENTS.md files and skills in refactoring workflows.

The experiment compared two separate refactors of the same application, both focused on A Philosophy of Software Design:

# OBEY A Philosophy of Software Design by John Ousterhout

For each branch, Codex first generated a PLAN.md refactoring plan with GPT-5.5, reasoning extra high. The full plan was then executed with the same model, reasoning high. The resulting codebases were passed to ChatGPT with the prompt: “which code better implements the principles from A Philosophy of Software Design, and by how much?”

ChatGPT rated the mini rules refactor at roughly 74/100, versus 46/100 for the branch that only mentioned the book. The result suggests that listing concrete rules from the book is more effective than merely naming the book when the goal is to make an agent apply the author's design principles during refactoring.

The result should be treated as an early qualitative signal, not a benchmark. A secondary Reek code-smell check showed only a small difference in generic static-analysis output: the original branch had 1083 detected smells, while the mini refactor had 1077. This suggests that the advantage of the mini rules did not show up clearly in raw smell counts. In this experiment, the difference was more visible in architectural judgment: module depth, responsibility boundaries, information hiding, and whether the refactor reduced the amount of code a reader needs to understand at once.

Deeper measurements and equivalent experiments for other books are not planned at this stage because they would require substantial token budget and a large amount of manual review time.

Important Note

These rules are inspired by the books listed above. They are not official materials from the authors or publishers, and they are not a substitute for reading the books.

The files in this repository are practical engineering instructions written for AI coding tools. They intentionally avoid reproducing book text. Use them as lightweight working agreements, not as summaries or study notes.

FAQ

What are AI coding agent rules?

AI coding agent rules are project-level instructions that guide tools like Codex, Cursor, Claude Code, and GitHub Copilot when generating, reviewing, or refactoring code.

What are AI coding agent skills?

AI coding agent skills are task-specific instruction packs that agents load only when a workflow needs them, such as refactoring, reviewing, legacy-code changes, reliability work, or domain modeling.

What is AGENTS.md?

AGENTS.md is a Markdown file used to give coding agents project-specific instructions, workflows, constraints, and coding standards.

Can I use these as Claude Code rules or skills?

Yes. You can copy selected rule sets into CLAUDE.md as project memory or turn a focused mini rule set into a Claude Code skill.

Can I use these as Cursor rules?

Yes. You can adapt the rule sets into Cursor project rules or keep them as AGENTS.md-style instructions.

Can I use these as GitHub Copilot custom instructions or skills?

Yes. The rules and skills are plain Markdown and can be adapted into GitHub Copilot custom instructions, prompt files, or reusable task-specific guidance.

Related searches

AI coding agent rules, Agent skills, AGENTS.md examples, Claude Code rules, Cursor rules, Codex rules, GitHub Copilot custom instructions, CLAUDE.md, software engineering rules for AI coding assistants, Clean Code rules for AI, Refactoring rules for AI agents, Domain-Driven Design rules, Clean Architecture rules.

License

The code and rules in this repository are released under the MIT License.

See LICENSE for details.

Author

Maciej Ciemborowicz

Frequently asked questions

Is agent-rules-books free to use?

agent-rules-books is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does agent-rules-books do?

AGENTS.md rules / skills for AI coding agents: Codex, Cursor & Claude Code. Inspired by Clean Code, Refactoring, DDD, Clean Architecture and DDIA programming bo

What is agent-rules-books written in?

agent-rules-books's source is publicly available at https://github.com/ciembor/agent-rules-books, with 3,170 GitHub stars.