I've arrived at a lot of the same conclusions for how to agent-optimize a codebase and one thing I find pretty interesting is that a lot of it is just good old "software engineering best practices" made to idiot-proof your codebase. One exception is the docs.md hierarchy, but honestly, I'm sure if you had an organization that was doing a simple version of that 10 years ago they probably would have been better off too!
We actually did do a version of this on my team at Google. You could define a markdown file that would then get rendered into a static site that would live alongside the code
The Memento framing helps. 'A bug is when the code doesn't match the intent, so intent has to live somewhere' is a good way to put it. Does the per-folder docs.md ever drift out of date, and do you check it, or do agents keep it current as they change things? Stale intent notes seem like they could mislead a fresh session worse than having none.
I've arrived at a lot of the same conclusions for how to agent-optimize a codebase and one thing I find pretty interesting is that a lot of it is just good old "software engineering best practices" made to idiot-proof your codebase. One exception is the docs.md hierarchy, but honestly, I'm sure if you had an organization that was doing a simple version of that 10 years ago they probably would have been better off too!
We actually did do a version of this on my team at Google. You could define a markdown file that would then get rendered into a static site that would live alongside the code
The Memento framing helps. 'A bug is when the code doesn't match the intent, so intent has to live somewhere' is a good way to put it. Does the per-folder docs.md ever drift out of date, and do you check it, or do agents keep it current as they change things? Stale intent notes seem like they could mislead a fresh session worse than having none.