If anyone wants to write/link a much better-thought-out post, I'm all ears!
Time to delete the symlinks
I feel people too readily blame the LLMs themselves for this, but I’ve found LLMs know the history of computing thought evolution better than anyone I’ve ever encountered. Once you push them in the right direction, ground them in the philosophy of thought of hard won engineering ideas, they are astoundingly precise and accurate in their read and application (keeping every session grounded is the trick!). So it’s not the machines making these same mistakes with ready conceptual frameworks around them, it’s the 22 year old gatekeepers dashing head first into wall after wall, when we painstakingly built the door two feet to the left about the time they were gestating.
Anthropic in 2026: We are losing our market position. Users who adopted other harnesses have a degraded Claude Code experience because it doesn't recognize their AGENTS.md
> “I’m thinking about banning Claude Code at Shopify until they change their mind and read AGENTS.md and .agents/skills etc.,” Lütke posted Tuesday on X.
I didn't even have that symlink in any other project - it just did it. I think it saw that one of the projects I already had was set up by Codex and that project had an AGENTS.md so perhaps it inferred that I was using both Claude and Codex, so it was politely covering both? Or maybe a recent change made this behavior default?
I was surprised and I hope they continue to seek standards.
In the manner of someone finding a dead mouse and holding it up for examination CC said it could find no instructions but perhaps it should check this AGENTS.md file.
Very sassy, Codex!
Also: did it suggest instructions for the “correct” agent, or an ambiguous agent?
One has marketing implications, the other one is generally decent advice.
> The function you added is load-bear-very important [...]
I never felt this mocked by a computer.
Maybe internally they see really unbelievable things, but my impression is that they pushed so hard on agents that they don't have the grasp of the situation.
mkdir -p ~/.githooks
git config --global core.hooksPath ~/.githooks
cat > ~/.githooks/post-checkout <<'EOF'
#!/usr/bin/env bash
if [ -d .agents/skills ] && [ ! -e .claude/skills ]; then
mkdir -p .claude
ln -s ../.agents/skills .claude/skills
fi
EOF
chmod +x ~/.githooks/post-checkoutThat said, AGENTS.md doesn't seem like a good name, right?, technically, it's an instructions file read by a single agent, not necessarily for agents, so it always struck me as a bit odd
But until the next standardization, keeping just AGENTS.md is the best approach.
Doesn't look like Anthropic care about dev community
For instance, say you added "do not add 'Made with Claude Code' in any issues, pull requests or wiki entries" in your CLAUDE.md. So far, so good.
Well the latest update now looks for something in your settings.json. Since you don't know about it, it is not set. Claude then says "not explicitly set, so now it is true by default". It completely ignores your CLAUDE.md.
Wait, what?
You shouldn't be shipping logic that arbitrarily redefines the behavior of the program, especially if your new logic actually ignores your own configuration or directives.
# CLAUDE.md
This project uses `AGENTS.md` as its agent instruction file (kept provider-agnostic). Treat any `AGENTS.md` file exactly as you would a `CLAUDE.md` file — at the root level and in any subdirectory you are working in.
@AGENTS.md
Does your tech do that?
Anyway, the joke is on me I guess, because it might not work reliably.
Default filesystems for all Unix, Linux, WinNT, all do.
That was the idea.... For the toplevel it works because of the @AGENTS.md and this is also the part the link would solve.
Thanks for all the great advice and explanations.
Anyway, with the change they announced, I can now simply delete my CLAUDE.md and everything will just work the way I wanted.
Thanks for your clarification.
aka, sometimes it really is too early to force a standard
No harness can batch your agents.md read with the reads the contents of the file tell it to read.
on the other hand if it's just a local coding/"use my computer" agent, i highly doubt the effort in maintaining different prompts is worth any gain in performance
I'll just use my one-size-fits-all AGENTS.md file and tweak it when the one of the clankers screw up. I don't have time for such busywork.
Actually, I will append extra rules to CLAUDE.md (which imports AGENTS.md) since there is a hook there, and Claude has its own foibles. So I'll backpedal a bit there.
In a "one LLM only" environment, your instructions are by default tuned for said LLM.
In a multi-LLM environment, roughly nobody will keep separate sets of instructions for each. It's not a realistic take.
On top of that: If your LLM is so bad at reading that it can't follow a set of instructions that wasn't specifically written just for that one single precious LLM, I sure wonder what that says about your employers repeated statements that ASI is definitely right around the corner.
Same with skills, symlink to skills at .claude/skills
Congrats.
Truly the last people you want with this kind of power.
Even to this day Windows has all kinds of problems around long file paths in its ecosystem.
To this day I don't know if it's a Windows problem or a Python problem, because I never encountered this - and never realized this problem exists - except for some random Python code whose docs tell me to set some registry value because of "long paths issue".
You can have all the right flags enabled, then unexpectedly you'll run some commandlet and get a path too long error.
Now if your on W11/W25 and the lastest PS it might all work, but W16 and PS versions between now and then had all kinds of things pop up.
> Short version: there is no exact equivalent for POSIX symlinks on Windows, and the closest thing is unavailable for non-admins by default unless Developer Mode is enabled and a relatively recent Windows 10 version is used. Therefore, symlink emulation support is only turned on by default when that scenario is detected. Support can be enabled by the user, via the core.symlinks=true config setting.
the fact that they're owned by different companies (ok vercel is a little less random) still leaves me with a sour taste in my mouth when thinking about the fact that they should all point to 1 place about how to create and find skills for ai agents?!
I was using my claude.md file as a pointer to my agents.md file
https://x.com/trq212/status/2101009392611278961
AGENTS.md implementation is open sourced as well: https://github.com/anthropics/claude-code/tree/main/mods/age...
Isn't it literally all just more text you're adding to the prompt. How can you even be sure it isn't just clouding context with nonsense for whatever you're asking for?
Similar reasoning with claude.md except it always reads the entire thing(?)
In my experience, there are two classes of tasks: some are very "in-distribution", and for those LLMs can near-flawlessly perform the "architectural or deep algorithmic legwork", with maybe a single second round to fix the mistakes. For others, I have to break the tasks down myself, and often it's a "death through thousand papercuts", because the size of a task that I can quickly verify and the LLM will not screw up with > 50% probability is small enough that it's sometimes net negative time spent relative to doing it myself (and using LLMs only as glorified search engine and article summarizer).
I like to tell myself that I'm getting better at recognizing these two classes up front, but I'm still frequently surprised when "type 1" turns out to be "type 2".
But circling back to the main topic: with "type 2", agent instructions are paramount, if only to enforce the "small steps, pre-commit to scope and methodology, verification at the end, user doesn't even want to know about anything in between" rules, as agents naturally want to run ahead faster than I can keep up with.
Then when it comes to implementation time, things typically go much smoother for larger changesets. Be wary to not overplan, as we all know how often we realized we missed something once we get into the details. Here, I stop the session and go back to iterating on the design/plan doc. Not a step-by-step guide, if you don't instruct them to the difference, they will just pseudo-implement in the plan like they do in their thinking traces, need to be be explicit about the level of detail.
you end up clouding that more with an agent having to re-understand concepts or conventions
AGENTS.md is good when it is a nested sparknotes for the project, you save context and turns overall, but keep them minimal and largely gotchyas or unusual workflows in your repo
Why? This is why. [0]
Why are people still putting up with this kind of attitude, especially when there are so many good alternatives available?