This is exactly what I do. It works super well. Who would have thought that documenting your code helps both other developers and AI agent? I've been sarcastic.

I would argue that many engineering “best practices” have become much more important much earlier in projects. Personally, I can deal with a lot of jank and lack of documentation in a early stage codebase, but LLMs get lost so quickly, or they just multiply the jank faster than anyone ever could have in the past, making it much, much worse for both LLMs and humans.

Documentation, variable naming, automated tests, specs, type checks, linting. Anything the agent can bang its proverbial head against in a loop for a while without involving you every step of the way.

This might be one of the best things about the current AI boom. The agents give quick, frequent, cheap feedback on how effective the comments, code structure, and documentation are to helping a "new" junior engineer get started.

I like to think I'm above average in terms of having design docs alongside my code, having meaningful comments, etc. But playing with agents recently has pointed out several ways I could be doing better.

If I see an LLM having trouble with a library, I can feed its transcript into another agent and ask for actionable feedback on how to make the library easier to use. Which of course gets fed into a third agent to implement. It works really well for me. Nothing more satisfying than a satisfied customer.

I've done something similar. I ask agents to use CLIs, then I give them an "exit survey" on their experience along with feedback on improvements. Feels pretty meta.