AGENTS.md is seven design decisions in a trench coat. Each one has a token bill.

1. Plain markdown only

The spec page is explicit: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." No YAML frontmatter, no JSON Schema, no XML wrapper. The decision is one line in the spec and one entire class of features deleted.

The trade-off is real. Frontmatter would have let you tag a rule as "only fire when editing TypeScript" or "only inject for subagents". Without it, every line of your AGENTS.md fires for every task, on every turn, for every tool call. The token cost of that decision scales linearly with file size: a 4,000-token AGENTS.md that could have been split with frontmatter is 4,000 tokens injected unconditionally instead of 800 tokens injected conditionally.

The benefit, also real, is that any tool that can read a markdown file can read AGENTS.md the day it ships. No parser version, no validator, no migration. That is the trade.

2. Single root file, not a directory

Cursor stores rules in .cursor/rules/*.mdc, one file per concern, with explicit glob patterns. Anthropic ships skills as .claude/skills/<name>/SKILL.md, loaded on demand. AGENTS.md rejected both shapes: one file, one place, no manifest.

The token consequence is that AGENTS.md cannot do conditional load. Every byte you put in the file is a byte the host can choose to include in every prompt. There is no metadata that lets a host say "skip the database section for this task". That is the price of one place to read.

The benefit is auditability. If the file is one file, you can read it. If it is a directory of fifteen .mdc files with glob scopes, you have to mentally execute the loader to know what the model will see. For a deeper look at this drift, see AGENTS.md host context drift.

3. No required fields, no schema

You can ship an AGENTS.md that is one line. You can ship one that is 1,200 lines and starts with a poem. Both pass. There is no validator because there is nothing to validate against. The spec authors say this in plain text on the homepage: "The beauty of agents.md is its flexibility, there are no required fields."

That decision pushes all responsibility for what makes a good AGENTS.md onto the writer. There is no "your file is malformed" error. The file is whatever you wrote. The closest thing to a standard rubric in public is Karpathy's 12-rule list for what a useful agent-config file should contain. ccmd applies that rubric to any AGENTS.md paste and reports the pass count. The first time most people audit their file they score 2 or 3 out of 12, because the spec never told them what good looked like.

4. The name "AGENTS.md" (plural, all caps, not vendor-specific)

The plural noun is a deliberate signal: the file is for any agent that wants to read it, not for one specific product. The all-caps convention matches README.md and CONTRIBUTING.md, which the spec authors explicitly cite as the precedent. The decision to not use AI.md, BOT.md, or CONTRIBUTING-AI.md was about adoption: the name has to be visually distinct from human docs but read like a peer to README.

The cost is no vendor-specific signal in the filename. Compare with CLAUDE.md, which ties the file to Anthropic, or .cursorrules, which ties the file to Cursor. AGENTS.md is the only filename a repo can ship that any compliant tool reads, which is also the only filename ccmd's detector finds without help. As of the Linux Foundation announcement in December 2025, over 60,000 open-source projects already ship one.

5. Nested files concatenate, they do not replace

This is the one Codex-specific decision in the list. OpenAI's docs describe it directly: "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt."

The mechanism is loader order, not file precedence. There is no "subdirectory file wins" rule in the spec. There is just "later in the prompt wins because LLMs weight later instructions higher." The token consequence is that the prompt grows linearly with how deep in the directory tree you are working. Open a file in src/billing/refunds/ in a repo with AGENTS.md at every level and Codex injects four AGENTS.md bodies into the system prompt, joined by blank lines.

Cursor and Claude Code do not implement this concatenation. A subdirectory-only AGENTS.md is invisible to them. That is one of the most common drifts we see when teams ship multiple AGENTS.md files and assume every tool reads them. See AGENTS.md and CLAUDE.md import drift for a worked example.

6. The 32 KiB default cap

OpenAI Codex truncates AGENTS.md at 32 KiB by default, controlled by the project_doc_max_bytes setting. The docs note that you should "raise the limit or split instructions across nested directories when you hit the cap."

32 KiB at the standard 4-chars-per-token estimate is about 8,000 tokens. If your AGENTS.md is at the cap and fires every turn through Codex, that is roughly 8,000 input tokens per turn. On a 30-turn uncached session at Opus 4.7's $15 per million input rate, that is about $3.60 for the system prompt alone. The cap exists because the spec authors knew people would write 50 KiB AGENTS.md files; the truncation forces a quality conversation instead of a silent bill. If you have not measured your file's size, paste it into the analyzer at the homepage and read the totalTokens number. More on that calibration step in AGENTS.md token audit cost.

7. No @-import in the base spec

Anthropic's CLAUDE.md supports @path/to/file.md imports up to a five-hop recursion limit. A one-line CLAUDE.md that just says @AGENTS.md is a complete CLAUDE.md as far as the loader is concerned. AGENTS.md itself has no equivalent. The spec is the file contents; the file contents are the spec.

The trade is composition vs simplicity. Imports would have given you a DRY mechanism (write shared rules once, reference them from many AGENTS.md files). The cost would have been a parser, a hop limit, a cycle-detection rule, and a resolution model that every host has to re-implement. The decision was to skip all of that and let users either inline (copy-paste, accept drift) or rely on nested-directory concatenation (Codex-specific). For shops that want both, the common pattern is to maintain AGENTS.md as the source of truth and ship a one-line CLAUDE.md that imports it. The wrapper stays one line; the analyzed body is the AGENTS.md.

What ccmd's analyzer inherited from these decisions

When the analyzer reads a paste, the format-detection routine treats AGENTS.md, CLAUDE.md, .cursorrules, and .grokrules as different labels on the same underlying problem. The reason is decision 3: the spec has no schema, so there is nothing format-specific to score against. The rubric and the per-line findings apply to all four.

That is the design decision behind the analyzer: the label on the report is cosmetic. The real audit, the 12-rule rubric and the per-line bloat and aspirational and missing-why checks, is format-agnostic. The same way AGENTS.md itself is.