Universal AGENT.md with Symlinks
One AGENT.md file as the single source of truth, with symlinks to CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md.
Description
The AGENT.md initiative (backed by Amp and other vendors) solves the config file fragmentation problem. Instead of maintaining separate CLAUDE.md, .cursorrules, .windsurfrules, and .github/copilot-instructions.md files that drift out of sync, you write one AGENT.md and create symlinks. Every tool reads its expected filename but gets the same content. Amp natively supports AGENT.md since May 2025. GitHub's Copilot Coding Agent already reads CLAUDE.md and AGENTS.md alongside its own format. The migration is simple: move your existing config to AGENT.md, then ln -s AGENT.md CLAUDE.md, ln -s AGENT.md .windsurfrules, etc.
Who is this for
Teams or individuals who regularly switch between AI coding tools (Claude Code, Cursor, Copilot, Windsurf) and want a single source of truth.
Why files are split this way
Maintaining multiple config files that say the same thing is a maintenance burden and drift risk. Symlinks solve this at the filesystem level — one write, many readers. Tool-specific additions that cannot be shared should still live in their native locations (e.g., .cursor/rules/ for glob-scoped rules).
What changed from the previous setup
Separate CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md files that drifted out of sync as the project evolved.
Related patterns
Multi-Editor Frontend Setup
Frontend-optimized AI config covering design system tokens, component conventions, and testing patterns across Cursor, Copilot, and Claude Code simultaneously.
Turborepo Per-Package AI Context
Root-level CLAUDE.md with per-package CLAUDE.md files that Claude auto-loads when working in subdirectories. Works with Turborepo, Nx, and pnpm workspaces.
Spec-Driven AI Development
Separates what to build (SPEC.md) from how the AI should work (CLAUDE.md). Specs define features and constraints, CLAUDE.md defines workflow and conventions.