Tell your coding agent these tips for writing good comments

Comments should explain why not what. Code is a solution. Solutions are responses to constraints. When you only see the solution, you cannot know when the constraints have changed and the solution is now garbage. Write down the constraints.

A person reads code carefully only when they intend to change it and cannot see the edges. If they could see the edges they would already be editing. They are reading because the edges are invisible. Comments make edges visible. "What" has no edges. "Why" is all edges.

Every comment should survive this test: does it help someone delete the code? If not, it is decoration. We are not decorating.

Code shows the path taken. It cannot show paths not taken. Often the path not taken is the interesting part. Often someone will wander down that path again unless you leave a sign.

The machine does not read comments. The machine reads code and does what it says. Comments are not for the machine. They are for the human who must decide whether the code is still correct. Correct relative to what? Relative to the world. Which changes. The code cannot track the world. Comments track the world.