Hi all, Claude Code now supports reading AGENTS.md directly, with support introduced in version 2.1.277. With this available, I would like to consolidate our repository-level agent instructions into AGENTS.md and remove the root CLAUDE.md. See the Claude Code documentation <https://code.claude.com/docs/en/memory#agentsmd> for the supported behavior.
Currently, our root AGENTS.md is a symlink to CLAUDE.md. I propose making AGENTS.md a regular file containing the existing guidance. I see a few benefits to this change: - *A shared convention across tools.* AGENTS.md is an open format supported by multiple coding agents. Our build instructions, testing practices, and coding conventions apply regardless of which assistant a contributor uses, so a tool-neutral filename is a better fit. AGENTS.md <https://agents.md/> - *A simpler repository structure.* Contributors would have one clearly named file to read, edit, and review, without needing to understand why one instruction file points to another. - *Better portability.* A regular Markdown file avoids relying on symlink support. This is particularly useful on Windows, where Git configurations that do not preserve symlinks can leave a file containing only the target filename. Symlink considerations <https://code.claude.com/docs/en/memory#share-one-file-with-other-coding-tools> - *Less maintenance as tooling evolves.* Using a shared entry point makes it easier to keep project guidance consistent without accumulating separate instruction files for individual tools. The migration would preserve the existing guidance, update the title and introduction to address coding agents generally, and adjust references to CLAUDE.md. There are compatibility details to account for: older Claude Code versions need an upgrade, and contributors with an applicable CLAUDE.local.md may need to adjust the Project instructions setting to also load AGENTS.md. I would document these details alongside the change. Loading rules <https://code.claude.com/docs/en/memory#when-claude-code-reads-agentsmd> Please let me know if you have any concerns, especially if this would affect an existing workflow. Best regards, -------------------- Yuan Tian
