Skip to content
AI Security

Your agent may be reading the wrong instruction file: AGENTS.md, CLAUDE.md and the 2026 myths

Antigravity does not read .antigravity.md, Aider does not load AGENTS.md on its own, and a forgotten CLAUDE.md switches off your AGENTS.md. What the official docs say in October 2026.

Why it matters

The security rule you wrote for the agent only applies if the agent loads the file. Going through each tool's official documentation in October 2026, I found advice going around that simply does not work.

The most common myths

"Antigravity reads .antigravity.md." It does not. The Antigravity docs list AGENTS.md, GEMINI.md and rules in .agents/rules/*.md. Rules in that folder need trigger frontmatter; without it, the rule is dropped silently. Run agy inspect to see what loaded.

"Claude Code ignores AGENTS.md." That used to be true. Since version 2.1.277 it reads AGENTS.md when there is no CLAUDE.md in the folder or above. If a CLAUDE.md, or even a CLAUDE.local.md, exists, it wins and AGENTS.md is left out. To load both, put @AGENTS.md on the first line of CLAUDE.md.

"Aider reads AGENTS.md." The Aider docs only load files you pass with --read or list under read: in .aider.conf.yml.

"Zed reads AGENTS.md." It does, but it uses the first file it finds in a list that starts at .rules and goes through .cursorrules and .windsurfrules before AGENTS.md. A forgotten .cursorrules wins.

"A Claude Code subagent is just a markdown file." Without name and description frontmatter, the file is treated as documentation and does not load.

"A plain .md file in .cursor/rules works." The Cursor docs say a .md without frontmatter in that folder is ignored. The rule has to be .mdc.

Less is more

An ETH Zurich study (2026) compared agents with no context file, an AI-generated one and a human-written one. The AI-generated file lowered the success rate and raised cost by over 20%. Write it yourself, short, with only what the agent cannot find by reading the code.

Check in 2 minutes

  • Claude Code: /context shows the loaded memory files.
  • Antigravity: agy inspect.
  • Others: start the session with "list the project instructions you loaded" and check that your security rule shows up.

The RET Promptbook keeps the per-tool path table checked against the official documentation as of October 2026.

Sources

  • Official documentation: Antigravity Rules, Claude Code memory, Aider conventions, Zed instructions, Cursor rules
  • InfoQ coverage of the ETH Zurich study on context files (March 2026)
Tags:#AGENTS.md#CLAUDE.md#Antigravity#Claude Code#Cursor#coding agents
Gabriel Ferreira
Gabriel Ferreira

Founder & Lead Pentester

Gabriel Ferreira reviews production SaaS with focus on login, billing, data, and evidence founders can act on.

How much does it cost to test your system?

Answer four questions and see the package, price and timeline for your case, no sign-up. We refund 50% if the test finds no flaw.

See price and timeline for my case
Keep reading
View all