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

201–210 of 398 posts

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

#201

Post by monkeydust »

goosejuice wrote: post #62
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 req…

Also see this happening, what does that mean for business specifications? Does it become close to code syntax itself?

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

#202

Post by nivertech »

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…

This looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself.

AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support both versions, i.e. see Arc42.

Though, it's much easier and less error-prone to @-mention a separate .md file, rather than a section in a large markdown file.

Smaller files also might be better when you want to focus a coding agent's attention on a specifric thing.

They're also easier to review diffs / PRs.

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

#204

Post by thrown-0825 »

anonyfox wrote: post #199

Currently I am building a new JS web toolkit on the side with AI assistance for faster progress, and I came to have some prompts folder in the project root that I just drop into the agents (like cursor CMD+I) and point it to a direction (file/folder). https://github.com/Anonyfox/raven-js/tree/main/prompts I think we should not split README and AGENT into different documents - the way its heading is that the coding ag…

Agreed, between this and MCP we are quickly approaching the point where you basically need to document your codebase twice.

Its completely pointless

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

#205

Post by theshrike79 »

bryanrasmussen wrote: post #172
awbraunstein wrote: post #168

Earlier quoted context omitted.

You can have multiple AGENTS.md files in your codebase and tooling will look at both the one in the current directory as well as in the root of the codebase. This way you can sort of do what you're suggesting but simultaneously keep the information closer to the code that it is describing.

so you would have an Agents.md in your testing folder and it would describe how to run the tests or generate new tests for the project - am I understanding the usage correctly?

Pretty much yes

Most systems have a global config, project config and personal config.

But I do like the directory style to keep context low. Cursor did it best with actual glob filters in the front matter that tell the LLM "only read this if the file you're processing ends with *.php"

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

#207

Post by theshrike79 »

createaccount99 wrote: post #147
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…

Anti-feature if you ask me. An agent should be able to pick the stuff it needs from the AGENTS.md, and not blindly use everything.

Context is not infinite. Saving context for what matters is key in working with LLMs.

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

#208

Post by fallpeak »

ekusiadadus wrote: post #161
Osyris wrote: post #117

Earlier quoted context omitted.

> but as OpenAI pointed out last week What are you referring to here?

https://cdn.openai.com/API/docs/gpt-5-for-coding-cheatsheet.... From OpeAI's last week document for coding with gpt5. > #3. Use XML-like syntax to help structure instructions

I don't know if GPT-5 is an exception and is overcooked on XML specifically, but in general Markdown and XML seem to work about equally well for LLM inputs, the important part is just that they like hierarchical structured formats. The example on that page could probably be replaced with:

  ## Code Editing Rules

  ### Guiding Principles

  - Every component should be modular and reusable
  ...

  ### Frontend Stack Defaults

  - Styling: TailwindCSS
Without any meaningful change in effectiveness.

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

#209

Post by mrklol »

andyferris wrote: post #76
diggan wrote: post #6

Earlier quoted context omitted.

At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.

For ages, many projects have README.md for marketing/landing page (i.e. users) and CONTRIBUTING.md for developers. Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.

I feel like as a human you should still do it like you said. But in the current state it’s advantageous to give the LLM proper instructions which are distinct to human instructions. LLMs aren’t drop in replacements for developers … yet (or never).

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

#210

Post by tappio »

I've came across llms.txt files in few services. I don't know how the agents.md compares to the llms.txt files, but I guess they could pretty much have the same content. See more also here https://llmstxt.org/

Anyhow, I have made few interesting observations, that might be true for the agents.md also:

Agents have trouble with these large documents, and they seem to miss many relevant nuances. However, its rather easy to point them to the right direction when all relevant information is in one file.

Another thing is that I personally prefer this style of documentation. I can just ctrl+f and find relevant information, rather than using some built in search and trying to read through documents. I feel that the UX of one large .txt file is better than the documentation scattered between multiple pages using some pretty documentation engine.

Post reply on HN