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).
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".
skybrian · 31m ago
Except not hidden. Why do people want to hide important files and directories? Particularly documentation? Tradition, I guess, but it's an antipattern that makes everything more opaque.
Maybe robot_docs?
p1necone · 51m ago
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.
numpy-thagoras · 28m ago
Would you be open to sharing this here?
asabla · 2h ago
Been using a similar setup, with so far pretty decent results. With the addition of having a short explanation for each file within index.md
I've been experimenting with having a rules.md file within each directory where I want a certain behavior. Example, let us say I have a directory with different kind of services like realtime-service.ts and queue-service.ts, I then have a rules.md file on the same level as they are.
This lets me scaffold things pretty fast when prompting by just referencing that file. The name is probably not the best tho.
jitix · 1h ago
I like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?
CharlesW · 38m ago
I'd be interested in smarter ways of doing this, but currently I just use my CLAUDE.local.md to serve as the index.md in my example. It includes the 'specialist' .md files with their relative paths and descriptions, and tells Claude Code to use these when planning.
I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`:
## Remember Shortcuts
Remember the following shortcuts, which the user may invoke at any time.
### XNEW
When I type "xnew", this means:
```Understand all BEST PRACTICES listed in CLAUDE.md.
Your code SHOULD ALWAYS follow these best practices.
REVIEW relevant documentation in .agents/ before starting new work.
Your code SHOULD use existing patterns and architectural decisions
documented there rather than creating new approaches.```
tortilla · 48m ago
I'm building a little tool like this for myself. It's almost ready to be open-sourced. Just need to clean up some code and write better documentation.
riffic · 1h ago
.well-known/
echelon · 1h ago
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.
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 and comprehend our writing, so let's architect for it at that level.
tptacek · 3h ago
It's not just understanding the codebase, it's also stylistic things, like "use this assert library to write tests", or "never write comments", or "use structured logging". It's just as useful --- more so even --- on fresh projects without much code.
time0ut · 9m ago
Honestly, everything I have written in markdown files as AI context fodder is stuff that I write down for human contributors anyway. Or at least stuff I want to always write down, but maybe only halfway do. The difference now is it is actually being read, seemingly understood, and often followed!
naniwaduni · 3h ago
... most of which would also be valuable information to communicate when onboarding new devs.
jaggederest · 2h ago
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.
andyferris · 1h ago
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.
jaggederest · 1h ago
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
ameliaquining · 2h ago
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.
naniwaduni · 2h ago
Reality is just that people neglected onboarding docs until LLM-based coding agents put them in a position to directly benefit from having more knowledge of the codebase explicitly written down.
No comments yet
Mtinie · 1h ago
Common sense takes time to sink in.
goosejuice · 2h ago
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.
iknowstuff · 12m ago
Those particular signs are just stupid. The street should be redesigned with traffic calming, narrowing and chicanes so that speeding is not possible.
Slapping on a sign is ineffective
username223 · 1h ago
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.
4b11b4 · 1h ago
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.
joegibbs · 2h ago
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.
mvkel · 1h ago
This is mostly true if the existing codebase is largely self documented, which is rare
rr808 · 2h ago
One of the most common usages I see from colleagues is to get agents to write the comments so you can go full circle. :)
TZubiri · 3h ago
This applies to mcp too
vFunct · 3h ago
> 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.
Mtinie · 1h ago
> 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
blinkymach12 · 2h ago
I don't think the bar here is a human level coder, I think the bar is an LLM which reads and follows the README.md.
If we're otherwise assuming it reads and follows an AGENTS.md file, then following the README.md should be within reach.
I think our task is to ensure that our README.md is suitable for any developer to onboard into the codebase. We can then measure our LLMs (and perhaps our own documentation) by if that guidance is followed.
CuriouslyC · 2h ago
Have you taken a Waymo?
rorytbyrne · 2h ago
Waymo uses a bespoke 3D data representation of the SF roads, does it not? The self-driving car equivalent of an AGENTS.md file.
vFunct · 2h ago
The limited self-driving cars, with a remote human operator? no, I never have.
bix6 · 1h ago
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.
spawarotti · 3h ago
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.
nicklo · 3h ago
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.
blinkymach12 · 2h ago
I like this insight. We kind of always knew that we wanted good docs, but they're demotivating to maintain if people aren't reading them. LLMs by their nature won't be onboarded to the codebase with meetings and conversations, so if we want them to have a proper onboarding then we're forced to be less lazy with our docs, and we get the validation of knowing they're being used.
alphazard · 3h ago
Isn't the promise of AI that we don't have to adhere to precise formats? We can just write it down in whatever format makes the most sense to us, and any impedance mismatch is on the machine to figure out?
sqs · 3h ago
Just the filename is standardized. The contents aren't, which is exactly right. From the site:
> Are there required fields?
> No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
4b11b4 · 1h ago
No, structure and format matters, even if it may not be precise code syntax
eats_indigo · 3h ago
In what way is this a format or standard? It's just markdown in a namespce
tptacek · 3h ago
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.
esafak · 3h ago
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.
TZubiri · 3h ago
Easy story points
ethan_smith · 3h ago
Standards derive their value precisely from being simple and widely adopted - think of .gitignore, CONTRIBUTING.md, or LICENSE files that work because everyone agrees on their location and purpose.
chrismorgan · 1h ago
.gitignore is not a standard: it’s a format used by one tool. A few other tools piggy-back on it (e.g. ripgrep ignores paths matching in .gitignore, .hgignore, &c. by default), not infrequently to confusion.
CONTRIBUTING.md is not a standard: it’s a convention pushed by one platform, used by some projects (but many more will not write down such information, or put it in a README file, or put it in some other documentation).
LICENSE is definitely not a standard: it’s one of a wide variety of names people use to hold licensing information, which some tools will be able to detect. I just looked through my /usr/share/licenses, of 1135 files, only 300 are named LICENSE—it’s the most popular single name, sure, with COPYING next at 182, but it’s still definitely a minority, though in certain ecosystems it may be more popular. Any license-detection tooling will be scanning for a lot more file names. “LICENSE” is a very weak convention, compared with the others.
arrowsmith · 3h ago
All the different coding agents put their "rules" in different places: .cursor, CLAUDE.md etc..
It makes no sense and it really needs standardisation. I hope this catches on.
cma · 1h ago
As a workaround you can add a wrapper launcher script that symlinks them and then removes the symlink after you exit
ivanjermakov · 3h ago
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
* 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.
lmeyerov · 56m ago
We find it useful:
* Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a < 500loc ai/readme.md with must haves, links to others, and meta how-to-use
* 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
stingraycharles · 3h ago
It is. README is for humans, AGENTS / etc is for LLMs.
Document how to use and install your tool in the readme.
Document how to compile, test, architecture decisions, coding standards, repository structure etc in the agents doc.
crazylogger · 49m ago
We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?
darepublic · 3h ago
Compile, test, architecture would be very welcome in the readme too Id wager
sponnath · 2h ago
Why would these things not be relevant for humans?
throwup238 · 2h ago
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.
goosejuice · 2h ago
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.
stingraycharles · 7m ago
Because managing an AI’s context is important and you don’t want to put stuff in there that’s not relevant.
Just because they can read it and understand it doesn’t mean there are no better alternatives.
trailrunner46 · 1h ago
One reason to consider is around context usage with LLMs. Less is generally better and README.md files are often too much text some of which I don’t want in every context window.
I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.
rogeliodh · 51m ago
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.
diggan · 3h ago
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.
andyferris · 1h ago
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.
blinkymach12 · 3h ago
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.
esafak · 3h ago
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".
viraptor · 2h ago
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.
ecb_penguin · 1h ago
That seems exactly like something you would want to tell another developer
sothatsit · 3h ago
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.
bongodongobob · 3h ago
Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
ameliaquining · 2h ago
README often contains only basic context for the project and instructions for basic tasks like running it and building it from source. If additional information for developers, like coding conventions, is short enough compared to the rest of the README then it sometimes gets added there too, but if there's a lot of it then it's frequently kept elsewhere to prevent README from getting overwhelming for end users and random people just checking out the project.
blinkymach12 · 2h ago
I don't think anything requires a README.md to be monolithic. They often provide the introductory material that you mention here, then link out to other appropriate files for contribution guidelines, etc.
CuriouslyC · 2h ago
To share the most effective workflows so people don't have to muddle around figuring out what to do?
petesergeant · 1h ago
Perhaps. I let Claude put whatever it wants in its Claude file and check it’s not batshit from time to time, where I’m very protective of the high-quality README I write for humans. The Claude file has stuff that would be obvious to a human and weird to jam into the README (we use .spec.ts not .test.ts) but that Claude needs in order to get things right.
ekusiadadus · 36m ago
How are you actually running this in practice with Claude Code?
Do you just tell Claude to always read and follow AGENTS.md, or do you also use an MCP server to strictly control which commands (like pnpm test or pnpm lint) it can run?
I’d love to hear what workflows or best practices have worked well for you in day-to-day use.
j45 · 32m ago
I have Claude Code maintain the files and reference links between them.
faangguyindia · 2h ago
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
<Role> <instruction>
Agent only reads the file if its role is defined there.
Inside project directory, we've a dot<coding agent name> folder where coding agents state is stored.
Our process kicks off with an `/init` command, which triggers a deep analysis of an entire repository. Instead of just indexing the raw code, the agent generates a high-level summary of its architecture and logic. These summaries appear in the editor as toggleable "ghost comments." They're a metadata layer, not part of the source code, so they are never committed in actual code. A sophisticated mapping system precisely links each summary annotation to the relevant lines of code.
This architecture is the solution to a problem we faced early on: running Retrieval-Augmented Generation (RAG) directly on source code never gave us the results we needed.
Our current system uses a hybrid search model. We use the AST for fast, literal lexical searches, while RAG is reserved for performing semantic searches on our high-level summaries. This makes all the difference. If you ask, "How does authentication work in this app?", a purely lexical search might only find functions containing the word `login` and functions/classes appearing in its call hierarchy. Our semantic search, however, queries the narrative-like summaries. It understands the entire authentication flow like it's reading a story, piecing together the plot points from different files to give you a complete picture.
It works like magic.
jzig · 2h ago
Tell me more!
faangguyindia · 1h ago
The agent I’m developing is designed to improve or expand upon "old codebases." While many agents can generate code from scratch, the real challenge lies in enhancing legacy code without breaking anything.
This is the problem I’m tackling, and so far, the approach has been effective. It's simple enough for anyone to use: the agent makes a commit, and you can either undo, squash, or amend it through the Git UI.
The issue is that developers often skip reviewing the code properly. To counter that, I’m considering shifting to a hunk-by-hunk review process, where each change is reviewed individually. Once the review is complete, the agent would commit the code.
The concept is simple, but the fun lies in the implementation details—like integrating existing CLI tools without giving the agent full shell access, unlike other agents.
What excites me most is the idea of letting 2–3 agents compete, collaborate, and interpret outputs to solve problems and "fight" to find the best solution.
That’s where the real fun is.
Think of it as surgeons scalpel approach rather than "steam roller" approach most agents take.
aeon_ai · 1h ago
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.
No comments yet
stingraycharles · 3h ago
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.
Jules uses AGENTS.md, which indicates that Google is on board with it as the standard. If Gemini Code Assist continues to be a thing (I'm not sure whether Jules is intended to succeed it) then presumably it will support AGENTS.md as well. In the meantime you can configure Gemini Code Assist to use an arbitrary filename.
I don't see a reference to a specific filename in Aider's documentation, can you link to it?
Anthropic appears to be the major holdout here.
4b11b4 · 1h ago
While I understand why...
ruler seems like something we should not need
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.
rblatz · 55m ago
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.
albert_e · 1h ago
README.md should have been called HUMANS.md in retrospect
ekusiadadus · 44m ago
Markdown is certainly easy for humans to write, but as OpenAI pointed out last week, wouldn’t an XML-based format be easier for LLMs to parse and understand?
Osyris · 39m ago
> but as OpenAI pointed out last week
What are you referring to here?
_mu · 3h ago
Make sure to check out https://agent-rules.org/ as well for more background on this initiative. More and more tools are adopting the standard.
Amp used to have an "RFC 9999" article on their website for this as well but the link now appears to be broken.
You can symlink your Cursor / Windsurf / whatever rules to AGENTS.md for backwards compatibility.
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.
sqs · 3h ago
Thank you for pointing that out. Just pushed a fix, will be live in ~5-10min.
_mu · 2h ago
Works now, thank you! :)
tomComb · 1h ago
Ok, I looked at your agent-rules and it sounds good except for a couple things ...
"Guidance for Use"
Your preference for bullet lists over headers is odd. This comes down to what works best with the models - they are interpreting it. This is a moving target. If you believe that your suggestion works best you should provide some sort of evidence. The default would be to not even get into that sort of thing.
Non-Hierarchical AGENTS.md
Claude-code, Gemini, and GHCP all support hierarchical context files. Your proposal and this new one from OpenAI and friends do not, and I think that is a shame.
_mu · 1h ago
I did not write agent-rules, I'm just linking to it.
tomComb · 3h ago
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.
neuronexmachina · 3h ago
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.
tomComb · 2h ago
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.
andyferris · 1h ago
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?
prmph · 2h ago
The agents instructions file needs to be hierarchical; It's a pain managing multiple agents.md files with a lot of duplication between them for different projects, even in a mono-repo. we probably need a tool for this.
In any case, I increasingly question the use of an agents file. What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and again?
Another thought: are folks committing their AGENTS.md? If so, do you feel comfortable with the world knowing that a project was built with the help of AI? If not, how do you durably persist the file?
tomComb · 2h ago
Agree on the need for hierarchical agents.md. I thought that was kind of standard and I am surprised that this proposal doesn’t support that.
petesergeant · 1h ago
> do you feel comfortable with the world knowing that a project was built with the help of AI?
I would be deal-breakingly concerned if I thought someone was actively trying to hide the fact from me.
alfg · 1h ago
I'm sure there's plenty of overlap with just using a CONTRIBUTING.md or even the README.md development setup. Especially since LLMs should understand guidance in human instructions.
ec109685 · 1h ago
Do all ai agents only include a single AGENTS.md, closest in the hierarchy? Where do people put common instructions or do they just copy and paste?
nunez · 46m ago
Did they just reinvent the Makefile?
koakuma-chan · 44m ago
Make is a command runner, no? It's completely different.
meowface · 2h ago
Unfortunate that two of the most-used tools (Claude Code, Gemini CLI) don't support it.
neutronicus · 1h ago
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?
_mu · 3h ago
I think this is a good thing - I would like to see the same pattern standardized for the memory system of all the different agents.
indigodaddy · 1h ago
opencode made one of these for me when I did an /init in my existing project
spullara · 2h ago
just use a good agent like augmentcode that can look at relevant context across your repository and then you can name it whatever you want.
lerp-io · 2h ago
cant you simply prompt it to read the code and create whatever md you need it to lol what is the point of this
legostormtroopr · 2h ago
So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better?
Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".
ecb_penguin · 1h ago
> So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better?
Umm, no. Where did you get that idea?
The purpose of the agent.md file is to give it instructions. Nothing about no-code AI said there would be no instructions...
TZubiri · 3h ago
Protocols for llms are funny because they are designed to accept any text as input and they don't really implement the protocol anyways, so it's just a consumer side restriction of the input space.
That’s insane. 3000 words of prose boilerplate about the language and framework. Sounds like you need, at the very least, some sort of import directive. I have no idea if “Read and follow the instructions in path/to/phoenixframework/AGENTS.md.” would work.
And then the eclectic mixture of instructions with a variety of ways of trying to bully an intransigent LLM into ignoring its Phoenix-deficient training… ugh.
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).
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".
Maybe robot_docs?
I've been experimenting with having a rules.md file within each directory where I want a certain behavior. Example, let us say I have a directory with different kind of services like realtime-service.ts and queue-service.ts, I then have a rules.md file on the same level as they are.
This lets me scaffold things pretty fast when prompting by just referencing that file. The name is probably not the best tho.
I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`:
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_Base_Directory
https://dot-config.github.io
The LLM's whole shtick is that it can read and comprehend our writing, so let's architect for it at that level.
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.
No comments yet
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.
Slapping on a sign is ineffective
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.
“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
If we're otherwise assuming it reads and follows an AGENTS.md file, then following the README.md should be within reach.
I think our task is to ensure that our README.md is suitable for any developer to onboard into the codebase. We can then measure our LLMs (and perhaps our own documentation) by if that guidance is followed.
I find them more enjoyable than Uber. They’ve already surpassed Lyft in SF ridership and soon they will take the crown from Uber.
This situation reminds me a bit of ergonomic handles design. Designed for a few people, preferred by everyone.
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.
> Are there required fields?
> No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
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.
edit: They're on it. Not everything has to be complex; sometimes somebody just has to do it.
CONTRIBUTING.md is not a standard: it’s a convention pushed by one platform, used by some projects (but many more will not write down such information, or put it in a README file, or put it in some other documentation).
LICENSE is definitely not a standard: it’s one of a wide variety of names people use to hold licensing information, which some tools will be able to detect. I just looked through my /usr/share/licenses, of 1135 files, only 300 are named LICENSE—it’s the most popular single name, sure, with COPYING next at 182, but it’s still definitely a minority, though in certain ecosystems it may be more popular. Any license-detection tooling will be scanning for a lot more file names. “LICENSE” is a very weak convention, compared with the others.
It makes no sense and it really needs standardisation. I hope this catches on.
(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.
* Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a < 500loc ai/readme.md with must haves, links to others, and meta how-to-use
* 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
Document how to use and install your tool in the readme.
Document how to compile, test, architecture decisions, coding standards, repository structure etc in the agents doc.
Just because they can read it and understand it doesn’t mean there are no better alternatives.
I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.
Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.
They are separate for a good reason. My CLAUDE.md and README.md look very different.
<Role> <instruction>
Agent only reads the file if its role is defined there.
Inside project directory, we've a dot<coding agent name> folder where coding agents state is stored.
Our process kicks off with an `/init` command, which triggers a deep analysis of an entire repository. Instead of just indexing the raw code, the agent generates a high-level summary of its architecture and logic. These summaries appear in the editor as toggleable "ghost comments." They're a metadata layer, not part of the source code, so they are never committed in actual code. A sophisticated mapping system precisely links each summary annotation to the relevant lines of code.
This architecture is the solution to a problem we faced early on: running Retrieval-Augmented Generation (RAG) directly on source code never gave us the results we needed.
Our current system uses a hybrid search model. We use the AST for fast, literal lexical searches, while RAG is reserved for performing semantic searches on our high-level summaries. This makes all the difference. If you ask, "How does authentication work in this app?", a purely lexical search might only find functions containing the word `login` and functions/classes appearing in its call hierarchy. Our semantic search, however, queries the narrative-like summaries. It understands the entire authentication flow like it's reading a story, piecing together the plot points from different files to give you a complete picture.
It works like magic.
This is the problem I’m tackling, and so far, the approach has been effective. It's simple enough for anyone to use: the agent makes a commit, and you can either undo, squash, or amend it through the Git UI.
The issue is that developers often skip reviewing the code properly. To counter that, I’m considering shifting to a hunk-by-hunk review process, where each change is reviewed individually. Once the review is complete, the agent would commit the code.
The concept is simple, but the fun lies in the implementation details—like integrating existing CLI tools without giving the agent full shell access, unlike other agents.
What excites me most is the idea of letting 2–3 agents compete, collaborate, and interpret outputs to solve problems and "fight" to find the best solution.
That’s where the real fun is.
Think of it as surgeons scalpel approach rather than "steam roller" approach most agents take.
But this is wildly insufficient as a standard, and wholly lacks innovation on the dimension of 'context management' as a discipline.
No comments yet
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
I don't see a reference to a specific filename in Aider's documentation, can you link to it?
Anthropic appears to be the major holdout here.
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.
What are you referring to here?
Amp used to have an "RFC 9999" article on their website for this as well but the link now appears to be broken.
You can symlink your Cursor / Windsurf / whatever rules to AGENTS.md for backwards compatibility.
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.
"Guidance for Use"
Your preference for bullet lists over headers is odd. This comes down to what works best with the models - they are interpreting it. This is a moving target. If you believe that your suggestion works best you should provide some sort of evidence. The default would be to not even get into that sort of thing.
Non-Hierarchical AGENTS.md
Claude-code, Gemini, and GHCP all support hierarchical context files. Your proposal and this new one from OpenAI and friends do not, and I think that is a shame.
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.
> 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.
> 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?
In any case, I increasingly question the use of an agents file. What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and again?
Another thought: are folks committing their AGENTS.md? If so, do you feel comfortable with the world knowing that a project was built with the help of AI? If not, how do you durably persist the file?
I would be deal-breakingly concerned if I thought someone was actively trying to hide the fact from me.
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?
Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".
Umm, no. Where did you get that idea?
The purpose of the agent.md file is to give it instructions. Nothing about no-code AI said there would be no instructions...
That’s insane. 3000 words of prose boilerplate about the language and framework. Sounds like you need, at the very least, some sort of import directive. I have no idea if “Read and follow the instructions in path/to/phoenixframework/AGENTS.md.” would work.
And then the eclectic mixture of instructions with a variety of ways of trying to bully an intransigent LLM into ignoring its Phoenix-deficient training… ugh.