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.

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.

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

They really might not understand it fully. That's very much in line with my understanding of how autism works.

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

Well... Yah. For the record I'm saying this to trick humans into making better comments for humans. It is very difficult to convince people to do this otherwise, in my experience.

buuut...

I will also mention that these agent files are typically generated by agents. And they're pretty good at it. I've previously used agents to dissect unfamiliar code bases in unfamiliar languages and it has worked spectacularly well. Far far FAR better than I could have done on my own.

I have also been shocked at how dumb they can be. They are uselessly stupid at their worst, but brilliant at their best.

Think of it like it's saving future you time if you just let the AI centipede feed off of you. Surely it'll eventually regurgitate perfect code.

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.

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.

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.

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.

Arguably, contributors are human agents. ;)

Dude, this is such a good point.