Nice. Thanks!

First feature to borrow after peaking into openai repos? ))

Wake up babe, new recursive self learning technique just dropped.

Because Git can track symlinks and not hard links since they look like ordinary files.

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

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.

Yeah but are models good enough to review these files and say “i would work better if you worded it this way?”

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

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.

YMMV but for me even models in the same family fail in different ways, and every incremental update changes 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.

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.

It can try its own file and fall back to generic like here. What's wrong with that?

You tell Opus to do it.

It looks for Claude.md first so I don't understand what you think the problem is with the standard name as a fallback.

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.

There’s also that whole MCP thing.

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.

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.

The world has moved on.

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.

Standards? In LLM harnesses? I wish

Thanks guys, you did the right thing.

Don't worry, it's on the roadmap for Q4 2029.

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

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 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.

If not a system prompt telling it not to read those files unless explicitly told to.

Artificial General Intransigence

Won’t you have to do it recursively for all child directories?

Sure, but I have work to do. ;)

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

oh god. sorry.

Just .gitignore CLAUDE.md and handle it locally. Checking in a symlink would be weird.

are you though?

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.

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.

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.

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?

you'll need to wrap that in a `find` because of nested instruction files

Only took them a year and a half of everyone complaining to finally do the right thing.

Congrats.

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

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.

Basically asking the government to hobble the competition so they can IPO before the music stops.

Pretty typical capitalist moves.

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.

https://gitlab.steamos.cloud/steamrt/scout/sdk

<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.

..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.

They have achieved AGI/RSI internally and it told them "common, let's sort this s..t out, it's embarrasing".

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).

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 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

Finally, I can delete `sync-agent-docs.sh`, which recursively symlinked AGENTS.md to GEMINI.md and CLAUDE.md...

Good one

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.

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.

Justba prompt change.

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

not as simple as that: nested AGENTS.md, skills, agent customization, MCP, ... the list of misaligned harness features is still rather long

I cancelled my subscription over this. [0]

0 - https://www.williamangel.net/blog/2026/09/18/i-cancelled-my-...

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

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(?)

About time!

Wow..... Progress and technical innovation right here!!!

This is not a news to celebrate, they must follow standards

because they still/never wanted to, but finally caved

Fed raises rates => Claude now reads AGENTS.md, Bevi loses $50M in valuation

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.

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

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.

Great, now please standardize the skills folder and the MCP config.

It's almost like the whole thing is designed on vibes.

Oooh so that is why it started doing that! I was so confused how it suddenly started writing that everywhere again

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.

Prompt results!

oh-my-pi

it's our Eternal September, s/usenet/usebot/

Truly incredible innovation.

Hell froze over?

great, one less step for me.

I was using my claude.md file as a pointer to my agents.md file

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"?

Ah yes, the peak of technology.

Mmm and autorun.inf, any dir with that file will automatically be scrutinised by any running agent on your system

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?!

I wonder when they'll finally fix the VS Code plugin to not constantly dump your current file into the context.

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.

that is an optimistic read, I still see a lot of crazy from the EA/SV elite

Great. Now if they could support the `~/.agents/skills` path next like everyone else does that would be even better.

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.

Commoditization commoditizes commodities.

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.

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?

Wild that it didn’t already do this

didn't it always read it?

Now do skills

Better late than never... Now it's time for Claude Code to load skills from .agents/skills!

One of many "new normal" artifacts that seem all the more strange when the pace of change accelerates.

It's just so nice when even crazy people agree to some sane standard. Like USB c, like having dark mode, just nice.

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.

You joke but cloudflare tunnels got a new vibewritten slopsite today and made the top of HN

I read it more as sarcastic engagement since this should have been the case for a year+.

So far I've been managing this with a symlink.

Same with skills, symlink to skills at .claude/skills

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?

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.

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.

I just wiped all agents and it’s always readme.md

“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?”

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.

slopologist

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.

Isn't "deal with the difference" just renaming the file?

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's been a standard practice on open source projects, right? CLAUDE.md only have one sentence "read ./AGENTS.md", lol.

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?

Qwen3.8 30B

404

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

Finally.

Now is the time to git mv CLAUDE.md AGENTS.md.

People still use Claude?

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.

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.

check out skillshare. or just manage/curate from ~/.agents and symlink to the harness settings directories you have installed

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...

I wonder if Anthropic's vending machine only serves customers wearing a Claude™ branded hat.

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

BTW if you hate these Antrophic moments but still want to use CC, you can patch it: https://github.com/Piebald-AI/tweakcc

The fact that something like this is so widely celebrated shows just how user hostile anthropic has become.