Claude Code now reads AGENTS.md if there is no Claude.md
code.claude.com
code.claude.com
I was quite annoyed with Claude earlier this year when I had to maintain duplicate files or rely on symlinks.
Seemed like a waste of time simply because Anthropic didn’t want to take the “L” and accept that AGENTS.md was the new standard.
IMO, this kind of product decision making is why so many products either suck, or they’re are good but not great … and users have zero loyalty.
I find it super annoying this building lock in instead of loyalty approach to product seems to be standard practice these days.
When prompted to write to it, it will always try to write into the Claude.md and error out with that approach.. It eventually figures it out, but it's a ymmv situation I think
How is agents.md and different? Just a standard for other models? Is claude the lower standard now?
Sent from my iPhone.
404
They don't even allow alternative harnesses on their subscription model. (But they do allow a agent-sdk that can pretend to be a generic compatible endpoint the alternative harnesses can use).
If you like your stuff overengineered, gated, and over-priced then by all means.
Its not even wrong from Anthropic because it's the path to most profit.
I'll take the opinion of people who have strong opinions about mild inconveniences.
Between my goals and Anthropic's bottom line, i want my goal to win out without needless inconveniences.
If you think I'm wrong, and these arguments have nothing to do with it, just tell us what explains Claude not supporting AGENTS.md.
Was it such a grand engineering challenge? Too many 'legacy' projects relying on both AGENTS.md/CLAUDE.md and that has recently changed?
I've made clear my belief on the reason behind it - branding decisions outweighing utility.
Add something to the thread by sharing your version of a 'more likely' decision process that led to the choice to only now support it.
I don’t disagree with anything you say, I just don’t think AGENTS.md ever was a big deal, just a small annoyance
> Our reasoning for this was that we don't think that model families are interchangeable and the system prompt can have a big impact on performance.
Sometimes, Anthropic has pushed standards (MCP, Skills), and that is great, but other times they have explicitly built incompatibilities. With the Plug-in marketplaces, it is quite similar.
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.
Oh-my-py unlocks max capabilities at the smartest token usage, and you can change AI company and providers while still getting things done. Roles, advisor, and the ability to use Chinese models on international providers with no training and ZDR behind OpenRouter are very powerful. You can have providers and model companies competing on price, intelligence, and speed for something that's useful but with less and less moat as model progress plateaus.
I now use GLM 5.3 for slow/planning, GLM 5.3 Flash as the default task-vision model, and DeepSeek Flash 4.1 as the advisor. Providers are ordered by cheapest at the minimum TPS I want for that model. I use it not only for coding but also as a personal assistant. I can ask it things and it gets them done automatically, like opening an issue on a repo, then having another agent ship the code, run the tests, and update master after having changed the app to autoupdate on cut release.
I can also ask it to do groceries. I use Bitwarden machine secrets and a limited virtual card connected to my phone.Something else that's very powerful is asking it to launch parallel agents to do things you know don't overlap too much.
The amount of agency we're gifted with is crazy, you can now move hundreds of hours of work with one hour of input using an open-source harness and open-weight models. I can't wait for more competitors in the chip space, and to be able to buy models etched on silicon for even higher agency, speed, and independence.
I also use the same. But I use Anthropic models (Opus 5) with it.
They win either way
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-checkoutDoesn't look like Anthropic care about dev community
Shocker.
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.
IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
Codex follows the AGENTS.md far better. CC seems to have nudged people away from taking the CLAUDE.md as mandatory instructions.
This bug was closed Not Planned and from a recent analysis of the system prompt the behavior is still there even with the new inclusion of AGENTS.md.
But this is a good change.
The world of managing skills between providers still feels messy though.
https://code.claude.com/docs/en/memory#import-additional-fil...
From a profit maximization standpoint you want identical phones that can't easily be sold across market borders. Usually that's done in software (e.g. region locked video games), but that can usually be cracked, so a single design difference is the best solution. A great example is Nintendo's cartridge slot shapes that were different in each region despite the hardware being the same.
Apple had lightning everywhere; they were forced to change to USB-C. Therefore they changed to USB-C everywhere. The market protection design change remains the sim slot.
OK, so why not ship a SIM card slot in the US? eSIMs work perfectly well in Europe, the US and most of the rest of the world, "region locking" is clearly not the answer.
Apple did not have "lightning everywhere" either - Macs and iPads got it much earlier.
2.1.277
September 18, 2026
Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under “Project instructions” in /config (not yet on Bedrock, Vertex or Foundry)
Note that this *does not include .agents/skills*. Argh.
> “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.
Maybe I can finally delete that useless symlink to the actual AGENTS.md.
Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.
You can toggle this behavior in /config."
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.
Time to delete the symlinks
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
Pausing AI training would benefit them a lot, as inference is insanely profitable (> 50% margins with maximum demand, afaik)
Cynical. The word is cynical.
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.
…
Yeah… that’s… pretty much how these LLMs work and their main selling point, actually. Not sure what the “I’m such a greybeard with 350 years worth of experiencie” preamble gets you here besides just making you look like you barely understand what you are talking about.
In fact, this is a key insight, so it’s surprising you didn’t get the punchline. Trying to build things in a new way on a machine composed of the corpus of all the old ways is stupid. By eliciting the corpus of tried and true methods over the history of computing and process engineering as the grounding for how to develop and behave in processes, you offload a huge amount of the work in getting software that’s “right” for the domain you’re working in. But not being aware of them and being heedless that the techniques hard won were hard won by people at least or more smart than you facing similar problems is leading to a cycle in software that’s needlessly dumb, making stupid mistakes that are unnecessary.
There was a great Star Trek NG episode where Picard is stranded on a planet with a creature that can only speak in metaphorical language. Every sentence it uses refers to an event in the past and you have to understand it’s history to understand it today. Because LLMs are entirely trained on historical corpus, there is no time in history when all the techniques and processes and system design thinking was more relevant. Like that episode, Darmok, you can elicit a wealth of experience by simply referring to a technique from the past - if you know what it is.
Another way to put it , those that aren’t aware of their history are doomed to repeat it. The sad part of the situation is the coding agent you’re working with is fully trained on it, but unless you intentionally activate the semantic space and bring the concepts into its J-space you won’t maximize the value of that corpus. So, we are using these tools which are mostly crap duct-taped together, which suffer from flaws well understood for decades, mostly because of the driving human being ignorant of the available corpus.
In any case I don't see how this is materially different from Windows where it's the norm for every game to ship its own libraries and install various redistributables to function.
At least with dark mode, you can ignore most web developers and get a browser extension to make everything dark, then only webmasters who don't follow standards gets it wrong.
0 - https://www.williamangel.net/blog/2026/09/18/i-cancelled-my-...
I canceled my personal subscription the weekend after Astra was released. I was working with our internal IT to swap the whole team when OpenAI turned off new 20x Pro subscriptions, so we’re stuck for now. Everyone is hyper-productive for about 1 day a week on 5x.
# 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.
Edit: sometimes if Claude lists files in a directory or does a search that shows it an AGENTS.md exists it will decide to read it. But it's not a reliable behavior.
I've been using omlx and qwen for almost a year but have bounced around clients a bunch, and it seemed like everything was specific to claudes style of config layout, so I've been putting all of my skills/agents/md files in my ~/.claude as a catchall for bouncing between pi.dev/claude/vscode/etc. and just seeing what happens. I really haven't used claude itself much so reasonable but I didn't know it didn't look at AGENTS.md, for instance. Also using some memory/kb system that puts $myKB.md in directories to pre-fill context by project/workspace.
I'm currently using oh-my-pi but in the quest for optimization and token trying to get better than 30t/s on my m1 max 64gb (qwen3.6-a35b) I probably need to spend some time just making pi base into what I need and not the opinionated omp setup I have that probably makes the initial context larger than it should be.
I'm between work and can't afford the $100+ frontiers but it does get really frustrating spending hours/days tweaking this stuff to almost no benefit sometimes. When I do get to use a frontier it's such a nice break from fixing things. The local llm stuff can definitely be a bit frustrating right now and zap the energy I have for work out of me when it goes awry.
Anthropic's plans have always been pretty dynamic based on the demand they're seeing, whereas OpenAI's demand-induced changes are more abrupt and sharp (both upwards and now downwards too). You can tell that suddenly you get a bit more Fable usage, and especially higher tok/s, than pre-Astra. I wouldn't be surprised if Anthropic tweaks it almost daily, potentially automated. As a paying user I don't think either is better than the other really, just different. They both suck as you can get wildly different usage for the same $. If I'd bought a load of $200 subs for employees right after Astra launch I'd be pissed that now I'm getting 3x less usage than when I bought them. Because this extends to Sol too.
ln -s AGENTS.md CLAUDE.mdln was the only thing that worked for me
aka, sometimes it really is too early to force a standard
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.
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
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.
No harness can batch your agents.md read with the reads the contents of the file tell it to read.
Tariq is wrong and it's not an antipattern. Reason being that a good AGENTS.md impacts all models in a positive manner. If it affects certain models negatively, it means you're putting the wrong things in it.
Truly the last people you want with this kind of power.
Which is why a hook works where a file wont. It lands when the command is about to run, not 200 turns ahead of time as a suggestion.
That 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.
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?
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
Similar reasoning with claude.md except it always reads the entire thing(?)
Congrats.
It was either this or Claude had to become a generic term like sheetrock.
If anyone wants to write/link a much better-thought-out post, I'm all ears!
Reminds me of when you’d see posts for React 16.0.3 or whatever. Absolutely minor news, but multiply that by the number of users…
Now I just need to figure out which one makes me feel worse.
I also think your point has at least one decent reading: that the upvotes help other practictioners update their mental model of their tools. There's probably also some value due to being an implicit "Claude Code megathread" for commenters to congregate around. News so minor that it does't even really make sense to force people to fully stay on topic, hah.
“I’m thinking about banning Claude Code at Shopify until they change their mind and read AGENTS.md and .agents/skills etc.,”
- Tobi Lütke on X.
Same with skills, symlink to skills at .claude/skills
> 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.
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.
There’s no problem with Python in general. The registry value LongPathsEnabled, which is probably the one you were asked to set, affects the entire Windows system.
However, there’s also an older workaround that allows programs to use “extended paths” even if that setting is off, by prefixing path strings with “\\?\”. So applications using that workaround can use long paths no matter how Windows is configured. But Python doesn’t use the workaround, it uses the modern APIs and if you want long paths, you need to configure the underlying Windows system to enable it.
But it brings me to two follow-up questions:
1) What is that registry switch even doing, if the problem can be solved with just setting it?
2) Why is Python not using the workaround like ~everyone else?
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...
(As I mentioned elsewhere) I use oh-my-pi (and opencode, and toad) but use (client paid) Opus 5 with these harnesses.
All three of these understand AGENTS.md
Why? This is why. [0]
Now is the time to git mv CLAUDE.md AGENTS.md.
Why are people still putting up with this kind of attitude, especially when there are so many good alternatives available?