Comment by simonw a day ago
> Finally, we keep this file synced with an AGENTS.md file to maintain compatibility with other AI IDEs that our engineers might be using.
I researched this the other day, the recommended (by Anthropic) way to do this is to have a CLAUDE.md with a single line in it:
@AGENTS.md
To be fair, I think Anthropic/Claude started doing CLAUDE.md before AGENTS.md was a thing.
I'd say if we criticize that they did not think that far ahead, we are still pretty fair.
I use symbolic links, and Claude Code often gets confused, requiring several iterations to understand that the CLAUDE.md file is actually a symbolic link to AGENTS.md, and that these are not two different, duplicate files
The recommended approach has the advantage of separating information specific to Claude Code, but I think that in the long run, Anthropic will have to adopt the AGENTS.md format
Also, when using separate files, memories will be written to CLAUDE.md, and periodic triaging will be required: deciding what to leave there and what to move to AGENTS.md
I'm still not 100% sure I understand what a symlink in a git repository actually does, especially across different operating systems. Maybe it's fine?
Anthropic say "put @AGENTS.md in your CLAUDE.md" file and my own experiments confirmed that this dumps the content into the system prompt in the same way as if you had copied it to CLAUDE.md manually, so I'm happy with that solution - at least until Anthropic give in and support AGENTS.md directly.
It just creates the same symlink on any other checkout. (On Linux/macOS at least, Windows I believe requires local settings changes.)
Only sane (guaranteed portable) option is for it to be a relative symlink to another file within the same repo, of course. i.e. CLAUDE.md would be -> 'AGENTS.md', not '/home/simonw/projects/pelicans-on-bicycles/AGENTS.md' or whatever.
Confirm on a new clone that if you modify a file that the other is updated.
I thought git by default treats symlinks simply as file copies when cloning new.
Ie git may not be aware of the symlink.
git very much supports symlinks. Although depending on the system config it might not create actual symlinks on Windows.
Wow! That's....
discouraging, actually, considering how frequently Claude ignores my AGENTS.md guidance.
This is one thing I think they need to get in-line with, and rename CLAUDE.md to AGENTS.md to follow convention.