[nzoschke]

The best thing you can do is help build and maintain high quality docs.

Great docs help you, your agents, your team and your customers.

If you’re confused and the agent can’t figure it out reliably how can anyone?

Easier said than done of course. And harder now than ever if the products are rapidly changing from agentic coding too.

One of my only universal AGENTS.md rules is:

> Write the pull request title and description as customer facing release notes.

[chatmasta]

I’ve been thinking about this a lot. It’s obviously the ideal state of things. The challenge is that we’ve got existing docs frameworks and teams and inertia and unreleased features… and I don’t have time to wait for that when I’m trying to get something done today. Not to mention the trade off of writing in public vs. private.

One quick win I’ve thought could bridge this is updating our docs site to respond to `Accept: text/markdown` requests with the markdown version of the docs.

[nsvd2]

I've come to the point where, if the agent makes a wrong assumption about the code base with fresh context, I consider that the code is not obvious enough about it's intent.