Claude · Agent · Interview

AGENTS.md Is Not a README: Why AI Coding Tools Need a Rulebook, Not a Welcome Mat

By 洛卡卡了 · Jun 29, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams burning through token budgets and fighting agent misbehavior are usually missing a maintained AGENTS.md. Without it, every session starts from zero, context windows fill with repeated corrections, and agents guess wrong on conventions that were never written down. A concise, team-shared rule file cuts rework and makes AI coding costs predictable.

Summary

AGENTS.md functions as a machine-readable rulebook that AI coding agents load at session start. It specifies build commands, test procedures, naming conventions, forbidden actions, and cross-file change requirements. Tools like Codex, Cursor, and Claude Code all support it, though Claude Code layers its own CLAUDE.md on top and can import AGENTS.md via an @ reference.

Running `/init` scans the project and generates a starter AGENTS.md, but it only captures surface-level structure. It cannot know team conventions, historical pitfalls, or recurring mistakes. The real value comes from ongoing maintenance: every time a developer repeats the same correction in a prompt, that rule should be promoted into AGENTS.md. Claude Code users get an intermediate step through Memory, a local draft notebook that holds temporary lessons before they graduate to the shared rule file.

A 2025 study on LLM instruction-following confirms that agents degrade when overloaded with rules. Effective AGENTS.md files are short, specific, and actionable — "run pnpm lint after changing frontend components" works; "keep code elegant" does not. The file is not a real-time config; changes require a new session to take effect, and Codex enforces a default 32 KiB total size limit across all loaded rule files.

Takeaways

— AGENTS.md is an open standard supported by Codex, Copilot, Cursor, Aider, Zed, JetBrains, and Claude Code.

— README.md explains the project to humans; AGENTS.md gives the agent build commands, test commands, coding rules, prohibitions, and change-linkage requirements.

— Codex builds an instruction chain at startup: global config → project root → current working directory, concatenating AGENTS.md files along the path.

— Codex enforces a default 32 KiB total size limit across all loaded rule files; exceeding it silently truncates later rules.

— AGENTS.md is not a real-time config — changes only take effect in a new session.

— Claude Code uses CLAUDE.md for its own configuration but can import AGENTS.md with an @ reference, keeping general rules in one place.

— Claude Code's Memory mechanism stores local, per-project experience notes; rules that get repeated should be promoted from Memory into AGENTS.md.

— The `/init` command scans project structure, dependencies, and README to generate a starter AGENTS.md, but it only captures surface-level information.

— `/init` works best on projects with stable directory structures and existing code; running it on an empty project produces generic, quickly outdated output.

— Rules worth writing into AGENTS.md are those the agent cannot infer from code, need to be followed long-term, and can be stated as a specific action.

— Vague rules like 'keep code elegant' are ineffective; effective rules specify exact commands or constraints, such as 'run pnpm lint after changing frontend components' or 'do not manually modify generated/.'

— A 2025 study (arxiv 2507.11538) shows LLM instruction-following degrades with too many rules; a short, focused AGENTS.md outperforms an exhaustive one.

— The second time you repeat a correction in a prompt, that rule should be deposited into AGENTS.md (or Memory, for Claude Code users).

Conclusions

Most teams treat AGENTS.md as a one-time generated artifact, but its real function is as a living sink for recurring prompt corrections — a cache that prevents context-window bloat.

The 32 KiB size limit in Codex is a forcing function for discipline: rules that cannot survive truncation were probably too vague to be useful anyway.

Claude Code's Memory-to-AGENTS.md pipeline is an under-documented workflow that mirrors a personal kanban for agent rules — draft locally, promote when stable.

AGENTS.md and CLAUDE.md solve the same problem through competing formats, but the @ reference syntax in Claude Code makes the format war irrelevant for teams willing to maintain one canonical rule file.

Vague rules fail not because agents ignore them, but because they lack a verifiable condition — an agent cannot check whether code is 'elegant,' but it can check whether it ran pnpm lint.

The instruction-following degradation curve means a 50-line AGENTS.md with sharp rules will outperform a 500-line one filled with aspirations.

Concepts & terms

AGENTS.md

An open-standard markdown file placed in a project directory that provides AI coding agents with build commands, test procedures, coding conventions, forbidden actions, and cross-file change rules. Supported by Codex, Copilot, Cursor, Aider, Claude Code, and others.

Instruction chain

The ordered set of rule files an AI coding tool loads at session startup. In Codex, it goes global (~/.codex) → project root → current working directory, concatenating AGENTS.md files with later directories taking priority.

CLAUDE.md

Claude Code's project-level configuration file. It can contain Claude-specific settings like skills and hooks, and can import AGENTS.md via an @ reference to avoid duplicating general project rules.

Memory (Claude Code)

A local, per-project storage mechanism in Claude Code that records temporary lessons and recurring corrections. It acts as a draft layer: rules that prove durable should be promoted from Memory into the shared AGENTS.md.

/init command

A built-in command in tools like Codex that scans a project's structure, dependencies, and README to generate a starter AGENTS.md file. It captures surface-level information but cannot infer team conventions or historical pitfalls.

project_doc_max_bytes

A Codex configuration setting (default 32 KiB) that limits the total size of all loaded AGENTS.md and related rule files. Exceeding it causes silent truncation of later rules.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗