Top stories

Nice. Thanks!

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

Finally doing something standards-compliant instead of forcing users into a proprietary workflow.

CLAUDE.md: @AGENTS.md

    ln -s AGENTS.md CLAUDE.md

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

42m agoHN ↗

Why not hardlink - so it wouldn't even know?

20m agoHN ↗

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

55m agoHN ↗

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

52m agoHN ↗

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.

45m agoHN ↗

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

43m agoHN ↗

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

40m agoHN ↗

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.

37m agoHN ↗

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

36m agoHN ↗

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.

27m agoHN ↗

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.

23m agoHN ↗

This wastes both tokens and turns. But yes it's probably the best option we have today.

17m agoHN ↗

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.

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

17m agoHN ↗

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.

40m agoHN ↗

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

26m agoHN ↗

There’s also that whole MCP thing.

19m agoHN ↗

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.

14m agoHN ↗

Trying to make a .md file proprietary by changing the name is hilarious

4m agoHN ↗

claude.md predates agents.md.

Thanks guys, you did the right thing.

Don’t get too excited, Claude code still won’t detect skills on .agents/skills.

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

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

49m agoHN ↗

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

A post-checkout git hook can handle this unfortunate situation.

  mkdir -p ~/.githooks
  git config --global core.hooksPath ~/.githooks

  cat > ~/.githooks/post-checkout <<'EOF'
  #!/usr/bin/env bash
  if [ -d .agents/skills ] && [ ! -e .claude/skills ]; then
      mkdir -p .claude
      ln -s ../.agents/skills .claude/skills
  fi
  EOF

  chmod +x ~/.githooks/post-checkout

16m agoHN ↗

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

16m agoHN ↗

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

4m agoHN ↗

Sure, but I have work to do. ;)

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

oh god. sorry.

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

I'm surprised Git and/or Windows don't support symlinks?

are you though?

See: https://gitforwindows.org/symbolic-links.html

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.

10m agoHN ↗

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.

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.

47m agoHN ↗

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

27m agoHN ↗

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.

13m agoHN ↗

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.

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.

Caught myself about to praise this, but it's the absolute bare minimum.

Time to delete the symlinks

15m agoHN ↗

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

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

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

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

[0] https://news.ycombinator.com/item?id=49750694

A reminder that needs to be said: Don't use a closed-source harness.

Why? This is why. [0]

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

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

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.

52m agoHN ↗

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.

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.

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.

yay! /s

Why are people still putting up with this kind of attitude, especially when there are so many good alternatives available?

ln -s

Still can't read what their models vomit at me.

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?

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.

41m agoHN ↗

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.

3m agoHN ↗

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?

8m agoHN ↗

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

why did it take so long?

11m agoHN ↗

because they still/never wanted to, but finally caved

There goes their moat...

This just be a recession indicator

13m agoHN ↗

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

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.

48m agoHN ↗

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!

36m agoHN ↗

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.

33m agoHN ↗

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

14m agoHN ↗

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.

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.

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

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.

Hi, September 2026, meet September 2025

12m agoHN ↗

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