Usage

May 10, 2026 · View on GitHub

This repository ships three versions of every rule set:

mini: the recommended version for most real task use, especially as a focused skill
nano: the compact fallback for very tight context budgets
full: the complete reference version, best used as reference material for deep skills, audits, and focused sessions

Start Here

Use the smallest mechanism that still changes the agent's decisions.

Start with one primary rule set.
Prefer skills for book-specific guidance. A mini file is usually the right skill body.
Use mini by default when one book should shape the agent's decisions for a specific task.
Use nano only when the rule set must be extremely small, permanently always-on, or portable across tools with tight context budgets.
Use full for audits, one-off deep sessions, skill reference files, or for deriving smaller scoped rules.
Prefer scoped, on-demand, or retrieval-based loading over global loading.
Treat memories as helpers, not as the canonical source of truth.

Delivery Patterns

Pattern	Best for	Repo version	Notes
Skill or command	Refactoring passes, reviews, migrations, reliability work, DDD modeling, legacy changes	`mini`, optionally backed by `full`	Best default for most book-specific guidance.
Always-on project rule	Stable defaults that should affect most tasks	`mini` or `nano`	Use one carefully chosen `mini`; use `nano` if `mini` is too large for the tool or project.
Scoped rule	One directory, file type, or subsystem	`mini` or `nano`	Prefer `mini`; use `nano` for tiny path-scoped reminders.
On-demand rule	Refactoring passes, reviews, migrations, reliability work	`mini`	Invoke only when the task matches.
Retrieval or MCP	Large reference material, changing docs, external systems	`full` or source material outside the prompt	Use when the content is too large or too rarely needed for always-on context.

Skills First

Use skills when the rule set should activate for a kind of work rather than every message in the project.

Good skill candidates:

refactoring.mini.md for a refactoring pass
working-effectively-with-legacy-code.mini.md for risky legacy changes
domain-driven-design.mini.md for modeling-heavy work
release-it.mini.md for production reliability changes
designing-data-intensive-applications.mini.md for data consistency, events, streams, and schema evolution

Recommended skill shape:

project/
  .agents/
    skills/
      refactoring-pass/
        SKILL.md        # derived from refactoring.mini.md
        reference.md    # optional link or copy of refactoring.md

Keep the active skill concise. Put long examples, full rule files, and traceability material in reference files or retrieval, not in always-on project instructions.

mini is the optimal default for most agent work and the best starting point for skills. It usually contains enough of the book's decision pressure, trigger rules, and tradeoff handling to change implementation choices without bringing in the full source.

Use mini when:

you are choosing one primary book for a task, skill, or small project-wide baseline
you want a stable repo-wide engineering bias and the context budget can afford it
the task is a review, refactor, migration, design pass, production fix, or modeling-heavy change
the rule set should prevent subtle shortcuts, not just remind the agent of the headline thesis

Use nano when:

the tool has a very small always-on instruction budget
the same baseline must travel across several editors with different limits
you only need the smallest reminder of a book's bias
mini would compete with more important project-specific context

Use full when:

the skill needs a deep reference file
you are auditing a rule set or deriving a smaller skill
the task is a focused one-off session with enough context budget
you need traceability back to the book's structure and bias

Portable Baseline

If your team uses more than one editor, use a portable baseline:

Keep one canonical AGENTS.md with a single mini rule set when the supported tools can handle it.
Use nano as the portable fallback only when mini is too large for one of the tools.
Let Codex read that file directly.
Let Claude Code import it from CLAUDE.md.
Let Cursor either read AGENTS.md directly for simple projects or translate the same content into .cursor/rules for better scoping.
Add editor-specific on-demand mechanisms next to that baseline instead of duplicating a large global rule file.

This gives you one cross-tool source for the base layer, while still allowing each editor to use its stronger native features.

Codex

Available mechanisms

AGENTS.md in the repo root or nested directories
AGENTS.override.md for closer overrides
.codex/config.toml with model_instructions_file, project_doc_fallback_filenames, and project-scoped config
skills in .agents/skills/ or ~/.agents/skills/
hooks via .codex/config.toml or hooks.json
MCP servers and web search for external context
memories for learned preferences

Preferred setup

Use Codex in two layers:

Use skills for book-specific workflows such as refactoring, legacy changes, production reviews, and domain modeling.
Put one mini rule set in the project layer only when you want a book to shape most tasks.
Fall back to nano only when the always-on project layer must stay extremely small.

Preferred order:

Turn procedures, checklists, and book-specific workflows into skills.
Use root AGENTS.md for the project-wide base layer.
Use model_instructions_file if you want Codex to point at a chosen file without renaming it to AGENTS.md.
Add nested AGENTS.md or AGENTS.override.md only where a subtree genuinely needs different pressure.
Use MCP or retrieval for large reference corpora instead of stuffing them into the always-on file.

Recommended version mapping

mini: preferred skill body; also usable as project-wide default in AGENTS.md or model_instructions_file
nano: compact fallback for very tight always-on budgets
full: skill reference, audit source, or focused-session reference

Recommended structure

project/
  AGENTS.md
  .agents/
    skills/
      refactoring-pass/
        SKILL.md
  services/
    payments/
      AGENTS.override.md

Use Codex this way when

you want a stable repo-wide engineering bias
some subtrees need different guidance
a workflow is repeatable enough to deserve a skill

Avoid

loading several full files globally
putting long procedures into AGENTS.md
using memories as the primary place for shared rules

Claude Code

Available mechanisms

CLAUDE.md or .claude/CLAUDE.md
CLAUDE.local.md for private local additions
@path imports inside CLAUDE.md
.claude/rules/ for scoped project rules
.claude/skills/<name>/SKILL.md
subagents
hooks in settings or scoped to skills
MCP resources and prompts
auto memory

Preferred setup

Claude Code works best with a small root memory file plus scoped additions.

Preferred order:

Keep root CLAUDE.md short.
If you want one shared cross-tool base file, put the chosen repo file at AGENTS.md and import it from CLAUDE.md.
Use Claude Code skills for book-specific workflows.
Use one mini rule set for always-on project context when the file stays short enough for the team.
Use .claude/rules/ or path-scoped skills for mini.
Use nano only when the shared root file has to be much smaller.
Put procedures, large checklists, and long references into skills instead of the root CLAUDE.md.
Use disable-model-invocation: true for side-effectful manual workflows such as deploy or release flows.
Use subagents or context: fork skills when a side task would otherwise flood the main context.

Recommended version mapping

mini: preferred .claude/skills/ body; also usable in .claude/rules/ or a short imported base file
nano: compact fallback for very tight root context
full: skill reference, audit source, or narrowly imported file for a specific session

Recommended structure

project/
  AGENTS.md
  CLAUDE.md
  .claude/
    rules/
    skills/

Example CLAUDE.md:

Import the shared root AGENTS.md baseline by adding this line to CLAUDE.md in order to reuse the same project-wide rules in Claude Code.

@AGENTS.md

## Claude Code

- Use skills for long procedures and checklists.
- Use scoped rules for subsystem-specific guidance.

Use Claude Code this way when

you want a cross-tool base layer plus Claude-specific scoping
a rule only matters in one subsystem
a rule has become a procedure rather than a fact

Avoid

pasting a long full rule file into root CLAUDE.md
mixing many conflicting imports
relying on auto memory instead of reviewed project instructions

Cursor

Available mechanisms

.cursor/rules/*.mdc project rules
rule types: Always, Auto Attached, Agent Requested, Manual
root AGENTS.md as a simple alternative
user rules
@Cursor Rules for explicit rule application
/Generate Cursor Rules
memories
codebase indexing
MCP

Preferred setup

Cursor's strongest native mechanism is .cursor/rules.

Preferred order:

Prefer .cursor/rules over AGENTS.md for serious use.
Use at most one project-wide Always rule derived from mini when it stays small enough.
Turn mini into Agent Requested, Manual, or Auto Attached rules by topic or path.
Use @Cursor Rules when you want explicit on-demand application.
Keep large reference material in attached files, indexed docs, or MCP, not in Always rules.
Use root AGENTS.md only for simple projects or when you want a portable cross-tool baseline.
Use nano only when an Always rule must be extremely short.

Recommended version mapping

mini: short Always rule, simple root AGENTS.md, or Agent Requested, Manual, and Auto Attached project rules
nano: compact fallback for very tight Always rules
full: reference only

Recommended structure

project/
  .cursor/
    rules/
      base.mdc
      payments.mdc
      refactor.mdc
      ddd.mdc

Suggested split:

base.mdc: one short Always rule derived from mini, or from nano if the base must be tiny
payments.mdc: Auto Attached for payments/**
refactor.mdc: Manual for explicit refactoring passes
ddd.mdc: Agent Requested for modeling-heavy tasks

Use Cursor this way when

you want strong scoping and explicit control over context
you want different rules for different subsystems
you want on-demand rule selection without a huge global file

Avoid

using one giant Always rule
treating root AGENTS.md as the best default for complex projects
storing large reference packs in project rules when indexing or MCP is a better fit

Retrieval, MCP, and RAG

Use retrieval-based delivery when the material is too large, too dynamic, or too rarely needed for always-on context.

Good candidates:

multiple books at once
large examples and templates
architecture docs, specs, and runbooks
changing external guidance
domain documents that matter only for some tasks

Recommended by editor:

Codex: skills plus MCP or retrieval-backed tools
Claude Code: skills plus MCP resources or prompts, optionally with subagents
Cursor: scoped project rules plus codebase indexing or MCP

If your team already has a RAG system, keep the long reference material there and only promote decision-changing rules into always-on or scoped prompt rules.

Decision Guide

Need a task-specific book bias: create or invoke a skill from the relevant mini rule set.
Need a steady repo-wide bias: use one mini rule set.
Need an extremely small always-on baseline: use nano.
Need stronger guidance for a specific task: load the relevant mini rule set as a skill or on-demand rule.
Need a multi-step workflow: create a skill or command, with full as optional reference.
Need subsystem-specific pressure: use scoped rules or nested files.
Need long reference material: use retrieval, indexing, or MCP.
Need more than one book: keep one primary always-on rule set and move the rest to on-demand mechanisms.