AGENTS.md

One file that tells AI agents how to behave in your repository.

What Is AGENTS.md?

AGENTS.md is a convention for documenting how AI agents should interact with your project. Like README.md for humans, but for agentic tools.

Place an AGENTS.md file in your repository root. AI agents (OpenAI Codex, Claude Code, Cursor, and others) read it automatically at the start of each session.

Quick Start (30 Seconds)

Create a file named AGENTS.md in your project root:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# AGENTS.md

## Commands
- Test: `npm test`
- Lint: `npm run lint`

## Rules
- Ask before adding dependencies
- Run tests when modifying logic
- Prefer small, focused changes

Commit it:

1
2

git add AGENTS.md
git commit -m "Add AGENTS.md"

Done. Agents will now follow these rules automatically.

Why This Matters

  • Stop repeating yourself — Document conventions once, agents remember them
  • Consistent output — Same code style, testing rules, and guardrails every session
  • Faster onboarding — New agents understand your project immediately
  • Better than skills — Vercel’s evals show AGENTS.md beats skills on formatting reliability

Vercel research found that compact files with clear rules outperform long, detailed manuals.

Next Steps

Choose your path:

I want to…Go to…
Get a complete template for my stack/agents/agents-md/#templates-by-use-case — Python, TypeScript, or documentation templates
Understand why this works/posts/agents-md-practical-guide/ — Evidence-based deep dive
Set up a monorepo/agents/agents-md/#hierarchical-loading-monorepos — Multi-package configuration
Use multiple AI tools/agents/agents-md/#multi-tool-setup — One config, multiple editors
Avoid common mistakes/agents/agents-md/#common-mistakes-to-avoid — What not to do

Tool Support

ToolConfiguration FileNotes
OpenAI CodexAGENTS.mdNative support, merging behavior
Claude CodeCLAUDE.mdSame format, hierarchical loading
Cursor.cursorrules or .cursor/rules/*.mdcNative AGENTS.md support in recent versions
OpenCodeAGENTS.mdNative support with CLAUDE.md fallback
ZedAGENTS.mdNative support
GitHub Copilot.github/copilot-instructions.mdDifferent filename, same concept

Most tools support symlinks—use AGENTS.md as your canonical source, link to it from tool-specific filenames.

AGENTS.md vs CLAUDE.md

Same format, different names:

  • AGENTS.md — Used by OpenAI Codex, Cursor, OpenCode, Zed
  • CLAUDE.md — Used by Claude Code

Practical difference: Almost nothing. Use AGENTS.md as your canonical file, symlink CLAUDE.md → AGENTS.md if you use Claude Code.

Security Considerations

Never include in AGENTS.md:

  • API keys or secrets
  • Database credentials
  • Internal URLs or endpoints
  • Personal access tokens

Agents read these files before every task. Treat AGENTS.md like code—commit it, review it, keep it safe.

Best practices:

  • Use .gitignore patterns to exclude secrets files
  • Reference environment variables instead of hardcoding values
  • Keep AGENTS.md under version control for team consistency

For detailed security analysis: See AGENTS.md Security Best Practices and OpenClaw Security Risks

Full Documentation

/agents/agents-md/ includes:

  • Copy-paste templates for Python, TypeScript, and documentation projects
  • Tool comparison: AGENTS.md vs CLAUDE.md vs .cursorrules
  • Monorepo setup with hierarchical loading
  • Common mistakes to avoid
  • Multi-tool configuration strategies
  • Advanced patterns (global config, overrides)

/posts/agents-md-practical-guide/ — Evidence-based deep dive:

  • What actually works in production
  • Tool-specific quirks and behaviors
  • Iteration methodology
  • Measuring success

Last updated: 2026-02-07