Comment by ivanjermakov
Comment by ivanjermakov 5 days ago
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
Comment by ivanjermakov 5 days 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.
To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean there are consequences to doing suchandsuch, like being fired or causing production downtime. So the same message will be received differently by the different types of readers.
This. When doing Stable Diffusion, I have noticed this as well. Adding negatives can sometimes lead to the opposite results.
From what I can tell, if you say "no computers" for example (ie adding computer as negative), you are setting the scene for something like "where there should be computer, there is not".
I can't better describe this phenomenom, only that it can completely change the output in unexpected unwanted ways.
AB - B = AC
I can, I don't have a specific example I've used to give you in this moment. And trying to share an exact example would read like a double negative.
The general rule of thumb is only put what you want in context. If you put instructions of what not to do in context, those tokens can be misunderstood and create unintended/unwanted steering of the model.
A fair example would be testing for positive sentiment. Consider weight of tokens appended to context, phrase instructions or questions to be neutral or positive.
e.g. Some phrases and their impact:
- "Is the tone of the user message positive?" will be biased for a false positive.
- "Analyze the tone of the user message?" will be more neutral and less biased.
- "Is the tone of the message negative?" will be biased for false positives when evaluating for negative tone.
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 had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.
That seems exactly like something you would want to tell another developer
Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
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.
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.
It should not contain personal preference. It should contain project conventions.
Project guidelines, how to build your project, where to find or implement different types of features, are not personal preference. If different members of your team disagree on these things, that is a problem.
To share the most effective workflows so people don't have to muddle around figuring out what to do?
You're going to try to tell people how to code with agents in the readme? Why?
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.
Compile, test, architecture would be very welcome in the readme too Id wager
Where contributors are the audience, yes. For things like libraries, I care about those things only if I run into a bug, and have enough resources to attempt a fix.
It can help even when using the library and not contributing. It helps you to use the api better imo, because usually the abstraction is not perfect and having even a general sense of how the sausage is made will prevent you from falling victim to gotchas. But then on the downside it lowers the mystique of the library. Some coders prefer to be magicians.
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.
We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?
There's a lot of shit in my claude.md that would be condescending to a human. Some of it I don't even mean, it's just there to correct egregious patterns the model loves to do. I'm not gonna write "never write fallback code" in my readme, but it saves a lot of time to prevent claude from constantly writing code that would silently fail if it got past me because it contains a fallback path with hardcoded fake data.
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.
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
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.
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.