The Fragmentation Problem: Proprietary Naming Conventions in AI Coding Tools
Executive Summary
The AI coding assistant ecosystem in 2025-2026 has developed a significant fragmentation problem: nearly every tool has created its own proprietary configuration file format and naming convention. This creates unnecessary overhead for developers who use multiple tools or switch between them.
The Complete List of Proprietary Config Files
Instruction/Rules Files by Tool
| Tool | Primary Config File(s) | Location |
|---|---|---|
| Claude Code | CLAUDE.md | Root directory |
| Claude Code | .claude/settings.json | Project directory |
| Claude Code | ~/.claude/settings.json | Global |
| Cursor | .cursorrules (deprecated) | Root directory |
| Cursor | .cursor/rules/*.mdc | Project directory |
| Cursor | .cursor/mcp.json | Project directory |
| Windsurf | .windsurfrules | Root directory |
| Cline | .clinerules | Root directory |
| Cline/Roo | .clinerules/ directory | Project directory |
| GitHub Copilot | .github/copilot-instructions.md | Project directory |
| Gemini CLI | GEMINI.md | Root + hierarchical |
| Gemini CLI | ~/.gemini/GEMINI.md | Global |
| Aider | CONVENTIONS.md | Root directory |
| Aider | .aider.conf.yml | Root/home directory |
| OpenAI Codex | AGENTS.md | Root directory |
| OpenAI Codex | ~/.codex/config.toml | Global |
| Bolt | .bolt/prompt | Project directory |
| Kiro | Custom “Powers” system | Project directory |
| Zed | Custom format | Project directory |
| Amp | AGENT.md (singular, early proposal) | Root directory |
The “M×N Problem”
Every AI tool creating its own format leads to:
- M models × N config formats = exponential complexity
- Developers maintaining 8+ identical instruction files
- Manual syncing between formats
- Inconsistent behavior across tools
Developer Frustration: Direct Quotes
“Our biggest problem is the terrible shortage of rule files: AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, (.cursor/rules), .windsurfrules, .clinerules, vscode - .github/copilot-instructions.md, bolt - .bolt/prompt .rules” — Kevin Kern on X
“If you’re using multiple AI coding assistants, you know the pain. Managing identical rules across eight different files is tedious, error-prone, and frankly, a waste of time.” — JP Caparas, Medium
“Every AI coding tool needs project-specific instructions—that’s not changing. But nine different config paths? That’s fragmentation for no reason.” — Concret.io
”# Damn you Claude!” — Found in developer setup scripts dealing with Claude’s refusal to adopt AGENTS.md
“The number one headache for most developers using Claude Code is just trying to figure out which config file to edit.” — eesel.ai
The Attempted Solution: AGENTS.md Standard
History
-
May 2025: Two competing efforts emerge
- AMP team proposes
AGENT.md(singular), secures agent.md domain - OpenAI acquires agents.md domain for their approach
- AMP team proposes
-
Late June 2025: Industry coalesces around
AGENTS.md(plural)- Adopted by: Codex, OpenCode, Gemini CLI, Jules, Factory A
-
July 16, 2025: OpenAI announces collaboration with Sourcegraph and Google to formalize
-
Late 2025: AGENTS.md stewarded by Agentic AI Foundation under Linux Foundation
Current Adoption Status
| Tool | AGENTS.md Support |
|---|---|
| OpenAI Codex | ✅ Primary format |
| Gemini CLI | ✅ Supported (alongside GEMINI.md) |
| Continue.dev | ✅ Default lookup |
| Aider | ✅ Supported via —read |
| OpenHands | ✅ Default lookup |
| Windsurf | ✅ Fallback support |
| Factory | ✅ Primary format |
| Kilo Code | ✅ Supported |
| Claude Code | ⚠️ Still prefers CLAUDE.md |
| Cursor | ⚠️ Still uses .cursorrules/.cursor/rules |
“Every tool except Anthropic has rallied behind the AGENTS.md standard. But Claude Code still wants its own special CLAUDE.md file.”
As of January 2026: 60,000+ repositories contain AGENTS.md files
Root Directory Clutter: A Secondary Concern
“I would prefer .agents/claude or something so we can get these files out of the root directory, which, at least for TypeScript projects, is already a confetti-like jumble of json files for every little ‘simple’ tool that needs its own configuration file.” — Hacker News commenter
Common root directory pollution in modern projects:
package.json,package-lock.jsontsconfig.json.eslintrc.json.prettierrcCLAUDE.mdAGENTS.md.cursorrules.windsurfrules.clinerulesGEMINI.mdCONVENTIONS.md.aider.conf.yml
Tools Built to Solve the Fragmentation
1. Ruler
- Purpose: Single source of truth for all AI agent instructions
- Supports: 22+ tools including agentsmd, aider, amazonqcli, amp, augmentcode, claude, cline, codex, copilot, cursor, firebase, gemini-cli, goose, jules, junie, kilocode, kiro, mistral, opencode, roo, windsurf, zed
2. Rulesync
- PHP CLI tool
- Write rules once in
rulesync.md, generates all tool-specific formats
3. ClaudeMDEditor
- Visual editor for multiple AI config formats
- Supports Claude Code, Cursor, Copilot, Windsurf, Gemini, Aider
4. vibe-rules
- Format converter between tools
- Hard-linking approach: one file, multiple names
5. rulebook-ai
- Treats AI operational context as portable “Environments”
- Manages Rules, Context, and Tools as code
The MCP Parallel: A Success Story?
The Model Context Protocol (MCP) represents a successful standardization effort in a related domain:
- Released by Anthropic as open-source
- Adopted by competitors (OpenAI, Google, Microsoft)
- Transforms M×N integration problem into M+N
- Acts as “USB-C port for AI applications”
Key insight: MCP succeeded because it was:
- Open-source from day one
- Actively adopted by competitors
- Provided clear value proposition (interoperability)
The instruction file format problem could potentially be solved the same way, but requires major players (especially Anthropic with Claude Code) to adopt the standard.
Recommendations for Developers
Short-term Workarounds
- Use a sync tool (Ruler, Rulesync, vibe-rules)
- Hard-link files so one edit updates all
- Adopt AGENTS.md as primary, with tool-specific symlinks
- Put instructions in subdirectory (
.ai-rules/) with links to root
Proposed Standard Structure
.ai-rules/
├── main.md # Canonical instructions
├── cursor/
│ └── config.json # Tool-specific overrides only
├── claude/
│ └── config.json
└── shared/
└── context/ # Shared context files
What Would Actually Fix This
- Anthropic adopts AGENTS.md as primary (with CLAUDE.md as fallback)
- Cursor adopts AGENTS.md (deprecates .cursorrules fully)
- All tools agree on single file location: either root or
.agents/ - Tool-specific overrides only for features unique to that tool
Sources
- Aligning Team using Cursor, Agentforce Vibes, Claude, etc.
- Agent.md vs Agents.md: How the Industry Settled
- AGENTS.md Official Site
- AGENTS.md Emerges as Standard Format
- Stop managing 8 different AI rule files
- Kevin Kern on X - Rule files proliferation
- Ruler - GitHub
- AGENTS.md - Hacker News discussion
- Ask HN: What’s in Your Agents.md/Claude.md?
- OpenAI Codex - Custom instructions with AGENTS.md
- Gemini CLI - GEMINI.md files
- Aider - Specifying coding conventions
- Model Context Protocol Introduction
- MCP: Solution to AI Integration Bottlenecks
- A developer’s guide to settings.json in Claude Code