I am not anti-AI - perhaps obviously. But this is wildly insufficient as a standard, and wholly lacks innovation on the dimension of 'context management' as a discipline.
[deleted]
AGENTS.md – Open format for guiding coding agents
101–110 of 398 posts
Re: AGENTS.md – Open format for guiding coding agents
#102Earlier quoted context omitted.
Have you taken a Waymo?
The limited self-driving cars, with a remote human operator? no, I never have.
This is a rather dismissive response considering the progress they’ve made over the past few years. The other commenter is correct that they use highly detailed maps but you are incorrect as they do not have a remote human operator.
I find them more enjoyable than Uber. They’ve already surpassed Lyft in SF ridership and soon they will take the crown from Uber.
Re: AGENTS.md – Open format for guiding coding agents
#103README.md should have been called HUMANS.md in retrospect
Re: AGENTS.md – Open format for guiding coding agents
#104We'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…
Very strong "reverse centaur" vibes here, in the sense of humans becoming servants to machines, instead of vice versa. Not that I think making things more machine-readable is a waste of time, but you have to keep in mind the amount of human time sacrificed.
Re: AGENTS.md – Open format for guiding coding agents
#105I'm still not convinced that separating README.md and AGENTS.md is a good idea.
I've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa...
(Quoting from that post)
Arguments in favor of keeping them separated:
* Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting.
* Conciseness vs. completeness. In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality. In internal eng docs, we ideally aim for 100% completeness. I.e. every important design decision, API reference, workflow, etc. is documented somewhere.
* Differing knowledge needs. The information that LLMs need help with is not the same as the information that human engineers need help with. For example, Gemini 2.5 Pro has pretty good built-in awareness of Pigweed’s C++ Style Guide. I tested that assertion by invoking the Gemini API and instructing it Recite the Pigweed C++ Guide in its entirety. It did not recite in full, but it gave a detailed summary of all the points. So the Gemini 2.5 Pro API was either trained on the style guide, or it’s able to retrieve the style guide when needed. Therefore, it’s not necessary to include the full style guide as AGENTS.md context. (Credit to Keir Mierle for this idea.)
Arguments against:
* Duplication. Conceptually, agent docs are a subset of internal eng docs. The underlying goal is the same. You’re documenting workflows and knowledge that’s important to the team. But now you need to maintain that same information in two different doc sets.
Re: AGENTS.md – Open format for guiding coding agents
#106Earlier quoted context omitted.
.well-known/
This. Projects need to stop inventing their own root level files and directories. Stop polluting the root dir. I'm not a fan of the name "well-known", but at least it's a convention [1]. I think it'd be great if we took something like XDG [2] and made it common for repositories, build scripts, package managers, tooling configs, etc. [1] https://www.rfc-editor.org/rfc/rfc8615 [2] https://wiki.archlinux.org/title/XDG_B…
.config is a good name, and has a small following
Re: AGENTS.md – Open format for guiding coding agents
#107I'm still not convinced that separating README.md and AGENTS.md is a good idea.
We find it useful:
* Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a * Similar to IaaC, useful to separate out as not really ready the same way we read it, and many markdowns are really scripts written in natural language, eg, plan.md.template
Re: AGENTS.md – Open format for guiding coding agents
#108I 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…
We are going the opposite way, putting instructions in md files and putting instructions in the Claude.md file when it should read those instructions.
Re: AGENTS.md – Open format for guiding coding agents
#109I'm still not convinced that separating README.md and AGENTS.md is a good idea.
Some time ago a lot of projects had a README and a BUILD/README.build/DEVELOPMENT file... I think AGENTS.md is more akin to this last file.
Re: AGENTS.md – Open format for guiding coding agents
#110This 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've been trying to keep my baked in llm instructions to a terse ~100 line file, mostly headered sections with 5 or so bullet points each. Covering basic expectations for architecture, test mocking, approach to large changes etc. I can see why for some projects that wouldn't be enough but I feel like it covers everything for most of mine.