Link CLAUDE.md to AGENTS.md

[tomjn]

Claude Code won't load AGENTS.md by default, but we can tell it to, and this gives us somewhere to put Claude specific instructions too

[sprunk]

"claude doesnt read the thing everybody else reads" sounds like not our problem. what instructions would be useful for claude but not others?

[tomjn]

claude doesn't read the thing everybody else reads" sounds like not our problem.

A lot of people agree but there are no signs of it changing, the alternative is copying AGENTS.md in full which is wasteful. The default currently is that Claude is unaware of everything in AGENTS.md unless prompted to look by the user, which could be problematic with sub-agents etc

what instructions would be useful for claude but not others?

So one of the arguments against AGENTS.md is that different agents make different mistakes or respond differently to language. E.g. bold direct statements about always doing the right thing can embolden OpenAI models but make Anthropic models more shy and cautious, the optimal instructions for one AI may reduce performance on another.

[bruno-dasilva]

imo (medium opinion, weakly held) is that supporting multiple formats for agent stuff isn't necessary unless we decide of first party support for specific agents (eg. if we wanted to support claude code working autonomously on the repo).

For human-driver purposes, you can easily symlink CLAUDE.md to AGENTS.md locally (i do this). Back when github copilot didnt support AGENTS.md, you could do similar local-only references from .github/copilot-instructions.

---

I have this opinion solely because agent support has a long tail and i don't think its worth spending time supporting, especially as that changes in the industry over time.
On the other hand, claude code is probably the most popular coding agent and doing it for this one time seems benign.

so 🤷

[tomjn]

Note that right now Claude Code as the most commonly used agent on the engine and in the wider ecosystem has no idea about anything in AGENTS.md by default. So the optimal step might be to rename AGENTS.md to CLAUDE.md. But a symlink or what I suggested is more inclusive.

I dont think Anthropic will support agents.md, and hasn't done despite noise about it, but there's a very real practical immediate consequence that if AGENTS.md says not to do something then the only half decent AI that will even see it is codex, leading to noisier PRs, more slop, and wasted tokens and $$$

[tomjn]

As for supporting AI, I think the users of AI should be handling that. If someone wants to update the agents file with some sensible guard rail I think that's an easy ask, adding an MCP agents or skills etc though should happen elsewhere

[bruno-dasilva]

the wider ecosystem has no idea about anything in AGENTS.md by default

seems to be supported by most everything except for claude code lol

but yea I'll leave this up to project maintainers whether they care about an extra CLAUDE.md symlink

[tomjn]

I truly worry for anybody who uses Gemini CLI for code

Note though that most of those are going to involve paying API rates for decent AI models, which is way more expensive than a Claude code subscription. Codex is the only reasonable competitor unless you're throwing cash at the problem or have the old copilot per message billing