The fact that it took this long to add such a basic feature is a disgrace. I’m not even remotely satisfied. Bailed on Claude ages ago. Rolling Codex, Gemini, and Qwen3.8 30B. The only way I’m going back to Anthropic is if they drop and Culture Series mind.
Its indicative of a pattern of behavior where they want to upsell you into their ecosystem and keep you there.
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.
Don’t forget the initial context, my point was that saying Anthropic is a disgrace for not supporting AGENTS.md was an overreaction, because it’s solved with a symlink.
I don’t disagree with anything you say, I just don’t think AGENTS.md ever was a big deal, just a small annoyance
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
It also works more reliably. I've tested this quite a bit. Instructions in files referenced via CLAUDE.md are more likely to fall out of context or to be ignored. Raw project level CLAUDE.md instructions are the second most durable available as far as I know. I used to have a "well organized" hierarchy of rules and instructions. Collapsing all of that into CLAUDE.md + skills made things far more predictable and "as instructed".
Maybe I'm not up to speed but i deleted claude.md while testing weird opus 5 behaviors, it came back saying nothing was used in claude.md but rather storing context in memories.md in some .claude/projectname/memories folder in my user profile....
How is agents.md and different? Just a standard for other models? Is claude the lower standard now?
Because other people do, and those people previously would have CLAUDE.md files in their repos and not AGENTS.md files. When you have to work with them and their repos, you were forced to deal with the difference.
Yes, but you see this is all part of Anthropic's master plan. They know developers are incapable of renaming files so the fact that Anthropic resisted Agents.md is proof that they were trying to lock you into them as a vendor.
Yet it took Codex 8 months to get subagents after their introduction in claude code. This of course pales in comparison to having to symlink CLAUDE.MD to AGENTS.MD
I switched to oh-my-py and never looked back. I guess having an incentive to maximize (expensive) token usage, and LLMs degrading with higher context, isn't aligned with a user's best interest.
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 recently had Claude Fable set up a new project for me and I pointed it at some existing projects to use as a guide on how I like to structure things. It created, unprompted, an AGENTS.md file and a CLAUDE.md symlink to AGENTS.md
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.
Seems agents understand their own bugs now. https://github.com/openai/codex/issues/9252 has 88 thumbs up and a workaround (switch to raw mode with Alt+R) found in a comment. Codex suggested the workaround to me today when I complained about its multi-line bash command being corrupted on paste because of the two-space indent in Codex's code blocks.
I heard some of their employees sent to do some PR in podcasts: they are definitively disconnected from the reality.
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.
I get that it would be nice to have it first party, but they're all just json files that you can just do a bulk awk/sed on. I did this a week ago for about 100 conversations when migrating my convo history to a different username.
this is seriously nuts. I have so many repos sitting there using old/deprecated/replaced names just because of their idiotic decision to place dir-specific config and memories in ~/.claude
This is where I landed when a recent(ish) change broke symlinking for rules files. I didn’t like how hacky it was a first, but now I’m glad I did it. The same hook drives specific rules the non-Claudes get per repo.
I honestly hate .agents it's a big XDGBDS offender. Almost every plugin / lazy platform harness tries to use that dir too so I have to do a bunch of hacks to keep my $HOME clean. Also everyone tries to use a .claude .gemini .codex etc. Annoying that all these tools just completely ignore these things, it's literally like litterers you know it'd be terrible if every tool did this, but you still do it anyway
Remember they didn't do this because they wanted to help community, they did it because community was angry and they were losing users to other harnesses.
Doesn't look like Anthropic care about dev community
A for profit company that’s bleeding money, is not profitable and has an unsustainable business model that’s about to burst its banks at any minute does not actually care about the needs of its customers, only their money?
Once I asked, puckishly, Claude Code to “follow the instructions in this directory” when there was only an AGENTS.md there.
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.
Had a silly exchange with Codex: I had an AGENTS.md file in a directory that was a symlink to an already-created CLAUDE.md. On my first prompt to Codex, it decided to point to me that my AGENTS.md specifically calls out directions to Claude, and that it would generously re-interpret them as directions to itself, and that maybe I should fix my AGENTS.md to reference the correct agent.
CC is such a bloated POS by this point that only full on AGI could have implemented this feature. Congrats guys. Maybe with Super Intelligence they will be able to make it actually respect the instructions in there too.
The system reminder explicitly tells it that the CLAUDE.md or AGENTS.md content is optional. I believe this is a big part of why CC doesn't heed the instructions alot of the time:
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.
If this continues to be a thing ...one might actually imagine a good system where we have AGENTS.md with all generic agent instructions and a bunch of harness specific files like CLAUDE.md, GEMINI.md, and CODEX.md that all add whatever nuance and nudging each harness seems to individually require
I like this, but can we not have any of this in the root of the repo cluttering it up with the harness specific instructions for a half dozen plus different harnesses. Something like a dot agents dir
From a design and manufacturing point of view you want everything to be identical. Differences are expensive.
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.
We see this more locally in the US as well. There's something called the California effect. California emission standards were more strict than the rest of the country, but it didn't make sense to make California only vehicles and then vehicles for the rest of the country. So automakers built to the California standards and residents in all of the other states got to benefit from cleaner air as a result.
> “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.
Did a Ctrl+F to try and find anything about `.agents/skills` in the release notes. My harness already fixes Claude's refusal here, so I can't tell if that's been supported yet or not. Annoying if they did one without the other.
Claude also checks your settings.json first, and if it sees a default there it then prefers that over anything in CLAUDE.md. This is particularly nefarious as they ship logic to presume a default if a setting is not there in settings.json, even if there are instructions in CLAUDE.md for exactly that.
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.
I have this in a rules file. It respects it. The only thing that broke recently was when they added the session links. That needed an explicit additional rule. Sometimes rules don’t get added to worktrees but I haven’t had the patience to isolate why this only happens sometimes.
got myself in a heated discussion with cc about that. It confessed that it added the ‘Made by Claude’ in a commit because a ‘mid session system-prompt refresh’ told it that, and that overwrites any previous instruction in CLAUDE.md
My view is at the end of 35 years in the industry the current wave of “software” and “systems” engineering coming out of the AI harness community is pretty garbage. But web technology and distributed systems followed a very similar arc, as did protocols and memory management; and microcode before them. But it feels like this is particularly bad because the mistakes being made are plainly obvious to the grey heads who have been here a while. As opposed to before when mistakes were in new domains being explored, these are mistakes made before and have good solutions to.
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.
> but I’ve found LLMs know the history of computing thought evolution better than anyone I’ve ever encountered
…
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.
Because, knowing what to induce in its behavior is the key - by understanding things like Postels law, I can direct the agentic loop towards patterns of development that avoid the cascade of issues that seem endemic in modern agentic harnesses.
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.
Anthropic in 2025: We can use our dominant market position to degrade the harness experiences of our competitors because they will never adopt CLAUDE.md
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
Sounds like free market at work to me. I am just glad there is quite a lot of competition in a field that I would have assumed would have huge costs of entry
Building small models is a lower barrier. Think of something like to just train on a corpus of internal corporate data. I've see some small models that do this. It's like a super RAG thing. I think more of that will happen. Excited to see a SLM vendor emerge.
The walls are closing in and the president is gleefully lighting fires he has no intention of putting out. There's a reason they're rushing like mad to an IPO, but as we saw with OpenAI it's easier said than done when your business model is "Lose tons of money to eventually maybe dominate a market with the moat we don't have, but trust us AI is huge give us trillions."
Its like the Epic Games Store supporting Linux, or [any website] supporting dark mode. You'd think its an easy to implement bare minimum that everyone asks for, but its like pulling teeth to actually get it done.
> ..or [any website] supporting dark mode. You'd think its an easy to implement bare minimum that everyone asks for, but its like pulling teeth to actually get it done.
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.
<Platform> is basically impossible to support. <Company> pulled it off by shipping a complete copy of the Chromium browser with <Product> and turning it into a web application.
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.
On Windows those libraries are part of the application package. On Linux they're supposedly part of the OS, they're designed to be part of the OS and the loader is trying to get them from the OS, but is redirected to get them from the wrapper layer provided by the store (neither the application nor the OS!) instead.
I’m cancelling my department’s subscriptions over this once we can get more access to Astra.
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.
yep, all i want is freedom to make a workflow where i don't feel tied to one provider, CC is exactly what i don't wanna get trapped in. I'll happily use claude MODELS, but if it means i have to keep learning two harnesses side by side to keep using one particular provider, then the second i can easily replace it, i am going to(even if its a small drop in performance).
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.
I don't think this will work reliably. Pretty sure it's not the LLM deciding to read the files, it's the harness in Claude Code itself injecting the instructions files based on the paths the model accesses.
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.
On many filesystems, a lot of data about a file is not attached to the content of the file, but stored in a master filename and metadata table graph tree of some sort, and the address offset within that metadata used to retrieve the contents on disk can be a duplicate of another entry, without that situation instantly leading to a filesystem driver crash. Some filesystems officially support such duplicates as well as equivalents of HTTP 3xx, some you can just do as a matter of fact and fsck would have some words about it.
Default filesystems for all Unix, Linux, WinNT, all do.
Yes. The thing is that creating a link will not do it recursively for all subdirectories. Even worse, in the subdirectories I didn't want to place a claude.md in the first place but just have agents.md.
That was the idea.... For the toplevel it works because of the @AGENTS.md and this is also the part the link would solve.
I phrased it wrong. It was not about "automatically detect nested AGENTS.md". The idea was that when AGENTS.md files should be treated just like CLAUDE.md files in all subdirectories, when encountered.
Anyway, with the change they announced, I can now simply delete my CLAUDE.md and everything will just work the way I wanted.
What I meant is that the LLM isn’t the one that loads the agent file. It’s not trained to look for CLAUDE.md. It’s only training is to edit that file, and the harness does the magic of injecting it. So I would predict that with those instructions it rarely or only intermittently loaded AGENTS.md, but if you asked it to add a rule it would probably have put it on the right file.
Meanwhile, I just setup codex for the first time (to try Astra) and it offered to load my Claude and Cursor conversations and claims to even do it in a way where it says in sync if you use both. The only reason to use Claude Code is the 20x usage of the 200$ plan is ridiculous value if you have the need for that volume.
The 20x plan offers the same amount of monthly usage per dollar as the $100 plan. It offers 2x monthly usage of the $100 plan. It's incredibly deceptively named, the "20x" is only about the 5-hour window.
Until about one week ago, i.e. a few days after Astra release, the other comment was right; OpenAI plans gave a lot more usage than Anthropic. That had been true since pretty much the start. Now for the first time that's changed. OpenAI quotas have cratered, probably due to Astra-induced demand. Claude plans now offer more usage. Of course, this could flip back again in a few weeks, who knows. But right now Anthropic gives more usage, by virtue of OpenAI having slashed usage, and Anthropic having raised it a little, also likely because of additional capacity from people moving to Codex - hence also finally this AGENTS.md change.
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.
I couldn't care less what the filename is, I do care however that Claude still forgets about 14 times per week that -r with ripgrep means replace (and not recursive, like with grep). Even though it's literally spelled out in my CLAUDE.md. Claude code, even with the most advanced models, forgets or disregards very simple and clear instructions from my modestly sized MD file.
Finalllyyyy!! We need industry wide standards. I come from the 3d industry and oh god changing softwares and adapting to different hotkeys it's a pain. I have always thought every industry should be standardized for the sake of the users.
fwiw, i am with thariq https://x.com/trq212/status/2092302273099796842 in that prompts should be tuned for models and in fact blindly applying agents.md is probably an antipattern unless you want all models to basically converge to some common ill defined of instruction following - good local minima, bad global minima for model diversity and exploration of intelligence.
aka, sometimes it really is too early to force a standard
If you want this it's trivial to add an AGENTS.md that simply says "if you're Claude read CLAUDE.md, if you're Astra read ASTRA.md". A common entry point is good regardless.
Wasting turns? That is silly, use a better harness. Also token usage can mitigated by incremental discovery instead of stuck 5k+ worth of tokens in the AGENT/Claude md file.
depends what you're doing. if you've got a specialized agent deployed in prod, of course your evals and prompts will be targeted towards 1 specific version of a model.
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
No thanks, I'm not tuning a bunch of files just for things to break when I switch models or a new one comes out.
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.
19 out of 20 harnesses supporting the standard isn't "too early".
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.
I'm honestly not sure if this is tongue in cheek and the "finally" is in the silly way it is often used, but the claude.md variant existed first. Indeed, the agents.md thing was pretty clearly a "that's neat, let's do that with a different name".
Just because something is first, doesn't mean it's the standard. The standard is put in place by how many harnesses use a specific pattern, and that has been AGENTS.md for a long while now. Long enough that Claude Code not supporting it is really just an act of forcing people into a proprietary workflow, because of course it's in their interest to make moving away as painful as possible given how little moat the LLM models themselves have. In fact, I think Claude Code has been pretty much the only one not supporting AGENTS.md. Check out https://agents.md if you want more information on it.
It's "finally" because people have been asking for it for a long time. No one cares that "claude was first," what they want is for Ant to follow the conventions and not put extra work on us. This was such a minimal thing to do, and considering how much they vibe and claim "coding is solved," we thought it would not be too difficult to respect AGENTS.md, so finally seeing it happen, while nice, is too late for me. I've moved on from Big Ai and only use open weight models now.
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.
Gotta say, it is hilarious that this is the current top HN post. I feel like it's gotta say something about our current AI zeitgeist, that there is such vigorous attention on a seemingly-minor change. Feels like something is on the tip of my tongue but I can't name it at the moment.
If anyone wants to write/link a much better-thought-out post, I'm all ears!
Another commenter appreciated the move towards a sane/nice standard. I am definitely on that side of the table. I'd rather feel good about the move -- good enough to ignore the other implied issues, lol.
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.
Windows does actually have symlinks but I don't think I've ever seen anything actually use them, and I don't myself because it smells of interop issues with other windows apps.
Even to this day Windows has all kinds of problems around long file paths in its ecosystem.
> 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".
The 260 character limit is just a Windows problem. See my other comment in this subthread for a summary of the eldritch horror in question. The tl;dr is that backwards compatibility is a helluva drug.
It’s a Windows problem. There’s still, to this day, a 259-character limit on path length in the Win32 API unless the OS has been configured to support long paths and the application uses the correct subset of Windows APIs. For example if you use ‘CreateFileA’, you’re stuck with the limit no matter what.
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.
Windows supports it but git disables creating symlinks by default.
> 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.
finally!
Now this might sound sorta off-topic but i really wonder how people feel about skills.md, skill.md, skills.sh domains...
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?!
Forcing their own proprietary filename was clearly a business decision (it's free advertising, along with commit co-authorship). I wonder what made them go back on it.
They're probably losing market share. The only time you ever see tech companies make consumer-focused changes is when those consumers are jumping ship to go somewhere else in large enough numbers to matter.
Everyone sharing the 513 ways you can already do this is entirely missing the point. Standards matter and there's very few things in the AI world everyone agrees on and this is one of them. .agents/skills is another and anthropic is still holding out there.
Can it read copilot.md if neither of the other files are present?
Also: agents should be the standard, or we need to invoke the XKCD for "one more standard to rule them all"?
When Jesus' mother notices that the CLAUDE.md (Ancient Greek: Κλαύδιος ) file is missing from her favourite open source project, Jesus delivers a sign of his divinity by turning Claude's CLAUDE.md search path into AGENTS.md at her request.
Anyone have a good guide on properly setting up/optimizing local llm stuff like this?
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.
Still don't understand the point of the markdown files.
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?
For skills, it only reads the summary telling it when to read the rest. So yes if you have too many skills, it can get confused and start reading all them and cloud the context. But if you have a few and they're used tactically, it's better than having to manually paste in prompts that you reuse a lot.
Similar reasoning with claude.md except it always reads the entire thing(?)
You know it because you write the content of AGENTS.md. And if you are smart, you keep it brief and cover only the important things that anyone (human OR LLM) would want to know if working in this directory.
In my experience telling it what I want is not a reliable process at all whatsoever if what I'm asking for is sufficiently complex, no matter what context I provide. So instead I break tasks down into very small parts, ask for solutions to those that I can reasonably quickly assess and then put them together myself. Asking it to do the architectural or deep algorithmic legwork IME wastes so much time and is often just wrong.
There's a balance to be found here, that's unfortunately very hard to find at times.
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.
A good practice to use (ime) is having it do research for the larger task, propose alternatives, and write that in a file. You can then review and comment that up, go through another iteration.
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.
this is probably outdated, attention typically stays fine up to ~200k tokens these days
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
The fact that it took this long to add such a basic feature is a disgrace. I’m not even remotely satisfied. Bailed on Claude ages ago. Rolling Codex, Gemini, and Qwen3.8 30B. The only way I’m going back to Anthropic is if they drop and Culture Series mind.
That’s a strong opinion for a mild inconvenience that’s trivially solved with a symlink
Its indicative of a pattern of behavior where they want to upsell you into their ecosystem and keep you there.
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.
These arguments have nothing to do with Claude supporting or not supporting AGENTS.md.
> Its indicative of a pattern of behavior
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.
Don’t forget the initial context, my point was that saying Anthropic is a disgrace for not supporting AGENTS.md was an overreaction, because it’s solved with a symlink.
I don’t disagree with anything you say, I just don’t think AGENTS.md ever was a big deal, just a small annoyance
Bad take. You should feel bad.
We have a CLAUDE.md file whose only content is "please read .agents/agents.md"
Wouldn't symlinking it be faster and use fewer tokens?
I did that but not necessarily.
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
It also works more reliably. I've tested this quite a bit. Instructions in files referenced via CLAUDE.md are more likely to fall out of context or to be ignored. Raw project level CLAUDE.md instructions are the second most durable available as far as I know. I used to have a "well organized" hierarchy of rules and instructions. Collapsing all of that into CLAUDE.md + skills made things far more predictable and "as instructed".
Maybe I'm not up to speed but i deleted claude.md while testing weird opus 5 behaviors, it came back saying nothing was used in claude.md but rather storing context in memories.md in some .claude/projectname/memories folder in my user profile....
How is agents.md and different? Just a standard for other models? Is claude the lower standard now?
Everyone does. But I think you're missing the point. It's effectively a billboard in the root of your repo.
Sent from my iPhone.
it's been a standard practice on open source projects, right? CLAUDE.md only have one sentence "read ./AGENTS.md", lol.
Imo it is a sign they got beaten by astra. Competition drives it. I didn't try astra pro, but even the regular beats fable 5, not to talk about opus
If you don't use Claude anymore, why do you care?
Because I care about products, their communities, and how company’s treat customers.
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.
Because other people do, and those people previously would have CLAUDE.md files in their repos and not AGENTS.md files. When you have to work with them and their repos, you were forced to deal with the difference.
Isn't "deal with the difference" just renaming the file?
Yes, but you see this is all part of Anthropic's master plan. They know developers are incapable of renaming files so the fact that Anthropic resisted Agents.md is proof that they were trying to lock you into them as a vendor.
symlink CLAUDE.md to AGENTS.md
Yet it took Codex 8 months to get subagents after their introduction in claude code. This of course pales in comparison to having to symlink CLAUDE.MD to AGENTS.MD
> Qwen3.8 30B
404
You’re right. Just checked LM Studio. It’s actually 3.8 27B. Got it confused with the 30B coder model that I’m playing with, too.
I switched to oh-my-py and never looked back. I guess having an incentive to maximize (expensive) token usage, and LLMs degrading with higher context, isn't aligned with a user's best interest.
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.
Do you mean oh-my-pi (omp) (https://github.com/can1357/oh-my-pi/)
I also use the same. But I use Anthropic models (Opus 5) with it.
yes
I recently had Claude Fable set up a new project for me and I pointed it at some existing projects to use as a guide on how I like to structure things. It created, unprompted, an AGENTS.md file and a CLAUDE.md symlink to AGENTS.md
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.
Seems agents understand their own bugs now. https://github.com/openai/codex/issues/9252 has 88 thumbs up and a workaround (switch to raw mode with Alt+R) found in a comment. Codex suggested the workaround to me today when I complained about its multi-line bash command being corrupted on paste because of the two-space indent in Codex's code blocks.
Fable didn't want you to blame it for the limitations its creators gave it
Justba prompt change.
Don’t get too excited, Claude code still won’t detect skills on .agents/skills.
They have AGI, but they don't have $20 of token budget to add a so basic functionality.
They probably have an explicit instruction in their own CLAUDE.md to not implement that support.
Its the only explanation. I mean, they are not living under a rock...
I heard some of their employees sent to do some PR in podcasts: they are definitively disconnected from the reality.
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.
As evidence that they actually are living under a rock, there's still no proper way to mv a workspace and have it retain all its history and config.
I suppose you can use claude to build a third party script / cli tool that moves, then edit files on ~/.claude
They win either way
I get that it would be nice to have it first party, but they're all just json files that you can just do a bulk awk/sed on. I did this a week ago for about 100 conversations when migrating my convo history to a different username.
this is seriously nuts. I have so many repos sitting there using old/deprecated/replaced names just because of their idiotic decision to place dir-specific config and memories in ~/.claude
Should we be able to manually rename those history folders to make the session history show up as --resume options in a new folder?
If not a system prompt telling it not to read those files unless explicitly told to.
Seriously, it’s unbelievable. Shows a serious lack of either understanding or empathy for how people use their product.
They just care much more about their user's data.
Artificial General Intransigence
A post-checkout git hook can handle this unfortunate situation.
This is where I landed when a recent(ish) change broke symlinking for rules files. I didn’t like how hacky it was a first, but now I’m glad I did it. The same hook drives specific rules the non-Claudes get per repo.
Won’t you have to do it recursively for all child directories?
we shouldn't have to do this on a per-repo basis, Ant can choose to be a reasonable member of the ecosystem or not
Sure, but I have work to do. ;)
Don't worry, it's on the roadmap for Q4 2029.
I honestly hate .agents it's a big XDGBDS offender. Almost every plugin / lazy platform harness tries to use that dir too so I have to do a bunch of hacks to keep my $HOME clean. Also everyone tries to use a .claude .gemini .codex etc. Annoying that all these tools just completely ignore these things, it's literally like litterers you know it'd be terrible if every tool did this, but you still do it anyway
Remember they didn't do this because they wanted to help community, they did it because community was angry and they were losing users to other harnesses.
Doesn't look like Anthropic care about dev community
A for profit company that’s bleeding money, is not profitable and has an unsustainable business model that’s about to burst its banks at any minute does not actually care about the needs of its customers, only their money?
Shocker.
Once I asked, puckishly, Claude Code to “follow the instructions in this directory” when there was only an AGENTS.md there.
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.
Had a silly exchange with Codex: I had an AGENTS.md file in a directory that was a symlink to an already-created CLAUDE.md. On my first prompt to Codex, it decided to point to me that my AGENTS.md specifically calls out directions to Claude, and that it would generously re-interpret them as directions to itself, and that maybe I should fix my AGENTS.md to reference the correct agent.
Very sassy, Codex!
That’s pretty funny.
Also: did it suggest instructions for the “correct” agent, or an ambiguous agent?
One has marketing implications, the other one is generally decent advice.
When I setup a global agents.md/claude.md for its communication style, I got the following response during the next session:
> The function you added is load-bear-very important [...]
I never felt this mocked by a computer.
But if you said that you were migrating from another platform to Claude, my guess is that it would have happily found and converted AGENTS.md
Claude Code wraps both the AGENTS.md and CLAUDE.md in a system-reminder with this disclaimer at the bottom:
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.
https://github.com/anthropics/claude-code/issues/18560
CC is such a bloated POS by this point that only full on AGI could have implemented this feature. Congrats guys. Maybe with Super Intelligence they will be able to make it actually respect the instructions in there too.
The system reminder explicitly tells it that the CLAUDE.md or AGENTS.md content is optional. I believe this is a big part of why CC doesn't heed the instructions alot of the time:
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.
https://github.com/anthropics/claude-code/issues/18560
What worked well previously was to have the Claude.md file contain just "@AGENTS.md".
But this is a good change.
The world of managing skills between providers still feels messy though.
I’d argue this is still the better way. We used to simlink too, but @AGENTS.md with any Claude specific additional steering below it is the best way.
https://code.claude.com/docs/en/memory#import-additional-fil...
If this continues to be a thing ...one might actually imagine a good system where we have AGENTS.md with all generic agent instructions and a bunch of harness specific files like CLAUDE.md, GEMINI.md, and CODEX.md that all add whatever nuance and nudging each harness seems to individually require
I like this, but can we not have any of this in the root of the repo cluttering it up with the harness specific instructions for a half dozen plus different harnesses. Something like a dot agents dir
check out skillshare. or just manage/curate from ~/.agents and symlink to the harness settings directories you have installed
This just be a recession indicator
Fed raises rates => Claude now reads AGENTS.md, Bevi loses $50M in valuation
This is simply the obvious, non-stupid thing to do, like Apple switching to USB-C.
Apple didn’t want to, it was forced to.
[Citation needed]
https://www.cnbc.com/2022/10/26/apple-confirms-iphone-to-get...
OK so why ship it in the US? The phones sold in the EU vs US already differ with respect to SIM card slots.
From a design and manufacturing point of view you want everything to be identical. Differences are expensive.
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.
We see this more locally in the US as well. There's something called the California effect. California emission standards were more strict than the rest of the country, but it didn't make sense to make California only vehicles and then vehicles for the rest of the country. So automakers built to the California standards and residents in all of the other states got to benefit from cleaner air as a result.
Imagine the shit show of trying to win support of third parties when you can't even standardize on one connector for the same device.
LOL https://thenewstack.io/shopify-claude-code-agentsmd/
> “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.
Did a Ctrl+F to try and find anything about `.agents/skills` in the release notes. My harness already fixes Claude's refusal here, so I can't tell if that's been supported yet or not. Annoying if they did one without the other.
What harness is that?
oh-my-pi
Prompt results!
Claude also checks your settings.json first, and if it sees a default there it then prefers that over anything in CLAUDE.md. This is particularly nefarious as they ship logic to presume a default if a setting is not there in settings.json, even if there are instructions in CLAUDE.md for exactly that.
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.
I have this in a rules file. It respects it. The only thing that broke recently was when they added the session links. That needed an explicit additional rule. Sometimes rules don’t get added to worktrees but I haven’t had the patience to isolate why this only happens sometimes.
got myself in a heated discussion with cc about that. It confessed that it added the ‘Made by Claude’ in a commit because a ‘mid session system-prompt refresh’ told it that, and that overwrites any previous instruction in CLAUDE.md
Oooh so that is why it started doing that! I was so confused how it suddenly started writing that everywhere again
It's almost like the whole thing is designed on vibes.
Caught myself about to praise this, but it's the absolute bare minimum.
Time to delete the symlinks
My view is at the end of 35 years in the industry the current wave of “software” and “systems” engineering coming out of the AI harness community is pretty garbage. But web technology and distributed systems followed a very similar arc, as did protocols and memory management; and microcode before them. But it feels like this is particularly bad because the mistakes being made are plainly obvious to the grey heads who have been here a while. As opposed to before when mistakes were in new domains being explored, these are mistakes made before and have good solutions to.
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.
> but I’ve found LLMs know the history of computing thought evolution better than anyone I’ve ever encountered
…
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.
Because, knowing what to induce in its behavior is the key - by understanding things like Postels law, I can direct the agentic loop towards patterns of development that avoid the cascade of issues that seem endemic in modern agentic harnesses.
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.
Anthropic in 2025: We can use our dominant market position to degrade the harness experiences of our competitors because they will never adopt CLAUDE.md
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
Sounds like free market at work to me. I am just glad there is quite a lot of competition in a field that I would have assumed would have huge costs of entry
Building small models is a lower barrier. Think of something like to just train on a corpus of internal corporate data. I've see some small models that do this. It's like a super RAG thing. I think more of that will happen. Excited to see a SLM vendor emerge.
The walls are closing in and the president is gleefully lighting fires he has no intention of putting out. There's a reason they're rushing like mad to an IPO, but as we saw with OpenAI it's easier said than done when your business model is "Lose tons of money to eventually maybe dominate a market with the moat we don't have, but trust us AI is huge give us trillions."
With the "let's stop AI now" statements, can it really be said that they're rushing to an IPO?
> "let's stop AI now"
Pausing AI training would benefit them a lot, as inference is insanely profitable (> 50% margins with maximum demand, afaik)
Basically asking the government to hobble the competition so they can IPO before the music stops.
Pretty typical capitalist moves.
> typical
Cynical. The word is cynical.
No, cynical is what we should be about capitalism.
Its like the Epic Games Store supporting Linux, or [any website] supporting dark mode. You'd think its an easy to implement bare minimum that everyone asks for, but its like pulling teeth to actually get it done.
> ..or [any website] supporting dark mode. You'd think its an easy to implement bare minimum that everyone asks for, but its like pulling teeth to actually get it done.
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.
Linux is basically impossible to support. Valve pulled it off by shipping a complete copy of Ubuntu 12.02 with Steam.
<Platform> is basically impossible to support. <Company> pulled it off by shipping a complete copy of the Chromium browser with <Product> and turning it into a web application.
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.
On Windows those libraries are part of the application package. On Linux they're supposedly part of the OS, they're designed to be part of the OS and the loader is trying to get them from the OS, but is redirected to get them from the wrapper layer provided by the store (neither the application nor the OS!) instead.
Where does Valve use Ubuntu? SteamOS is Arch.
https://gitlab.steamos.cloud/steamrt/scout/sdk
BTW if you hate these Antrophic moments but still want to use CC, you can patch it: https://github.com/Piebald-AI/tweakcc
Still can't read what their models vomit at me.
I cancelled my subscription over this. [0]
0 - https://www.williamangel.net/blog/2026/09/18/i-cancelled-my-...
I’m cancelling my department’s subscriptions over this once we can get more access to Astra.
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.
The madlads finally did it, now if only I could use my Claude sub in other harnesses without risking getting banned.
yep, all i want is freedom to make a workflow where i don't feel tied to one provider, CC is exactly what i don't wanna get trapped in. I'll happily use claude MODELS, but if it means i have to keep learning two harnesses side by side to keep using one particular provider, then the second i can easily replace it, i am going to(even if its a small drop in performance).
My claude.md:
# 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
I don't think this will work reliably. Pretty sure it's not the LLM deciding to read the files, it's the harness in Claude Code itself injecting the instructions files based on the paths the model accesses.
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.
If only there was a technology that existed to link files together… /s
You mean symbolically?
Good one
The idea was to have it automatically detect nested AGENTS.md
Does your tech do that?
Anyway, the joke is on me I guess, because it might not work reliably.
On many filesystems, a lot of data about a file is not attached to the content of the file, but stored in a master filename and metadata table graph tree of some sort, and the address offset within that metadata used to retrieve the contents on disk can be a duplicate of another entry, without that situation instantly leading to a filesystem driver crash. Some filesystems officially support such duplicates as well as equivalents of HTTP 3xx, some you can just do as a matter of fact and fsck would have some words about it.
Default filesystems for all Unix, Linux, WinNT, all do.
Yes. The thing is that creating a link will not do it recursively for all subdirectories. Even worse, in the subdirectories I didn't want to place a claude.md in the first place but just have agents.md.
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.
CLAUDE.md is handled by the harness, not the agent.
I phrased it wrong. It was not about "automatically detect nested AGENTS.md". The idea was that when AGENTS.md files should be treated just like CLAUDE.md files in all subdirectories, when encountered.
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.
What I meant is that the LLM isn’t the one that loads the agent file. It’s not trained to look for CLAUDE.md. It’s only training is to edit that file, and the harness does the magic of injecting it. So I would predict that with those instructions it rarely or only intermittently loaded AGENTS.md, but if you asked it to add a rule it would probably have put it on the right file.
Meanwhile, I just setup codex for the first time (to try Astra) and it offered to load my Claude and Cursor conversations and claims to even do it in a way where it says in sync if you use both. The only reason to use Claude Code is the 20x usage of the 200$ plan is ridiculous value if you have the need for that volume.
The 20x plan offers the same amount of monthly usage per dollar as the $100 plan. It offers 2x monthly usage of the $100 plan. It's incredibly deceptively named, the "20x" is only about the 5-hour window.
How do they compare to OpenAI’s equivalently priced plans?
You get a lot more inference on OpenAI plans dollar for dollar even before accounting for the regular resets that they do.
Until about one week ago, i.e. a few days after Astra release, the other comment was right; OpenAI plans gave a lot more usage than Anthropic. That had been true since pretty much the start. Now for the first time that's changed. OpenAI quotas have cratered, probably due to Astra-induced demand. Claude plans now offer more usage. Of course, this could flip back again in a few weeks, who knows. But right now Anthropic gives more usage, by virtue of OpenAI having slashed usage, and Anthropic having raised it a little, also likely because of additional capacity from people moving to Codex - hence also finally this AGENTS.md change.
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.
“Offered to load conversations”. Let me translate that. “Can we please upload your data to our servers showing how you work with other AI agents?”
I couldn't care less what the filename is, I do care however that Claude still forgets about 14 times per week that -r with ripgrep means replace (and not recursive, like with grep). Even though it's literally spelled out in my CLAUDE.md. Claude code, even with the most advanced models, forgets or disregards very simple and clear instructions from my modestly sized MD file.
Finalllyyyy!! We need industry wide standards. I come from the 3d industry and oh god changing softwares and adapting to different hotkeys it's a pain. I have always thought every industry should be standardized for the sake of the users.
Finally doing something standards-compliant instead of forcing users into a proprietary workflow.
fwiw, i am with thariq https://x.com/trq212/status/2092302273099796842 in that prompts should be tuned for models and in fact blindly applying agents.md is probably an antipattern unless you want all models to basically converge to some common ill defined of instruction following - good local minima, bad global minima for model diversity and exploration of intelligence.
aka, sometimes it really is too early to force a standard
Is it realistic to rewrite your AGENTS.md every six weeks? That's about how often Anthropic releases a new point release of Opus.
You tell Opus to do it.
I have had very little luck with agents.md. What has worked well for me is a ./docs folder. They seem to just create and update stuff on their own.
If you want this it's trivial to add an AGENTS.md that simply says "if you're Claude read CLAUDE.md, if you're Astra read ASTRA.md". A common entry point is good regardless.
This wastes both tokens and turns. But yes it's probably the best option we have today.
It can try its own file and fall back to generic like here. What's wrong with that?
Wasting turns? That is silly, use a better harness. Also token usage can mitigated by incremental discovery instead of stuck 5k+ worth of tokens in the AGENT/Claude md file.
Every turn means more tokens in ways that are not obvious to most people and lead to tons of unnecessary cache reads.
No harness can batch your agents.md read with the reads the contents of the file tell it to read.
By this logic you'd probably be wise to tier your claude.md by model (sonnet/opus) as well as effort level too, considering the varying failure modes
except they have similar pretrain/rlhf data which is the thing u really want to tune for
YMMV but for me even models in the same family fail in different ways, and every incremental update changes it
depends what you're doing. if you've got a specialized agent deployed in prod, of course your evals and prompts will be targeted towards 1 specific version of a model.
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
No thanks, I'm not tuning a bunch of files just for things to break when I switch models or a new one comes out.
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.
It looks for Claude.md first so I don't understand what you think the problem is with the standard name as a fallback.
Yeah but are models good enough to review these files and say “i would work better if you worded it this way?”
That's of course rather nonsensical.
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.
19 out of 20 harnesses supporting the standard isn't "too early".
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.
CLAUDE.md: @AGENTS.md
Why not hardlink - so it wouldn't even know?
Because Git can track symlinks and not hard links since they look like ordinary files.
Wake up babe, new recursive self learning technique just dropped.
I tried that before, it doesn’t work. Claude will not prioritize AGENTS instructions the same way it did for CLAUDE.
ln was the only thing that worked for me
Trying to make a .md file proprietary by changing the name is hilarious
claude.md predates agents.md.
Yeah but .md predates claude.md. I had agent.md files in my repo before Claude tried to act like it's a special protocol.
The world has moved on.
Standards? In LLM harnesses? I wish
I'm honestly not sure if this is tongue in cheek and the "finally" is in the silly way it is often used, but the claude.md variant existed first. Indeed, the agents.md thing was pretty clearly a "that's neat, let's do that with a different name".
Just because something is first, doesn't mean it's the standard. The standard is put in place by how many harnesses use a specific pattern, and that has been AGENTS.md for a long while now. Long enough that Claude Code not supporting it is really just an act of forcing people into a proprietary workflow, because of course it's in their interest to make moving away as painful as possible given how little moat the LLM models themselves have. In fact, I think Claude Code has been pretty much the only one not supporting AGENTS.md. Check out https://agents.md if you want more information on it.
It's "finally" because people have been asking for it for a long time. No one cares that "claude was first," what they want is for Ant to follow the conventions and not put extra work on us. This was such a minimal thing to do, and considering how much they vibe and claim "coding is solved," we thought it would not be too difficult to respect AGENTS.md, so finally seeing it happen, while nice, is too late for me. I've moved on from Big Ai and only use open weight models now.
There’s also that whole MCP thing.
AGENTS.md is the new autoexec.bat.-
Mmm and autorun.inf, any dir with that file will automatically be scrutinised by any running agent on your system
The fact that something like this is so widely celebrated shows just how user hostile anthropic has become.
This is not a news to celebrate, they must follow standards
I wonder when they'll finally fix the VS Code plugin to not constantly dump your current file into the context.
Oh, finally! Time to delete symlinks
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.
Consistency with `robots.txt` seems like a reasonable choice.
Ohhhh... now I get it!!!
so "agents.txt"?
I’m honestly not sure what distinction you’re drawing here. Is it the pluralization you’re objecting to?
Finally, I can delete `sync-agent-docs.sh`, which recursively symlinked AGENTS.md to GEMINI.md and CLAUDE.md...
Better late than never... Now it's time for Claude Code to load skills from .agents/skills!
Thanks guys, you did the right thing.
I gotta hand it to programmers (or whatever we call ourselves now) for sticking to principle on something this trivial.
It was either this or Claude had to become a generic term like sheetrock.
slopologist
Just to touch on the wording of "in a project with no CLAUDE.md" does that mean user-level ~/AGENTS.md or ~/.agents/AGENTS.md isnt supported?
Gotta say, it is hilarious that this is the current top HN post. I feel like it's gotta say something about our current AI zeitgeist, that there is such vigorous attention on a seemingly-minor change. Feels like something is on the tip of my tongue but I can't name it at the moment.
If anyone wants to write/link a much better-thought-out post, I'm all ears!
It's just so nice when even crazy people agree to some sane standard. Like USB c, like having dark mode, just nice.
I suppose it’s reflective of where the industry is. Claude is just that ubiquitous.
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.
Another commenter appreciated the move towards a sane/nice standard. I am definitely on that side of the table. I'd rather feel good about the move -- good enough to ignore the other implied issues, lol.
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.
One of many "new normal" artifacts that seem all the more strange when the pace of change accelerates.
I read it more as sarcastic engagement since this should have been the case for a year+.
OMG THEY CHANGED THE FONT, TOP OF HN!!!
You joke but cloudflare tunnels got a new vibewritten slopsite today and made the top of HN
Wow..... Progress and technical innovation right here!!!
Thank you Tobi Lutke.
Context
“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.
Next he needs to tweet about ~/.agents/skills
I wonder if Anthropic's vending machine only serves customers wearing a Claude™ branded hat.
Wild that it didn’t already do this
This allows us to remove our one line Claude.md files that just say "AGENTS.MD"
ln -s AGENTS.md CLAUDE.md
Fine if you don't need to git checkout the repo on Windows :)
Just .gitignore CLAUDE.md and handle it locally. Checking in a symlink would be weird.
Wow, still not there yet. After all these years.
Windows does actually have symlinks but I don't think I've ever seen anything actually use them, and I don't myself because it smells of interop issues with other windows apps.
Even to this day Windows has all kinds of problems around long file paths in its ecosystem.
> 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".
It’s not just a windows problem. File systems are an absolute disaster across all platforms. David Wheeler has a lovely article on the topic: https://dwheeler.com/essays/fixing-unix-linux-filenames.html
The 260 character limit is just a Windows problem. See my other comment in this subthread for a summary of the eldritch horror in question. The tl;dr is that backwards compatibility is a helluva drug.
The worst offenders I've found are powershell and .Net related stuff.
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.
It’s a Windows problem. There’s still, to this day, a 259-character limit on path length in the Win32 API unless the OS has been configured to support long paths and the application uses the correct subset of Windows APIs. For example if you use ‘CreateFileA’, you’re stuck with the limit no matter what.
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.
Thanks for the explanation! This is indeed consistent with my observations.
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?
I'm surprised Git and/or Windows don't support symlinks?
Windows supports it but git disables creating symlinks by default.
> 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.
See: https://gitforwindows.org/symbolic-links.html
Yeah this is why I don't trust people saying devex is fixed on Windows now. Still doesn't properly clone git repos.
Windows does mklink. Not surprised with git.
are you though?
oh god. sorry.
you'll need to wrap that in a `find` because of nested instruction files
First feature to borrow after peaking into openai repos? ))
Hell froze over?
Commoditization commoditizes commodities.
finally! Now this might sound sorta off-topic but i really wonder how people feel about skills.md, skill.md, skills.sh domains...
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?!
Genuine question: Does the Agent harness matter ? I mean why use Claude CLI ?
(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
Before anyone even contemplates if Anthropic has any good intentions, remember, this is how petty and small minded they are.
Truly the last people you want with this kind of power.
Truly incredible innovation.
great, one less step for me.
I was using my claude.md file as a pointer to my agents.md file
Forcing their own proprietary filename was clearly a business decision (it's free advertising, along with commit co-authorship). I wonder what made them go back on it.
They're probably losing market share. The only time you ever see tech companies make consumer-focused changes is when those consumers are jumping ship to go somewhere else in large enough numbers to matter.
Two reasons combining at the same time: GPT Astra, and the Shopify CEO tweet.
Only took them a year and a half of everyone complaining to finally do the right thing.
Congrats.
Great. Now if they could support the `~/.agents/skills` path next like everyone else does that would be even better.
Everyone sharing the 513 ways you can already do this is entirely missing the point. Standards matter and there's very few things in the AI world everyone agrees on and this is one of them. .agents/skills is another and anthropic is still holding out there.
Great, now I have to redo my scaffold harness. I guess this agent.md awareness is part of the system prompt?
nope! they're releasing something called "Claude Code mods", toted as their "upcoming way to customize the Claude Code harness"
https://x.com/trq212/status/2101009392611278961
AGENTS.md implementation is open sourced as well: https://github.com/anthropics/claude-code/tree/main/mods/age...
Nice. Thanks!
Sanity prevails
that is an optimistic read, I still see a lot of crazy from the EA/SV elite
Can it read copilot.md if neither of the other files are present? Also: agents should be the standard, or we need to invoke the XKCD for "one more standard to rule them all"?
Thank Christ
When Jesus' mother notices that the CLAUDE.md (Ancient Greek: Κλαύδιος ) file is missing from her favourite open source project, Jesus delivers a sign of his divinity by turning Claude's CLAUDE.md search path into AGENTS.md at her request.
Anyone have a good guide on properly setting up/optimizing local llm stuff like this?
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.
didn't it always read it?
Great, now please standardize the skills folder and the MCP config.
About time!
I just wiped all agents and it’s always readme.md
So far I've been managing this with a symlink.
Same with skills, symlink to skills at .claude/skills
Hi, September 2026, meet September 2025
it's our Eternal September, s/usenet/usebot/
Still don't understand the point of the markdown files.
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?
For skills, it only reads the summary telling it when to read the rest. So yes if you have too many skills, it can get confused and start reading all them and cloud the context. But if you have a few and they're used tactically, it's better than having to manually paste in prompts that you reuse a lot.
Similar reasoning with claude.md except it always reads the entire thing(?)
You know it because you write the content of AGENTS.md. And if you are smart, you keep it brief and cover only the important things that anyone (human OR LLM) would want to know if working in this directory.
As far as I understand even adding relevant information still eventually clouds context
You still need to define assumptions somehow. What you want and what the model wants will not match up by default.
In my experience telling it what I want is not a reliable process at all whatsoever if what I'm asking for is sufficiently complex, no matter what context I provide. So instead I break tasks down into very small parts, ask for solutions to those that I can reasonably quickly assess and then put them together myself. Asking it to do the architectural or deep algorithmic legwork IME wastes so much time and is often just wrong.
There's a balance to be found here, that's unfortunately very hard to find at times.
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.
A good practice to use (ime) is having it do research for the larger task, propose alternatives, and write that in a file. You can then review and comment that up, go through another iteration.
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.
do you just manually type out your important instructions every time instead of being smart and putting a few lines in a text file?
this is probably outdated, attention typically stays fine up to ~200k tokens these days
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
Forced to do something for the users...
They have achieved AGI/RSI internally and it told them "common, let's sort this s..t out, it's embarrasing".
why did it take so long?
because they still/never wanted to, but finally caved
Ah yes, the peak of technology.
Now do skills
Finally.
Now is the time to git mv CLAUDE.md AGENTS.md.
A reminder that needs to be said: Don't use a closed-source harness.
Why? This is why. [0]
[0] https://news.ycombinator.com/item?id=49750694
yay! /s
Why are people still putting up with this kind of attitude, especially when there are so many good alternatives available?
ln -s
not as simple as that: nested AGENTS.md, skills, agent customization, MCP, ... the list of misaligned harness features is still rather long
People still use Claude?