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

[zhann@computerclub.social]

@cassidy you're assuming people write does instead of prompting them. 👀

[isagalaev@mastodon.social]

@cassidy I was thinking about it the other day, and I think I have a theory why techies write these docs all of a sudden: because they work.

Maintaining docs for people (in corporate environment, at least) is often an exercise in futility, because nobody reads them. Nobody expects docs to be up to date or usefully written, so they usually just ask the maintainer directly instead.

With AGENTS.md you actually see how it affects things and you see that your effort is not in vain.

[isagalaev@mastodon.social]

@cassidy (mind you, I hate this entire AI shit with a burning heart, but I recognize what's happening.)

[tsturm@famichiki.jp]

@isagalaev @cassidy That is certainly part of the problem.

I try to provide a maximum of documentation in various formats, and I can't count the meetings where I show up and none of the involved people across the company bothered to read any of it.

[uep@timeloop.cafe]

@cassidy I think this gets at a valid point about documentation too, in that it's much easier to write docs for a specific, narrow, focused purpose and audience when it's clear to you what they need to read.

Perhaps people writing for an llm audience also don't have the expectation that their audience may give criticism back. I imagine that helps too.

[sop@unstable.systems]

@cassidy the contradiction is easily explained: the culture didn't actually change. most always those files are written by bots, for bots. Claude literally prompts you "hey you should start by running /init" the first use you use it. LLMs will take a simple "use a regex to customize a behavior in these cases" prompt and spit out a bonus 200 lines of slop.md regurgitating its context into your repository. If you don't catch that during code review, that becomes more write-only garbage no human will read, much less update, but still counts as technical debt when LLMs just choose to git grep random strings to see what they find

[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.