AGENTS.md and Cross-Tool Conventions

Development teams increasingly use multiple AI coding agents across their workflows. One developer might prefer Claude Code for architecture work while another uses Cursor for rapid iteration. This proliferation created a fragmentation problem.

The emergence of AGENTS.md

By early 2025, projects needed separate configuration files for each tool:

• Claude Code required CLAUDE.md
• Cursor used .cursorrules
• GitHub Copilot expected .github/copilot-instructions.md

AGENTS.md emerged as a vendor-neutral, cross-tool standard for providing project context to AI coding agents. By December 2025, the Linux Foundation announced the Agentic AI Foundation (AAIF) to steward the standard alongside other interoperability standards.

As of January 2026:

• Over 60,000 open-source repositories include AGENTS.md files
• More than 25 AI coding tools support the format natively
• Founding members include Anthropic, AWS, Google, Microsoft, and OpenAI

How AGENTS.md works

AGENTS.md is a plain Markdown file placed at the repository root. There is no required schema, no JSON configuration, and no proprietary syntax just natural language instructions in standard Markdown format.

File discovery and hierarchy

Tools supporting AGENTS.md follow a hierarchical discovery pattern:

1. Global scope: ~/.codex/AGENTS.override.md (if present), otherwise ~/.codex/AGENTS.md
2. Repository root: /repo/AGENTS.md
3. Subdirectories: /repo/src/AGENTS.md, then /repo/src/services/AGENTS.md

Files are concatenated in order, with closer directories taking precedence.

The override mechanism

AGENTS.md includes a feature absent from CLAUDE.md: the AGENTS.override.md file. In any directory, if both files exist, the override file replaces not supplements the standard file.

This handles temporary situations:

• Release freezes requiring stricter change controls
• Incident response requiring specific protocols
• Team rotations requiring different contact information

Recommended content

• Commands Build, test, and deployment with exact flags: npm test -- --coverage --bail
• Testing Frameworks, coverage requirements: "Use vitest; maintain 80% coverage"
• Architecture Project structure, key directories: "src/api/ handles all REST endpoints"
• Boundaries Always do, ask first, never do: "Never modify vendor/ or generated/"

The three-tier authority structure

Effective AGENTS.md files define three tiers of agent authority:

## Boundaries

### Always do
- Run tests before committing
- Update related documentation when modifying APIs
- Use TypeScript strict mode

### Ask first
- Modifying configuration files
- Adding new dependencies
- Changes affecting multiple packages

### Never do
- Commit secrets or credentials
- Modify files in vendor/ or generated/
- Delete database migration files

This transforms ambiguous situations into explicit decisions.

AGENTS.md versus CLAUDE.md

Current interoperability status

Claude Code does not natively support AGENTS.md as of January 2026. Two workarounds:

Import approach:

# CLAUDE.md

@AGENTS.md

## Claude-specific additions
Additional guidance specific to Claude Code workflows...

Symlink approach:

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .cursorrules
ln -s AGENTS.md .github/copilot-instructions.md

Codex configuration beyond AGENTS.md

Codex supports additional configuration through ~/.codex/config.toml:

# Alternative filenames when AGENTS.md is missing
project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md", ".agents.md"]

# Maximum combined size of all instruction files (default: 32 KiB)
project_doc_max_bytes = 65536

Choosing a portability strategy

Consolidation works best for small teams using one or two tools. Use AGENTS.md as the canonical source and create minimal shims for tools requiring specific filenames.

Tool-specific files make sense when tools genuinely benefit from different guidance. AGENTS.md holds shared conventions while CLAUDE.md contains Claude-specific patterns.

The deciding factor: does tool-specific content actually improve outcomes? Generic instructions that apply equally to all tools belong in the shared AGENTS.md.