Claude Code now reads AGENTS.md if there is no Claude.md

245

ddatadrivenangel about 2 hours ago 97 commentsRead Article on code.claude.com

FR version is available. Content is displayed in original English for accuracy.

⚡ Community Insights

Discussion Sentiment

81% Positive

Analyzed from 1683 words in the discussion.

Discussion (97 Comments)Read Original on HackerNews

rukuu001•about 1 hour ago

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.

ryandrake•26 minutes ago

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!

DANmode•14 minutes ago

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.

katzgrau•11 minutes ago

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

askonomm•about 1 hour ago

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

swyx•33 minutes ago

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

orlp•4 minutes ago

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.

esikich•14 minutes ago

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.

SoftTalker•9 minutes ago

Try naming the file "not_for_claude.md"

TomGarden•15 minutes ago

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

willsmith72•21 minutes ago

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

arcanemachiner•30 minutes ago

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.

atonse•23 minutes ago

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

groby_b•18 minutes ago

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.

klodolph•about 1 hour ago

CLAUDE.md: @AGENTS.md

fphilipe•about 1 hour ago

    ln -s AGENTS.md CLAUDE.md

kreetx•20 minutes ago

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

mlnj•about 1 hour ago

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

gcampos•39 minutes ago

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

llm_nerd•18 minutes ago

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

bredren•4 minutes ago

There’s also that whole MCP thing.

stillpointlab•about 1 hour ago

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.

reedlaw•about 1 hour ago

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.

cyanydeez•about 1 hour ago

Justba prompt change.

TomGarden•about 1 hour ago

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

Time to delete the symlinks

jtbaker•about 1 hour ago

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.

clutter55561•about 1 hour ago

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

vb-8448•about 1 hour ago

They have AGI, but they don't have $20 of token budget to add a so basic functionality.

bel8•about 1 hour ago

They probably have an explicit instruction in their own CLAUDE.md to not implement that support.

sscaryterry•38 minutes ago

Its the only explanation. I mean, they are not living under a rock...

nomel•about 1 hour ago

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

jjordan•about 1 hour ago

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

orlp•6 minutes ago

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

Havoc•4 minutes ago

Sanity prevails

orliesaurus•12 minutes ago

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

aroman•about 1 hour ago

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

throwaw12•about 1 hour ago

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

budoso•about 1 hour ago

This just be a recession indicator

bakugo•5 minutes ago

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.

sscaryterry•about 1 hour ago

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

seaal•about 1 hour ago

The madlads finally did it, now if only I could use my Claude sub in other harnesses without risking getting banned.

sidrag22•about 1 hour ago

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

dinga•about 1 hour ago

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

frizlab•about 1 hour ago

If only there was a technology that existed to link files together… /s

gberger•about 1 hour ago

You mean symbolically?

frizlab•about 1 hour ago

Good one

dinga•about 1 hour ago

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.

numpad0•30 minutes ago

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.

Bluestein•14 minutes ago

AGENTS.md is the new autoexec.bat.-

mitchitized•about 1 hour ago

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.

neverrroot•about 1 hour ago

Thanks guys, you did the right thing.

egorfine•32 minutes ago

Hell froze over?

moecables•31 minutes ago

great, one less step for me.

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

mococa•about 1 hour ago

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

getpokedagain•about 1 hour ago

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

datadrivenangel•about 1 hour ago

This allows us to remove our one line Claude.md files that just say "AGENTS.MD"

whalesalad•about 1 hour ago

ln -s AGENTS.md CLAUDE.md

lolpython•about 1 hour ago

Fine if you don't need to git checkout the repo on Windows :)

Arcuru•about 1 hour ago

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

skeledrew•about 1 hour ago

Wow, still not there yet. After all these years.

jpollock•about 1 hour ago

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

whalesalad•about 1 hour ago

oh god. sorry.

cmrdporcupine•about 1 hour ago

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

Congrats.

a3w•28 minutes ago

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

SrslyJosh•about 1 hour ago

Truly incredible innovation.

alansaber•16 minutes ago

Ah yes, the peak of technology.

vindex10•about 1 hour ago

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

timcobb•about 1 hour ago

There goes their moat...

yieldcrv•about 1 hour ago

Hi, September 2026, meet September 2025

anukin•about 1 hour ago

Thank you Tobi Lutke.

fhub•about 1 hour ago

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.

armcat•about 1 hour ago

About time!

kislakiruben•about 1 hour ago

why did it take so long?

Madmallard•about 1 hour ago

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?

mcherm•about 1 hour ago

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.

Madmallard•about 1 hour ago

As far as I understand even adding relevant information still eventually clouds context

pixl97•about 1 hour ago

You still need to define assumptions somehow. What you want and what the model wants will not match up by default.

electroglyph•44 minutes ago

do you just manually type out your important instructions every time instead of being smart and putting a few lines in a text file?

hbarka•about 2 hours ago

Great, now I have to redo my scaffold harness. I guess this agent.md awareness is part of the system prompt?

sync•about 1 hour ago

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

hbarka•about 1 hour ago

Nice. Thanks!

blueaquilae•about 1 hour ago

Forced to do something for the users...

dude250711•about 1 hour ago

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

davidkunz•about 1 hour ago

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

rvz•about 1 hour ago

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

nunodonato•about 1 hour ago

yay! /s

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