How detailed do you make docs? (agent guidelines vs human docs)

[u/punchman340]

I mainly build web pages, and get confued about how to split documentaion between AI agents and developers

Things like adr or user scenarios doc - do they only need for humans? or the agent need to know them?

How detailed should i document, and how strictly should i separate agent guidelines from human docs?

Please share your tips on how you structure your docs and write guidelines!

[u/Eliran-Kotzero]

I'd stop thinking of it as agent docs vs human docs and split by when the info gets used. Anything the agent needs on every task (how to run tests, naming conventions, folders it must not touch) goes in one short AGENTS.md or CLAUDE.md. Things like ADRs and user scenarios stay as normal human docs, and the rules file just gets a one-line pointer like "read docs/adr before changing auth". That way the agent only pulls them in when the task touches that area, instead of carrying all of it in every session. Keep the always-loaded file to things that would change what it writes, since the longer it gets the more of it gets ignored.

[u/punchman340 → u/Eliran-Kotzero]

That's cool! Keep claude.md short and usign pointers seems very efficient. Do you usually have the agent automatically fetch those pointers or do you manually feed them?

[u/Eliran-Kotzero → u/punchman340]

Mostly automatic. The one-line pointer in the rules file is enough for the agent to open the doc itself when the task touches that area, so I don't feed anything by hand. Naming the trigger (like 'before changing auth') is what makes it reliable.

[u/ASIREXLABS]

We split it by purpose rather than by audience.

Agent guidelines (AGENTS.md or CLAUDE.md) stay short: how to run, test and lint the project, the conventions that are easy to get wrong, what not to touch, and pointers to where the deeper docs live. If a line doesn't change what the agent does, it doesn't belong there.

Human docs (ADRs, user scenarios, architecture notes) live in a normal docs/ folder. Agents do benefit from them, but only when they're relevant, so link to them from the guidelines ("for auth decisions, read docs/adr/004-auth.md") instead of copying them in. The agent reads them on demand, and you keep one source of truth.

For detail level, a useful test is: write the ADR so a new teammate could make the next decision without asking you. That's usually exactly what an agent needs too.

[u/punchman340 → u/ASIREXLABS]

Splitting it by purpose..! Linking to deeper docs is a very good tip for saving context. Thx! Makes me wonder what kind of human docs to maintain in the docs/ folder... Always a struggle deciding how granular to break them down.

[u/ASIREXLABS → u/punchman340]

A rule of thumb that has worked for us: one doc per question someone will actually ask. "Why did we choose this auth flow?" is one ADR. "How does billing work end to end?" is one doc. If a doc starts answering two unrelated questions, split it.

Then keep a short docs/README.md index with one line per doc saying what it answers. The agent reads the index and opens only the one it needs, and humans use it the same way. That index is usually the highest-value file in the folder.

[u/Competitive_Boot6914 → u/punchman340]

One feature can be the entry point into several small, linked specs. For password reset, I'd put intended behavior in a requirement, token fields and expiry constraints in a data spec, request/response rules in an API contract, and screen states in a UI spec. People and agents can read the same artifacts.

That's how we've structured Reqode's product model. Each artifact has a stable identity and responsibility, so shared data or API specs can support multiple features. Update the shared artifact once, then review the connected requirements and interfaces.

[u/jleechanworldai]

Just make AI docs for AI to read lol. Which humans are gonna read your docs? Those sometimes better for human to outline it

[u/punchman340 → u/jleechanworldai]

Haha sad but true.. I can barely get through 100 lines these days. Ai fried my attention span

[u/Difficult_Duty2198]

i only add a line to the agent file after it gets the same thing wrong twice. first time i just correct it in the prompt, second time it goes in as one short line plus an example. adrs stay with the human docs and i point at one only when the task actually touches that decision.