Answers
Answers: coding agents and their rule files, agent by agent
Published
Short answers to the questions teams ask about coding agents and their rule files: why an agent skips a rule, how long the file can be, how rules drift, and how to share them across repos. Each page gives the free fix first, quotes the vendor's own docs, and shows the numbers from our study of 3,905 public CLAUDE.md and AGENTS.md files.
Find your agent and problem
Ignores its rule file
Claude Code
Claude Code strips HTML comments from CLAUDE.md, so a rule inside one never loads
Claude Code removes block-level HTML comments from CLAUDE.md before Claude sees it. 5.5% of public CLAUDE.md files have them. Move rules out of comments.
Claude Code
"Read AGENTS.md" in CLAUDE.md does not load it: put @AGENTS.md on its own line
A sentence asking Claude to read AGENTS.md is text, not an import. 14.9% of CLAUDE.md files beside an AGENTS.md do it. Use @AGENTS.md instead.
Gemini CLI and Antigravity CLI
Antigravity CLI skips AGENTS.md in subfolders and drops rule files without a valid trigger
Antigravity CLI loads AGENTS.md and GEMINI.md from where you start up to the repo root, never below, and silently discards .agents/rules files with no trigger.
Windsurf (Devin Desktop)
Windsurf is now Devin Desktop: .devin/rules wins, and only one global_rules.md loads
Windsurf became Devin Desktop on 2 June 2026. Rules in .devin/rules take precedence, and when two global_rules.md files exist only .devin/global_rules.md loads.
Rule file too long
Codex
Codex reads 32 KiB of AGENTS.md and cuts the rest: raise project_doc_max_bytes or trim
Codex stops at 32 KiB of project AGENTS.md files, shared by every file from the root down. 30,080 public AGENTS.md files are over it on their own.
Gemini CLI and Antigravity CLI
Antigravity truncates each rule file at 24,000 bytes and caps always-on rules at 20,000 tokens
Antigravity truncates a rule file above 24,000 bytes and gives global and always_on rules a 20,000-token budget. 51,840 public AGENTS.md files are over 24 KiB.
GitHub Copilot
Copilot code review no longer stops at 4,000 characters of instructions: the limit was removed in June 2026
Copilot code review used to stop reading copilot-instructions.md at 4,000 characters. GitHub removed that limit on 12 June 2026. Length still costs adherence.
Cursor
Keep each Cursor rule under 500 lines and split the rest by file pattern
Cursor’s docs say keep rules under 500 lines. Split a long rule into scoped .cursor/rules files that apply to specific files or when relevant.
Rules drift from the code
Claude Code
CLAUDE.md and AGENTS.md drift apart in 7% of repos that copy one into the other: import instead
In repos with both files, 7.0% of CLAUDE.md files are copies of AGENTS.md that drifted and 6.6% are copies still in step. One @AGENTS.md line ends it.
Claude Code, Codex
Leave the directory tree out of CLAUDE.md and AGENTS.md: it goes stale and the agent can list files itself
16.9% of public CLAUDE.md and 10.5% of AGENTS.md files paste a directory tree. It drifts with every move, and the agent can run ls. Name only surprises.
Share rules across repos and agents
Claude Code
Share CLAUDE.md rules across repos with ~/.claude/rules, a symlinked .claude/rules, or a managed CLAUDE.md
Three documented ways: ~/.claude/rules for one person, a shared folder symlinked into .claude/rules per repo, or a managed CLAUDE.md that IT deploys.
Codex
Codex shares instructions across repos only through ~/.codex/AGENTS.md, one person at a time
Codex loads ~/.codex/AGENTS.md in every project, but OpenAI documents no organization-wide instructions. For a team, sync AGENTS.md into each repo.
GitHub Copilot
Copilot organization instructions reach every repo, but only on GitHub.com and in code review
Organization custom instructions apply across an org’s repos for GitHub.com sessions and code review. GitHub says they are not supported in local sessions.
Gemini CLI and Antigravity CLI
Gemini CLI reads AGENTS.md only if context.fileName lists it; Antigravity CLI reads it by default
Gemini CLI reads GEMINI.md by default. Set context.fileName to ["AGENTS.md", "GEMINI.md"] to share rules with Codex and Cursor. Antigravity reads both.
Windsurf (Devin Desktop)
Share Windsurf rules across repos with ~/.devin/rules, and with other agents through AGENTS.md
Devin Desktop, formerly Windsurf, applies ~/.devin/rules to every project, reads AGENTS.md like Codex and Cursor, and can import .cursor/rules.
Memory between sessions
Gemini CLI and Antigravity CLI
Gemini CLI remembers between sessions by editing GEMINI.md files, in three places
Gemini CLI saves memory by writing Markdown: the repo’s GEMINI.md for the team, a private project folder, and ~/.gemini/GEMINI.md for you.