AGENTS.md is a vendor-neutral configuration file created in July 2025. OpenAI Codex, Google's Jules, Cursor, Factory, and 15+ other AI coding tools collaborated on the specification. It's now stewarded by the Agentic AI Foundation under the Linux Foundation. The promise: one configuration file that works across all AI coding tools, not just Claude. CLAUDE.md Advantages 1+ year of usage and refinement Better documentation Larger community Claude-specific optimizations AGENTS.md Advantages Works with 20+ AI tools Open standard (Linux Foundation) Future-proof / no vendor lock-in 6 months old, still evolving AspectCLAUDE.mdAGENTS.md CompatibilityClaude Code only20+ AI tools StandardAnthropic proprietaryOpen (Linux Foundation) Maturity1+ year of usage6 months old DocumentationGoodStill evolving CommunityLargeGrowing The Pragmatic Approach: Create AGENTS.md as your canonical file, then symlink for Claude: # symlink.sh ln -s AGENTS.md CLAUDE.md You get AGENTS.md as source of truth and Claude compatibility without maintaining two files.

How long should CLAUDE.md be?

Ideal: 30-60 lines. Maximum: 150 lines before you see degradation. I tested files from 20 to 400 lines. Performance dropped noticeably above 100 lines.

Where should I put CLAUDE.md?

Project root for team rules. ~/.claude/CLAUDE.md for personal global preferences. Avoid subdirectory files unless you have a specific need.

Can I have multiple CLAUDE.md files?

Yes, but keep it simple. Global + project root covers most cases. More files = more confusion.

What if Claude ignores my CLAUDE.md?

Check file name spelling, location, and rule count. Try removing rules until compliance improves. Add emphasis markers (NEVER, ALWAYS). Accept that some non-compliance is normal.

How often should I update CLAUDE.md?

When you upgrade framework versions, add new patterns, or notice Claude making the same mistake repeatedly. Monthly review is reasonable.

A vendor-neutral open standard for AI coding tools, created July 2025. Works across 20+ tools including OpenAI Codex, Google Jules, Cursor. Younger than CLAUDE.md but potentially more future-proof.