I think of this every time I see AGENTS.md or CLAUDE.md.

[djumaka@phpc.social]

@cassidy my stupid take on this: nobody has ever wanted or liked to write useful docs/specs. Now with AI there is a sudden excitement boost that "a little docs" will make the ai do your job... Soon enough we will start hating this as well and we will start making AGENTS.md useless as README.md. With the exception of the rare people that did it properly even before AI, truly understanding the purpose.

Lazy-driven-development.

[gooba42@mastodon.social]

@cassidy We were all told how awful and onerous documentation was supposed to be.

In fit of creative productivity, I might code out ahead of my docs but I never felt like it was as big a chore as it was made out to be.

Re-documenting a giant codebase is a different situation and one I haven't had to do yet. I think *inheriting* undocumented legacy code was the real big bad but we let it be our excuse for new undocumented code.

[mjd@mathstodon.xyz]

@cassidy Because the AI won't learn from being repeatedly told, the way a human would. So if you don't want to repeatedly tell it every little thing, you have to write it down in a file.

[log@mastodon.sdf.org]

@cassidy Staring at my "improve documentation" backlog ticket. Looking at the "add agentic instruction markdown" ticket. Trying to figure out whether this is philosophically happy or sad.

[bexelbie@toot.io]

@cassidy I’ve found that LLM focused docs have a terseness that is great to read and skim and would’ve been rejected when I was a tech writer. I think we have room to normalize a shared system for “man and machine” but that means being willing to let go of some converntions that some people may still find useful and others will wish to pearl-clutch over.

Also, if your AGENTS.md contains all that you should probably generalize it to be about the “relationship protocol” and put the codebase specific’s in a project context document. That way it’s even better for humans and still works for the machine.