Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

AGENTS.md – Open format for guiding coding agents

agents.md

Post reply on HN
Print view View original

31–40 of 398 posts

Re: AGENTS.md – Open format for guiding coding agents

#31

Post by TZubiri »

esafak wrote: post #25
tptacek wrote: post #4

Earlier quoted context omitted.

You could get this page down to under 100 words by simply having it say "the name of the file LLM agents will look at for instructions on the repo is AGENTS.md; that's it, that's the standard". It's a real problem! Every agent right now has their own weird filename. I love David Crawshaw's sketch.dev, but for reasons passing understanding they choose "dear_llm.md" for theirs.

I created a ticket for adding AGENTS.md support. edit: They're on it. Not everything has to be complex; sometimes somebody just has to do it.

Easy story points

Re: AGENTS.md – Open format for guiding coding agents

#32

Post by sothatsit »

blinkymach12 wrote: post #9
ivanjermakov wrote: post #2

I'm still not convinced that separating README.md and AGENTS.md is a good idea.

I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.

You're going to include specific coding style rules in your README? Or other really agent-specific things like guidance about spawning sub-agents?

They are separate for a good reason. My CLAUDE.md and README.md look very different.

Re: AGENTS.md – Open format for guiding coding agents

#33

Post by neuronexmachina »

tomComb wrote: post #28

I think we lost something pretty big in this formulation. With Claude code and others, if I put a context file (agent.MD or whatever) in a project subfolder, e.g., something explaining my database model in with the related code, it gets added to the root project context when the agent is using that subfolder. It sounds to me like this formulation doesn’t support that.

That's sort of this? I guess the exact behavior would depend on the agent.

> Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.

Re: AGENTS.md – Open format for guiding coding agents

#34

Post by nicklo »

spawarotti wrote: post #21

At this point AGENTS.md is a README.md with enough hype behind it to actually motivate people to populate it with contents. People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots. This situation reminds me a bit of ergonomic handles design. Designed for a few people, preferred by everyone.

I think it’s the reverse - people were too lazy to read the docs so nobody was motivated to write them.

With an agent I know if I write once to CLAUDE.md and it will be read by 1000’s of agents in a week.

Re: AGENTS.md – Open format for guiding coding agents

#35

Post by bongodongobob »

sothatsit wrote: post #32
blinkymach12 wrote: post #9

Earlier quoted context omitted.

I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.

You're going to include specific coding style rules in your README? Or other really agent-specific things like guidance about spawning sub-agents? They are separate for a good reason. My CLAUDE.md and README.md look very different.

Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.

Re: AGENTS.md – Open format for guiding coding agents

#36

Post by CharlesW »

This should've been an .agents¹ with an index.md.

For tiny, throwaway projects, a monolithic .md file is fine. A folder allows more complex projects to use "just enough hierarchy" to provide structure, with index.md as the entry point. Along with top-level universal guidance, it can include an organization guide (easily maintained with the help of LLMs).

  index.md
  ├── auth.md
  ├── performance.md
  ├── code_quality
  ├── data_layer
  ├── testing
  └── etc
In my experience, this works loads better than the "one giant file" method. It lets LLMs/agents add relevant context without wasting tokens on unrelated context, reduces noise/improves response accuracy, and is easier to maintain for both humans and LLMs alike.

¹ Ideally with a better name than ".agents", like ".codebots" or ".context".

Re: AGENTS.md – Open format for guiding coding agents

#37

Post by CuriouslyC »

vFunct wrote: post #24
blinkymach12 wrote: post #13

We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will. I think we should focus on our own project documentation being comprehensive (e.g. the contents of this AGENTS.md are appropriate to live somewhere in our documentation), but we should always write for humans. The LLM's whole shtick is that it can read an…

> We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will. This isn't guaranteed. Just like we will never have fully self-driving cars, we likely won't have fully human quality coders. Right now AI coders are going to be another tool in the tool bucket.

Have you taken a Waymo?

Re: AGENTS.md – Open format for guiding coding agents

#38

Post by CuriouslyC »

bongodongobob wrote: post #35
sothatsit wrote: post #32

Earlier quoted context omitted.

You're going to include specific coding style rules in your README? Or other really agent-specific things like guidance about spawning sub-agents? They are separate for a good reason. My CLAUDE.md and README.md look very different.

Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.

To share the most effective workflows so people don't have to muddle around figuring out what to do?

Re: AGENTS.md – Open format for guiding coding agents

#40

Post by vFunct »

CuriouslyC wrote: post #37
vFunct wrote: post #24

Earlier quoted context omitted.

> We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will. This isn't guaranteed. Just like we will never have fully self-driving cars, we likely won't have fully human quality coders. Right now AI coders are going to be another tool in the tool bucket.

Have you taken a Waymo?

The limited self-driving cars, with a remote human operator? no, I never have.
Post reply on HN