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

61–70 of 398 posts

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

#61

Post by joegibbs »

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…

I think they'll always need special guidance for things like business logic. They'll never know exactly what it is that you're building and why, what the end goal of the project is without you telling them. Architectural stuff is also a matter of human preference: if you have it mapped out in your head where things should go and how they should be done, it will be better for you when reading the changes, which will be the real bottleneck.

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

#62

Post by goosejuice »

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…

I suspect machine readable practices will become standard as AI is incorporated more into society.

A good example is autonomous driving and local laws / context. "No turn on red. School days 7am-9am".

So you need: where am I, when are school days for this specific school, and what datetime it is. You could attempt to gather that through search. Though more realistically I think the municipality will make the laws require less context, or some machine readable (e.g. qrcode) transfer of information will be on the sign. If they don't there's going to be a lot of rule breaking.

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

#63

Post by _mu »

sqs wrote: post #30
_mu wrote: post #18

Earlier quoted context omitted.

Gotcha - this is what I had in my history: https://ampcode.com/AGENT.md For me, that gives a 404 with no obvious way to get to https://agents.md , I think either a hyperlink or redirect would be nice to have as well.

Thank you for pointing that out. Just pushed a fix, will be live in ~5-10min.

Works now, thank you! :)

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

#64

Post by goosejuice »

throwup238 wrote: post #53
sponnath wrote: post #47

Earlier quoted context omitted.

Why would these things not be relevant for humans?

They are relevant but dumping it all into one document in the project root isn’t as optimal for humans as it is for agents, especially since a lot of that information is irrelevant to someone landing on your repo, who probably just wants to add it to their dependency manifest or install the app followed by usage instructions geared to humans.

Agents are capable of semantic search and reading an entire directory devoted to human readable docs. So I'm not sure this is a particularly good argument. Just make it clear where to find what.

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

#66

Post by viraptor »

esafak wrote: post #29
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.

My READMEs don't have things like "don't run the whole test suite unless I instruct you to because it will take too long; run targeted tests instead".

Why not? "For most development we recommend running single/specific tests since the whole suite is slow/expensive." sounds like a great thing to put in the readme.

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

#67

Post by cortesi »

I have a tiny, relevant weekend project:

https://github.com/cortesi/agentsmd

This is a command-line tool that lets you generate your AGENTS.md and CLAUDE.md files from common sources. So, for instance, if you have Rust-specific guidance for models, you can define it once, and then automatically include it in any project that contains Rust based on the `lang()` language matcher.

This is one of those small tools I now use many times a day to maintain and update ubiquitous agents files. Maybe other folks will find it useful too.

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

#68

Post by jzig »

faangguyindia wrote: post #50

I am developing a coding agent that currently manages and indexes over 5,000 repositories. The agent's state is stored locally in a hidden `.agent` directory, which contains a configuration folder for different agent roles and their specific instructions. Then we've a "agents" folder with multiple files, each file has Agent only reads the file if its role is defined there. Inside project directory, we've a dot folder…

Tell me more!

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

#69

Post by tomComb »

neuronexmachina wrote: post #33
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.

But no, that's the opposite - here sub-context files REPLACE the ones above it rather then augmenting it - and I think that deviating in this way is kinda' dangerous in that user's might not notice this difference.

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

#70

Post by riffic »

CharlesW wrote: post #36

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 ├── da…

.well-known/
Post reply on HN