+1 Haonan
On 2026-10-20 12:38 UTC Yuan Tian wrote: > 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 >
