{"slug": "how-to-link-claude-md-and-agents-md", "title": "How to link CLAUDE.md and AGENTS.md", "summary": "Claude Code reads CLAUDE.md while Codex, Cursor, GitHub Copilot, OpenCode, and Amp read AGENTS.md, so developers running multiple agentic harnesses must either maintain two instruction files or link them. The guide recommends symlinking CLAUDE.md to AGENTS.md from the repo root with `ln -s AGENTS.md CLAUDE.md`, verifying the symlink via `git ls-files -s CLAUDE.md` (mode 120000), or importing `@AGENTS.md` inside CLAUDE.md, and advises keeping AGENTS.md as the canonical source of truth because it is the file most harnesses read natively with zero configuration.", "body_md": "Claude Code reads `CLAUDE.md`. But Codex, Cursor, GitHub Copilot, OpenCode, Amp, and most of the other agentic harnesses read `AGENTS.md`.\n\nSome widely shared guides claim Claude falls back to AGENTS.md when CLAUDE.md is missing. It doesn’t. I *really* wish Anthropic would just adopt the open AGENTS.md standard. But they won’t! Why would they reduce your switching costs :/\n\nIf you run more than one harness (I run 4), you **either maintain two instruction files** that slowly drift apart, **or you make one a pointer to the other**.\n\nThere are two ways to do this:\n\n- Symlink the two files\n- Import `@AGENTS.md` in your`@CLAUDE.md` \n\nThis article will show you how to do both, and how to choose between them.\n\n## The quick way to symlink CLAUDE.md and AGENTS.md\n\nIf you want to symlink CLAUDE.md and AGENTS.md, it’s actually pretty straightforward.\n\nFrom the repo root, with `AGENTS.md` as the real file:\n\n```\nln -s AGENTS.md CLAUDE.md\ngit add CLAUDE.md\ngit commit -m \"symlink CLAUDE.md to AGENTS.md\"\n```\n\nThen, you can verify it with:\n\n```\ngit ls-files -s CLAUDE.md\n```\n\nMode `120000` means Git stored a symlink. `100644` means you committed a regular file. Then open Claude Code, run `/context`, and confirm `CLAUDE.md` is listed under Memory files.\n\nBut read on to learn how to use an `@import` in your CLAUDE.md to make this link more reliable.\n\n## Why AGENTS.md should be the source of truth\n\nYou should absolutely point `CLAUDE.md` at `AGENTS.md`, not the reverse.\n\nAGENTS.md is the file most harnesses read natively, including *cloud agents* that clone your repo on infrastructure you don't control. The canonical file should be the one that works with zero configuration.\n\nBeyond that, Claude Code's `@path/to/file` imports aren't part of the AGENTS.md convention. Copilot CLI and Gemini CLI happen to support `@` references too, but Codex's AGENTS.md docs describe no import mechanism, so to Codex an import line is just text. Keep the canonical file as plain markdown so it stays portable.\n\nIf you’re curious about customizing coding agents, you’re obviously in the right spot. I spend dozens of hours researching each of these guides so you have a shortcut to building software with AI.\n\nI’d love to have you join us and get notified when we share more tutorials like this.\n\nThank you for being a reader of The AI-Augmented Engineer! Deep tutorials like this are exclusive to paid members of the newsletter. This support makes it possible for me to do the research and prep necessary to deliver value-packed guides like this.\n\n**I’d love to have you join our almost 200 members!**", "url": "https://wpnews.pro/news/how-to-link-claude-md-and-agents-md", "canonical_source": "https://www.augmentedswe.com/p/symlink-claudemd-agentsmd", "published_at": "2026-09-11 11:48:32+00:00", "updated_at": "2026-09-11 12:09:53.849714+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Claude Code", "Anthropic", "Codex", "Cursor", "GitHub Copilot", "OpenCode"], "alternates": {"html": "https://wpnews.pro/news/how-to-link-claude-md-and-agents-md", "markdown": "https://wpnews.pro/news/how-to-link-claude-md-and-agents-md.md", "text": "https://wpnews.pro/news/how-to-link-claude-md-and-agents-md.txt", "jsonld": "https://wpnews.pro/news/how-to-link-claude-md-and-agents-md.jsonld"}}