Rules for AI Coding Agents: CLAUDE.md, AGENTS.md, and Agent Skills
Rules for AI coding agents are files like CLAUDE.md, AGENTS.md, and Agent Skills that keep an agent on your architecture and cut repeat prompts. Why cramming too many rules backfires, and how to do it right.
Rules for AI coding agents are the persistent instructions you set so a coding agent (Claude Code, Cursor, Codex, Antigravity) stays on your architecture, conventions, and build/test commands instead of being re-told every session. The three most common forms are the CLAUDE.md file, the AGENTS.md file, and Agent Skills. All three aim at one thing: injecting deterministic rules into an otherwise non-deterministic agent.
How do CLAUDE.md and AGENTS.md differ?
CLAUDE.md was popularized by Claude Code: a markdown file at the repo root that supplies project context, build/test commands, and behavior constraints. AGENTS.md is a cross-tool standard that many tools read directly, such as Codex, Cursor, Copilot coding agent, Windsurf, Kiro, and Antigravity: one file for many agents.
Two easy mix-ups. Claude Code reads only CLAUDE.md, not AGENTS.md (per Anthropic's memory docs). Gemini CLI reads GEMINI.md by default and reads AGENTS.md only when you configure it. That is why many projects keep a CLAUDE.md whose first line is @AGENTS.md, or keep two identical files, so the tools do not drift apart.
Why do too many rules make an agent worse?
A common complaint is "the AI ignores my rules". The root cause is usually one of two opposite mistakes: cramming every rule into one giant file that eats the context window (token bloat) and dilutes the model; or burying a rule in a skill that never runs, so it is never loaded at all.
The principle: a rule that must always hold belongs where it always loads, such as an @-import in CLAUDE.md. A rule left to a router is best-effort, because reading it still depends on the model's decision. The price of the always-loaded spot is that every file there is billed on every session, including sessions that touch no code, so only rules that truly must hold every time earn a place there. Adding more is not the same as placing it right.
@~/.aki/akidevrule/index.md
@~/.aki/akidevrule/RULE-agent-behavior.md
@~/.aki/akidevrule/RULE-coding.md
@~/.aki/akidevrule/RULE-pattern-core.md
@~/.claude/skills/akirule/SKILL.mdThat block is the top of AkiDevRule's ~/.claude/CLAUDE.md: one path per line, and Claude Code loads each file when the session starts.
Agent Skills: load rules on demand, not all at once
Agent Skills solve token bloat with progressive disclosure: the agent keeps only a short description of each skill on hand and loads the full body only when a task matches. A router reads the signals in a request and then pulls exactly the rule needed, keeping context lean while still applying the law.
How do you get a good rule baseline without building it from scratch?
AkiDevRule is an open-source (MIT) baseline that does this for Claude Code and Antigravity. One install command, npx @akinet/akidevrule@latest, gives you a self-routing rule corpus: five files always loaded (index.md, the three core rule files, and the akirule router), the rest read only when a task matches, plus ten single-purpose skills. It follows exactly the principle above: mandatory law via @-import, contextual law via a router.
Good rules are less about adding law and more about governing the agent: preventing one agent from approving its own work (role collapse), curbing sycophancy, and gating when an agent council activates. Read more in a fix for sycophancy and the agent-council activation gate.