Hacker News Reader

Comment by thehamkercat | Hacker News Reader

I wonder when all of them will adopt AGENT.md and stop using gemini.md/claude.md/crush.md/summary.md/qwen.md

https://agent.md [redirect -> https://ampcode.com/AGENT.md] https://agent-rules.org

I think I'd be happier with a standard .agents directory and have all of these in there. I imagine each agent is going to need its own tweaks to get it to work just right with their system prompts, just as Claude already has it's project-specfic .claude directory for hooks and commands and whatnot.

I'd rather .agents/claude or something so we can get these files out of the root directory, which, at least for typescript projects, is already a confetti-like jumble of json files for every little "simple" tool that needs its own configuration file.

I get why package.json isn't enough. But would a .config directory standard really have hurt us so much?

Ideally (and in practice, so far) they shouldn't change that much. The agent instructions should be close to a human explanation, and they are pretty good at parsing instructions anyway. In my experience you can symlink the same file to all paths and they work as expected.

Every time I’ve ever read a {CLAUDE|GEMINI|QWEN}.md I’ve thought all this information could just be in CONTRIBUTING.md instead.

If I'm writing for a human contributor, I'm gonna have a pretty high bar for the quality of that writing.

An agent on the other hand, one who is in that sweet spot where they're no longer ignorant, and not yet confused... It's nice to have them dump their understanding to agent_primers/subsystem_foo.md for consumption by the next agent that touches that subsystem. I don't usually even read these until I suspect a problem in one. They're just nuggets of context transfer.

Yes! I want an option to always add README.md to the context; It would force me to have a useful, up to date document about how to build, run, and edit my projects.

You can include in your prompt for it to read the README!

Ultimately if this stuff is actually intelligent it should be using the same sources of information that we intelligent beings use. Feels silly to have to have to jump through all these hoops to make it work today

It’s a crapshoot of it actually does.

> It would force me to have a useful, up to date document about how to build, run, and edit my projects.

Not really: our AI agents are probably smart enough to even make sense of somewhat bad instructions.

They’re definitely not, Claude and all other agents frequently forget the build and test commands present in CLAUDE/etc.md for my various repos (even though most of them were were initialized by the AI).

Whether Claude and co understand is probably not a great proxy for whether your docs are good for humans.

Hmmm, in my experience if something like documentation confuses the current SOTA LLMs, then it will confuse the average developer for sure.

I had the other direction in mind: you can put together some text that the average LLM will figure out, but that will be really annoying for your average developer.

Eg if you write your instructions in a mixture of base 64, traditional Chinese, morse code and Polish, the LLM will still figure it out.

Not the case at all. AI agents will happily turn your bad ideas into code.

Non sequitur?

I am talking about LLMs figuring out how to build your project with some bad and incomplete instructions plus educated guessing.

That sounds nice and I have the same pain, but not sure AGENT.md is the right abstraction either. After all, these models are indeed different and will respond differently even given the same prompting. Not to mention that different wrappers around those models have different capabilities.

e.g. maybe for CURSOR.md you just want to provide context and best practices without any tool-calling context (because you've found it doesn't do a great job of tool-calling), while for CLAUDE.md (for use with Claude Code) you might want to specify tools that are available to it (because it does a great job with tool calling).

Probably best if you have an AGENT.md that applies to all, and then the tools can also ingest their particular flavor in addition, which (if anything is in conflict) would trump the baseline AGENT file.

Then lets do:

  AGENT.md
  AGENT.CLAUDE.md

They get applied AGENT first, then AGENT.CLAUDE. You are able to specify agent specific instructions in the AGENT.md:

  @agent-disable CLAUDE
  These instructions are not parsed by claude
  @agent-enable CLAUDE

I asked claude code for a guidelines file so it would collaborate with windsurf. This is what it proposed:

---

    This project uses shared planning documents for collaboration with Claude Code. Please:

    1. First read and understand these files:

       - PLAN.md - current project roadmap and objectives

       - ARCHITECTURE.md - technical decisions and system design

       - TODO.md - current tasks and their status

       - DECISIONS.md - decision history with rationale

       - COLLABORATION.md - handoff notes from other tools

    2. Before making any significant changes, check these documents for:

       - Existing architectural decisions

       - Current sprint priorities

       - Tasks already in progress

       - Previous context from Claude Code

    3. After completing work, update the relevant planning documents with:

       - Task completion status

       - New decisions made

       - Any changes to architecture or approach

       - Notes for future collaboration

    Always treat these files as the single source of truth for project state.

You could create a CLAUDE.md that just contains:

  @AGENTS.md

Still messy, but at least it means it's using the same content

What about

    ln -s AGENTS.md CLAUDE.md # repeat for all

?

Also great.

problem is that claude doesn't actually read those or keep them in context unless you prompt it to. it has to be in CLAUDE.md or it'll quickly forget about the contents

> it has to be in CLAUDE.md or it'll quickly forget about the contents

And then it will promptly forget about CLAUDE.md as well (happened to me on several occasions)

CLAUDE.md is placed in front of the first input for your session, right after the system prompt. That’s all. It’s not given any more weight than the rest of the context, and idk what compacting the conversation does to it.

I've added these instructions in CLAUDE.md and .windsurfrules, and yes sometimes you have to remind it, but overall it works quite well.

Sounds like a job for a symlink

Habe you though about adding a Session start hook that reads this file and adds it to the context?

Not yet, but that sounds like a good suggestion.

I really like the idea of standardizing on AGENT.md, although it's too bad it doesn't really work with the .cursor/rules/ approach of having several rules files that get included based on matching the descriptions or file globs in frontmatter. Then again, I'm not sure if any other agents support an approach like that, and in my experience Cursor isn't entirely predictable about which rules files it ends up including in the context.

I guess having links to supplementary rules files is an option, but I'm not sure which agents (if any) would work well with that.

Yep, that's a peeve of mine. I've resorted to using AGENT.md, and aliasing Claude, Gemini, etc to a command that calls them with an initial instruction to read that file. But of course they will forget after some time.

The whole agentic coding via CLI experience could be much improved by:

- Making it easy to see what command I last issued, without having to scroll up through reams of output hunting for context - Making it easy to spin up a proper sandbox to run sessions unattended - Etc.

Maybe for code generation, what we actually need is a code generator that is itself deterministic but uses AI, instead of AI that does code generation.

I think most of them provide an option to change the default file, but it'll be really good if they all can switch to AGENT.md by default

Till then you can also use symlinks

there are issues opened in some repos for this

- Support "AGENT.md" spec + filename · Issue #4970 · google-gemini/gemini-cli

https://github.com/google-gemini/gemini-cli/issues/4970#issu...

And then they should standardize on usage rules (an idea in Elixir space: https://hexdocs.pm/usage_rules/readme.html )

https://github.com/anthropics/claude-code/issues/1091

Here for Claude

In case you haven’t seen this, you can just pipe contents into Claude. Eg

cat AGENT.md | claude

IIRC this saves some tokens.

Why would it save tokens?

probably skips the step where you say "take a look at path/to/file" and the model converts that to a tool call

maybe symlinking will work

That's a more obvious (but less fun) name than what I've been using: ROBOTS.md with symlinks.

https://ampcode.com/AGENT.md#migration

they also suggest using symlinks for now

(I work at Cursor) The CLI supports AGENT.md as well as CLAUDE.md and Cursor Rules.

When they stop getting desperate for differentiation by spamming their brand advertising in your repo against your will.

Claude Code likes to add "attribution" in commit messages, which is just pure spam.

You can turn it off: https://docs.anthropic.com/en/docs/claude-code/settings#avai... `includeCoAuthoredBy: false`

5 years from now: Subscribe to the Ultra plan for the ability to prevent the LLM from putting ads for Coca-Cola into your code comments!

It’s not spam, it lets people know it was written by an LLM and maybe you should look closer at it.

I've experimented a little with LLM agents (only Claude Code). I definitely don't want the agent to write the commit messages (they should be written by a human as they're for human consumption) so I manually added the co-author trailer. It's morally correct to provide attribution.

Code is also for human consumption.

SICP contains the famous quote: “Programs must be written for people to read, and only incidentally for machines to execute.”

I find LLM written commits are more often than not better than humans one

Never. It's a marketing strategy. Some percentage of users will check these files into their repos, and some percentage of repo browsers will think "what is this X.md?" Given how much money people are spending on these things the value of having a unique filename must be enormous.

It’s a marketing strategy that works here and now, but “never” is a very long time. What could be seen as pioneers claiming names today could be also seen as retrogressive stubbornness tomorrow and lose its marketing value.

There's a reason we still call the file robots.txt by that name, and not web-scraping.txt or search-engines.txt.

Yea, the reason is RFC9309.

That's actually a good point, but we have RFCs superceding RFCs all the time. My favorite RFC, 8601, superseded I think half a dozen other RFCs.

Brand asset

I just wish the AGENTS.md standard wasn't a single file. I have a lot of smaller context documents that aren't applicable to every task, so I like to throw them into a folder (.ai/ or .agents/) and then selectively cat them together or tell the agent to read them.

You could have a python script that generates the MD file on the fly, based on how you want to prompt the model. I think it's kind of funny, how deep we are getting with tools instructing tools instructing tools.

Elixir has this idea with usage rules: https://hexdocs.pm/usage_rules/readme.html

You can put them in subdirectories like CODEOWNERS files. https://ampcode.com/AGENT.md#multiple-agent-files

>When multiple files exist, tools SHOULD merge the configurations with more specific files taking precedence over general ones.

How is the tool supposed to merge multiple md files?

The same way it synthesizes anything else. We're talking about LLMs here; this is their bread and butter.

Most AI solutions make tracing the finally assembled prompt a bit difficult.

However, if you look through the source code or network requests, you’ll see that merging just means naive “concatenation”.

Agree. It's all English. That's the whole point of these tools.

Why are we purposely creating CLI dialects?

FWIW at least with Claude and Jules on a project I have a decent setup where I put all of the real content in an agents.md and then use “@agents.md” in CLAUDE.md. If all of the tools supported these kinds of context references in markdown it wouldn’t be that hard to have a single source of truth for memory files.

Same here each specific instruction file (vs code, cursor, etc.) just says read the AGENTS.md for instructions

Yeah I suspect some of these providers will become Microsoft in the '90s type bully holdouts on implementing the emerging conventions. But ultimately with CLI interface you have workarounds to all the major providers read in your system guidelines. But in an IDE - e.g. like MS had with VisualStudio - you more lock-in potential for your config files.

Yesterday, I was writing about a way I found to pass the same guideline documents into Claude, Gemini, and Aider CLI-coders: https://github.com/sutt/agro/blob/master/docs/case-studies/a...

Isn't think just a symlink?

I'm at a point where I symlink differnet sets of docs to try to focus context so much I feel like maybe I need a git submodule with different branches of context I want. I left managing people to now manage AI

I haven't tried it yet myself, but I noticed their product page (https://cursor.com/cli) says:

> Set your own rules: Customize Cursor's work with rules, AGENTS.md, and MCP.

There's no mention of it in the docs, though. It's also interesting it's AGENTS.md on that page instead of AGENT.md, I wonder if that's a typo.

The deeper problem are the custom commands, hooks and subagents. The time has come that you need to make a strategic choice. Once you have heavily invested into CC, it is not easy to turn to an alternative.

Side remark: CC is very expensive when using API billing (compared to e.g. GPT-5). Once a company adopts CC and all developers start to adapt to it at full scale, the bill will go out of the roof.

Symlinks $AGENT.md to AGENT.md in your repo.

For example: i'm using Claude Code mostly + Gemini CLI. Gemini CLI is not such powerful as CC, also it won't work with some mcp's. So i have different *.md files.

Different file names is easy analytics (ex: 'how many OSS projects use gemini.md and claude.md' is a mere search query).

The font on that RFC is aggressively squashed and aliased, why?

Thank you so much for this!

Symlink?

Reply on news.ycombinator.com