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

81–90 of 398 posts

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

#81

Post by jitix »

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…

I like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?

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

#82

Post by andyferris »

tomComb wrote: post #69
neuronexmachina wrote: post #33

Earlier quoted context omitted.

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.

I think it's just poorly written. Further down:

> What if instructions conflict? > The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.

This seems appropriate for hierarchical AGENTS.md files? How would it even realize there was a conflict if it hadn't read both files?

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

#83

Post by 4b11b4 »

stingraycharles wrote: post #5

Yet every agent I use (Claude Code, Gemini and Aider) uses their own custom filename. It would be nice if it was standardized. Right now I’m using ruler to automate generating these files for all standards as a necessary evil, but I don’t envision this problem being solved soon. Especially because these coding agents also use different styles for consuming MCP configs. https://github.com/intellectronica/ruler

While I understand why... ruler seems like something we should not need

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

#84

Post by neutronicus »

meowface wrote: post #60

Unfortunate that two of the most-used tools (Claude Code, Gemini CLI) don't support it.

What does "support" for this format mean beyond "reading the file without explicit prompting"?

Like, as the end-user, if I copy-paste "Please see AGENTS.md in the project root for some information on the project" have I filled the gap?

Or is the LLM ingesting this file in some special way I'm losing out on?

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

#85

Post by Mtinie »

ameliaquining wrote: post #45
naniwaduni wrote: post #20

Earlier quoted context omitted.

... most of which would also be valuable information to communicate when onboarding new devs.

If there were already a universal convention on where to put that stuff, then probably the agents would have just looked there. But there's not, so it was necessary to invent one.

Common sense takes time to sink in.

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

#86

Post by 4b11b4 »

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 agree with this general sentiment, but there might be some things you want to force into the context every time via a specific agent file.

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

#88

Post by jaggederest »

andyferris wrote: post #72
jaggederest wrote: post #46

Earlier quoted context omitted.

Yeah I agree. I think the best place for all this lives in CONTRIBUTING.md which is already a standard-ish thing. I've started adding it even to my private projects that only I work on - when I have to come back in 3 or 4 months, I always appreciate it.

I agree. My current thought is that (human) contributors should be encouraged to `ln -s CONTRIBUTING.md CLAUDE.local.md` or whatever in their local checkout for their agent of choice, have that .gitignored, and all contributors (human and LLM) will read and write to the same file. The "new" thing would be putting CONTRIBUTING.md into subfolders as appropriate - which could often be quite useful for humans anyway.

Yeah I think having a docs/contributing folder or equivalent, essentially referenced/linked in the CONTRIBUTING.md makes a bunch of sense, but I'd leave that kind of thing more or less up to the project

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

#89

Post by Mtinie »

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.

> Just like we will never have fully self-driving cars, we likely won't have fully human quality coders.

“Never is a long time...and none of us lives to see its length.” Elizabeth Yates, A Place for Peter (Mountain Born, #3)

“Never is an awfully long time.” J.M. Barrie, Peter Pan

Post reply on HN