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 right now 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 supported by many tools (Codex, Cursor, Copilot, Gemini CLI, Windsurf, Zed) — one config file for many agents. Many teams keep both: CLAUDE.md for Claude Code, AGENTS.md for the rest, or cross-import so they do not drift.
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: rules crammed into one giant file that eats the context window (token bloat) and dilutes the model; or a rule buried 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 (an @-import in CLAUDE.md); anything left to a router is best-effort. Adding more is not the same as placing it right.
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 its signals. 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 yourself?
AkiDevRule is an open-source (MIT) baseline that does this for Claude Code and Antigravity: one install command gives you a self-routing rule corpus (four core files always loaded via @-import, the rest read on signal match) 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 role-collapse, curbing sycophancy, and gating when an agent council activates. Read more in a fix for sycophancy and the agent-council activation gate.