News for hackers. Stuff that matters.
Re:The AGENTS.md Standard: A simple, open format for guiding... by ivanjermakov on Tuesday August 19, 2025 @08:31PM (#44957510)
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
Re:The AGENTS.md Standard: A simple, open format for guiding... by kaycebasques on Tuesday August 19, 2025 @10:55PM (#44958254)
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:The AGENTS.md Standard: A simple, open format for guiding... by CGamesPlay on Wednesday August 20, 2025 @12:24AM (#44958612)
> 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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by skhameneh on Wednesday August 20, 2025 @01:06AM (#44958779)
Negative assertions can lead to unwanted weights in the context.

I've found positive assertions to be more predictable.

Re:The AGENTS.md Standard: A simple, open format for guiding... by taikahessu on Wednesday August 20, 2025 @03:59AM (#44959741)
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

Re:The AGENTS.md Standard: A simple, open format for guiding... by superfish on Wednesday August 20, 2025 @02:51AM (#44959335)
Do you mind sharing a specific concrete example? I'm curious.
Re:The AGENTS.md Standard: A simple, open format for guiding... by skhameneh on Wednesday August 20, 2025 @10:00AM (#44962047)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by ghuntley on Wednesday August 20, 2025 @10:57AM (#44962555)
Using all caps will actually cause GPT-5 to not function effectively. Have a look at the GPT-5 tuning documentation for coding.
Re:The AGENTS.md Standard: A simple, open format for guiding... by lmeyerov on Tuesday August 19, 2025 @11:04PM (#44958286)
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

Re:The AGENTS.md Standard: A simple, open format for guiding... by diggan on Tuesday August 19, 2025 @08:35PM (#44957536)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by andyferris on Tuesday August 19, 2025 @10:09PM (#44958065)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by mrklol on Wednesday August 20, 2025 @04:36AM (#44959939)
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:The AGENTS.md Standard: A simple, open format for guiding... by stingraycharles on Tuesday August 19, 2025 @08:36PM (#44957541)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by furyofantares on Wednesday August 20, 2025 @12:08AM (#44958552)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by darepublic on Tuesday August 19, 2025 @08:46PM (#44957609)
Compile, test, architecture would be very welcome in the readme too Id wager
Re:The AGENTS.md Standard: A simple, open format for guiding... by silversmith on Wednesday August 20, 2025 @01:28AM (#44958896)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by darepublic on Wednesday August 20, 2025 @12:10PM (#44963202)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by crazylogger on Tuesday August 19, 2025 @11:11PM (#44958319)
We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?
Re:The AGENTS.md Standard: A simple, open format for guiding... by sponnath on Tuesday August 19, 2025 @09:17PM (#44957803)
Why would these things not be relevant for humans?
Re:The AGENTS.md Standard: A simple, open format for guiding... by throwup238 on Tuesday August 19, 2025 @09:22PM (#44957832)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by goosejuice on Tuesday August 19, 2025 @09:43PM (#44957936)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by stingraycharles on Tuesday August 19, 2025 @11:53PM (#44958496)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by goosejuice on Thursday August 21, 2025 @06:42PM (#44979011)
That's also not a strong argument?

Agents often have system prompts specific to their purpose. Having a single dump of agent instructions will increase noise in the context.

Re:The AGENTS.md Standard: A simple, open format for guiding... by trailrunner46 on Tuesday August 19, 2025 @10:11PM (#44958079)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by rogeliodh on Tuesday August 19, 2025 @11:09PM (#44958307)
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:The AGENTS.md Standard: A simple, open format for guiding... by blinkymach12 on Tuesday August 19, 2025 @08:38PM (#44957555)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by esafak on Tuesday August 19, 2025 @08:55PM (#44957674)
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".
Re:The AGENTS.md Standard: A simple, open format for guiding... by viraptor on Tuesday August 19, 2025 @09:46PM (#44957948)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by ecb_penguin on Tuesday August 19, 2025 @10:03PM (#44958041)
That seems exactly like something you would want to tell another developer
Re:The AGENTS.md Standard: A simple, open format for guiding... by sothatsit on Tuesday August 19, 2025 @08:57PM (#44957690)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by bongodongobob on Tuesday August 19, 2025 @09:01PM (#44957715)
Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
Re:The AGENTS.md Standard: A simple, open format for guiding... by ameliaquining on Tuesday August 19, 2025 @09:17PM (#44957805)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by blinkymach12 on Tuesday August 19, 2025 @09:31PM (#44957876)
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.
Re:The AGENTS.md Standard: A simple, open format for guiding... by CuriouslyC on Tuesday August 19, 2025 @09:05PM (#44957739)
To share the most effective workflows so people don't have to muddle around figuring out what to do?
Re:The AGENTS.md Standard: A simple, open format for guiding... by bongodongobob on Wednesday August 20, 2025 @10:10AM (#44962144)
You're going to try to tell people how to code with agents in the readme? Why?
Re:The AGENTS.md Standard: A simple, open format for guiding... by sothatsit on Wednesday August 20, 2025 @01:34AM (#44958923)
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.

Re:The AGENTS.md Standard: A simple, open format for guiding... by petesergeant on Tuesday August 19, 2025 @10:05PM (#44958051)
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.