AGENTS.md

AGENTS.md is a standardized, file-based configuration format for defining AI agent behaviors, constraints, and tool-access directly within a codebase. It acts as a manifest that allows different agentic runners (like Claude Code, GitHub Copilot, or OpenCode) to understand their mission and boundaries without vendor lock-in.

My Opinion

The “LLM King of the Hill” game is a carousel. 2024 and 2025 showed us that the lead rotates between OpenAI, Anthropic, and Google every few months. If you bake your agent instructions into a proprietary platform’s UI, you are trapped when a better model debuts elsewhere.

Agentic systems are the new runtime. Just as we don’t write code that only runs on one brand of CPU, we shouldn’t write agent instructions that only live in one provider’s ecosystem. AGENTS.md is the abstraction layer we desperately need.

The Power of Hierarchy

One of the strongest arguments for this format is contextual scoping. By placing different instructions at different levels of your directory tree, you prevent “instruction bloat” and keep the agent focused on the task at hand.

Example Structure:

project-root/
├── AGENTS.md (Global: Coding style, PR rules)
├── backend/
│   ├── AGENTS.md (Spring constraints, PostgreSQL rules...)
│   └── src/
└── frontend/
    ├── AGENTS.md (React, Tailwind, Astro conventions...)
    └── src/

The Maintenance Tax

The counterpart is the discipline required. Documentation is notoriously the first thing to rot. However, unlike traditional docs, AGENTS.md has a direct impact on agent performance.

Some agentic providers such as Claude Code suggest keeping these files under 500 lines. This forces a “Documentation-as-Code” mindset where you must architect your instructions into modular “skills.” It’s extra effort, but the payoff is a massive reduction in token waste and a significant jump in agent accuracy.

The Tool Compatibility

Not all AI tools support AGENTS.md equally:

• Claude Code: Native support, reads and respects instructions
• OpenCode: Full support with model flexibility
• Cursor: Partial support via .cursorrules (similar concept)
• Gemini CLI: No support—sessions are stateless
• AntiGravity: Unknown, but likely Google-specific configuration

The format is most valuable when you work across multiple tools or expect to switch providers.

Conclusion

Without doubt, AGENTS.md is the emerging standard to document and maintain AI agent instructions. Use it without moderation. Visit agents.md to learn more and see examples.

See AntiGravity for my thoughts on Google’s IDE, which heavily relies on agentic workflows.
Or my Cloudflare migration post where I used AGENTS.md to guide an AI agent through a complex infrastructure migration.