AI is great at reading, so give it things to read. Claude will try to throw big markdown docs in your repo, but you don't have to do that. Make it keep docs by the code.

I include a line in AGENTS.md that says "We *always* add docstrings to methods, classes, structs, and namespaces - there should be 100% coverage of docstrings."

It will make better choices about what functions to make or remove if you force it to justify why the function exists.

And when you have to go back and understand, it becomes easier.

It’s clear at this point that agents don’t actually follow agents.md

They try to but they don’t. As an example, we use perforce in games. I regularly have to stop an agent and remind it to use p4 edit rather than blasting through the read only flag, despite the first paragraph of Claude.md being “this is a project using perforce. Batch call p4 edit on all files before modifying, do not manually remove the read only flag”