Comment by troupo
6 hours ago
I beg people to learn what symlinks are. The fact that "put @AGENTS.md in there" is a "common workaround" shows why programmers (good ones at least) are not going anywhere soon.
6 hours ago
I beg people to learn what symlinks are. The fact that "put @AGENTS.md in there" is a "common workaround" shows why programmers (good ones at least) are not going anywhere soon.
I used to use a symlink but was concerned that Claude might see the presence of an "AGENTS.md" file (in e.g, a "List Files" tool call output or from a direct `ls`), be curious and attempt to read it directly (not knowing that it's the same as the "CLAUDE.md" file auto-injected by the harness), and essentially double the token impact / context bloat. Indeed, I did some local experimentation and noticed this was the case, which is why I switched to the explicit "@AGENTS.md" approach.
So perhaps there's no need to be rude about it :)
Your solution "appears" to solve the problem, but without any information about how exactly that solution works, it's just magic an vibes.
Does the harness parse the contents of CLAUDE.md, see the @AGENTS.md and then inject the contents of AGENTS.md into that file with a note saying "hey Claude-the-llm, here's the contents of AGENTS.md per an @reference"? Does the harness parse and inject but WITHOUT any ceremony telling claude-the-llm that what it's looking at is from another file? Or does the harness do nothing and Claude-the-llm is merely trained to see @references and treat those as "I should go read that file"? Which is it? If it's #1 and #3, then on long contexts/after compaction, then the LLM is still pretty likely to lose the fact that it read that file and re-read it again. If it's #2, the LLM could have the same problem as with the symlinks.
How does it work? The Anropic docs certainly don't say. So what's the best choice? I guess it's magic. For folks like me who care though, I guess there's always Pi or Opencode (or even, writing your own harness [which is shockingly easy if you want it reliable without all the fanciest features]).
Good programmers know symlinks are not portable
Neither are line endings. But like line endings, I just put it into git and get over it.
One bonus to this approach is that I can add Claude Code-specific stuff in there, that I wouldn't need for other harnesses.
Symlinks aren’t portable.
Symlinks are a pain if you're on Windows, I'd rather not bother with them.
I never had any issues with them. And they fixed my problems in a good way.
>Symlinks are a pain if you're on Windows
How so?
I'm pretty sure some agent harnesses read both files when present, so this @ "aliasing" is more token efficient.