[zimbatm]

This should have been CONTRIBUTING.md all along.

The content of the AGENTS.md is the same as what humans are looking for when contributing to a project.

[oehpr]

The most effective argument I have for getting other developers to comment their code is "The agent will read it and it will give better suggestions".

Truly perverse, but it works.

I agree with you... but the reality is that there's a wide contingent of people that are not capable of understanding "people don't know the same things as me". So they need some other reason.

[organsnyder]

It's made my project documentation so much better. If I write out really good acceptance criteria, 9 times out of 10 I can point Claude at the ticket and get a workable (if unpolished) solution with little to no supervision.

[esafak]

They understand it just fine; they are acting selfishly, because it does not benefit them. Helping the coding agent does.

[dingnuts]

several ironies here:

1) an AI agent is less likely to notice than even a junior is when the docs are out of date from the code

2) AI boosters are always talking about using language models to understand code, but apparently they need the code explained inline? are we AGI yet?

3) I frequently hear how great AI is at writing comments! But it needs comments to better understand the code? So I guess to enable agentic coding you also have to review all the agents' comments in addition to the code in order to prevent drift

HOW IS ANY OF THIS SAVING ME TIME

[sbochins]

I don’t think they serve the same purpose. Most of the instructions I have for an agent won’t apply to a human. It’s mostly around the the requirements to bootstrap the project vs what I’d ask for a human to accept their pull request.

[heyzk]

I think semantically this is true, but the way humans and agents handle context, at the moment, is different enough to warrant a separate structure.

[j2kun]

Yeah I can't find any example in an AGENTS.md that isn't useful information for a human. "Cluttering" a README.md is a silly justification.

[hombre_fatal]

Nah, My standard for what I write for humans is 100x than the slop I spew for robots.

Also, you don’t even address their point.

[layer8]

Arguably, contributors are human agents. ;)

[alostpuppy]

Dude, this is such a good point.