RFC 2119 for AGENTS.md: Make Your Agent Rules Compact and Strict - Welcome

Skip to content

Contents

The Problem with Prose

The RFC 2119 Vocabulary

Before and After

A Full Example

What This Buys You

Most AGENTS.md and SKILL.md files I have seen — including my own — read like onboarding documents for a new colleague.<br>Long paragraphs, friendly explanations, gentle suggestions.<br>That style fights against what these files are actually for: telling an LLM what it MUST do and what it MUST NOT do.

The idea for the fix was born in a workshop by Adam Bien.<br>He did not propose it directly — he mentioned RFC 2119 in passing, alongside a broader point: old, boring, widely-cited standards are deeply absorbed into every LLM.<br>You do not need to explain them.<br>Drop the name and the model already knows the rules, the vocabulary, and the conventions that go with it.<br>RFC 2119 is exactly that kind of standard.<br>Write your agent instructions in its style — and just mention "RFC 2119" once in the file — and you get the IETF’s decades of precision for free.

The Problem with Prose

Prose instructions have two failure modes when an LLM reads them.

First, intent gets buried .<br>"It would be great if you could try to use AsciiDoc source blocks where possible" is a polite request to a human and a coin flip to a model.<br>Is it a rule? A preference? Optional? The LLM has to guess.

Second, files grow without bound .<br>Every time the agent does something wrong you add another paragraph explaining context, rationale, exceptions — and maybe an example or two for good measure.<br>Six months later the file is 400 lines of well-meaning suggestions and the model misses half of them.

The RFC 2119 Vocabulary

RFC 2119 defines a tiny set of keywords with precise meanings:

MUST / MUST NOT — absolute requirement / prohibition

SHOULD / SHOULD NOT — strong recommendation; deviate only with good reason

MAY — truly optional

That is the whole vocabulary.<br>Five keywords, written in ALL CAPS so they stand out both to readers and to the model’s attention.

Before and After

Here is a typical prose rule from an early version of my CLAUDE.md:

When writing blog posts please make sure to use AsciiDoc format with<br>a `.adoc` extension. Every page needs YAML front matter at the top,<br>delimited by three dashes. The directory name should follow the<br>pattern of date plus slug, and the slug should be descriptive,<br>lowercase, and use hyphens between words.

Four sentences, friendly tone, easy to skim past.<br>Rewritten with RFC 2119 keywords:

- You MUST write all content in AsciiDoc (`.adoc`)<br>- You MUST start every page with YAML front matter delimited by `---`<br>- You MUST name post directories `YYYY-MM-DD-slug` under `content/blog/posts/`<br>- You MUST use a descriptive, lowercase, hyphenated slug

Same rules. Fewer words. No ambiguity.<br>The MUST keyword tells the model — and any future me — that these are not negotiable.

A Full Example

The CLAUDE.md that drives this very blog is written entirely in this style.<br>A short excerpt from the content section:

- You MUST write all content in AsciiDoc (.adoc)<br>- You MUST use AsciiDoc section syntax (==, ===) for headings — NOT<br>Markdown (#)<br>- You MUST use AsciiDoc source blocks for code and You MUST always<br>specify the language<br>- You SHOULD prefer `layout: :theme/post` for posts, `layout:<br>:theme/page` for standalone pages<br>- You MUST NOT duplicate author data in front matter when the author<br>key can reference data/authors.yml

Notice the mix.<br>MUST for structural rules the build will break on.<br>SHOULD for things I want but can be relaxed for one-offs.<br>MUST NOT for the failure mode I actually want to prevent.

The model picks up the gradient.

What This Buys You

Three things change when you rewrite an AGENTS.md or SKILL.md file this way.

Compactness.<br>The file shrinks.<br>My CLAUDE.md got noticeably shorter in the rewrite without losing a single rule.<br>Shorter context means more room for the actual task.

Easier review.<br>When every rule starts with one of five keywords, you can scan the file and immediately see what is a hard rule versus a preference.<br>Adding a new rule forces you to pick a keyword, which forces you to decide how strict it really is.

Share:<br>X / Twitter<br>Bluesky