I've been having a good time with Spec Driven Development, and it directly addresses the issue of needing the understand.

The whole idea is that you specify exactly what you want in some SPEC.md file. You can of course nest them, have multiple, etc, but the core idea is that the SPEC file is the source of truth, and all the code should be able to be generated by a competent agent into the working product you want. The SPEC file(s) should contain all the details and behavior you care about, and anything you don't care about is up to the agent to decide. If you don't like what the agent picked, _put it in the spec file_.

Critically, _you_ must write the SPEC file. You ensure understanding by doing so. You can of course ideate with the agent, but it's your ideas, in your words, specified by you. This also makes it a great source of documentation when you come back later and have to remember wtf is going on in this codebase.

> when you come back later and have to remember wtf is going on."

When that happens, do you read just the spec, or do you also need to read the code? Is there a difference between "I can remember what I intended" and "I can predict what the system will do in a situation the spec didn't cover"?

Interestingly, you said the spec author must be you. What happens when you join a codebase where someone else wrote the SPEC, or where an agent wrote the code and nobody spec'd it? Is the spec still sufficient, or does the "you must write it" part mean the understanding doesn't transfer?

same, I've been liking https://openspec.dev/ and find the more time I put iterating/scrutinizing the spec artifacts (proposal, requirements, design, tasks) before I let the agent implement the better understanding I have and the better results I get. Also like that it is agent agnostic so I can take it with me as I try different agents/models.