I am struggling with AI, I think we all are to some extent right now. We seem to be in a transition phase, moving more and more away from writing any code by hand. It's probably likely many of us have not written a line of code by hand in the last few months. But I am observing that code review, to a large extent, is still a human job. Maybe not when vibecoding the next prototype, but for production services with actual customers relying on it, it is still a must. And for good reason, AI likes to take the path of least resistance and add in any new feature without thinking about refactoring to better abstraction or it even misses the intent behind a change completely. That means we are at this terrible place of AI writing huge pull requests and humans having to painfully work through them. And at the same time, we still own the code changes even if we don't write them.
So how can we make AI-generated code as pleasant and efficient as possible for humans to review?
This is embarrassing #
One thing I find especially embarrassing: comments written by AI agents. You probably know exactly what I am talking about:
/// Note: These are complete API base URLs, including the mount point,
/// which is load bearing because leaving out even one part would mean the
/// endpoint is incomplete in the specific sense that it would no longer be a
/// complete API base URL
/// The order is preserved because callers may care about the order, even though
/// this field itself does not explain why they care, and because preserving an
/// order is different from not preserving an order.
/// An honest take is that endpoint availability and freshness are
/// related concepts in the broader system, though they are not represented
/// together here and this field does not define how that relationship should
/// work.
/// Note also that XYZ is a separate feature and only comes in phase 3 of the
/// implementation, which is outside the scope for now.
pub endpoints: Vec<String>,
It's overly verbose, it is extremely hard to understand or get the point and it often even references things out of your local session writing the code.
Seeing comments like this in pull requests:
- makes me think the owner never even looked at the code
- gives me nothing to understand what's going on
- adds the burden on future contributors to update/replace that
- makes me want to quit my job
This increases the already huge review burden we face right now.
And to be fair, some comments like this slipped through into my own changes as well, in the heat of the moment it's easy to miss, even if you want to review all changes yourself, it happens.
Force yourself to review #
There is an easy fix, make agent comments impossible to ignore, force yourself to review agent changes before committing them. I explored something similar before in I Have Trust Issues With My AI. Canary Comments Help., but that was not strong enough.
In my AGENTS.md I have a snippet saying:
## Mandatory Agent Comment Prefix (Pre-Commit Rule)
- In ANY programming language, ALWAYS prefix every comment you write or modify (including inline comments, block comments, and doc comments) with 'agent-comment:'
* Examples:
* // agent-comment:
* /// agent-comment: ...
* #agent-comment: ...
* /* agent-comment: ... */
* Never write or edit a comment without this prefix.
* A global git pre-commit hook rejects commits containing 'agent-comment:' so that comments are manually reviewed and re-worded before committing.
To save myself from committing something even worse, comments prefixed by agent-comment, I have a global commit hook that rejects any commit that includes agent-comment.
#!/bin/sh
if git diff --cached --no-ext-diff --no-textconv --no-color -U0 | awk '
/^diff / { in_hunk = 0 }
/^@@ / { in_hunk = 1 }
in_hunk && /^\+/ && /agent-comment/ { found = 1 }
END { exit !found }
'; then
echo 'Review and remove agent-comment markers before committing.'
exit 1
fi
This is amazing! It forces me to:
- open my editor at the place of comment
- understand what the code does, decide if that even makes sense
- re-word it, remove it, rewrite the code & make sure it is fit for human consumption
Why this works #
It forces me to be the first reviewer, yes we all want to be that anyway, but this stops these lazy moments where you want to move fast or are tired and would skip that. No way to blindly commit everything that the agent produces.
This is no guarantee that all code is reviewed, maybe the agent will start avoiding writing comments, maybe they start using --no-verify in commits to work around these constraints and its still up to me to review everything, but its an additional safeguard.
It also encourages me to dive deeper, because I'll spot some weirdness in the comments, probably meaning something is off in implementation. It also helps to spot if an agent drifts away from your instructions, e.g. if you spot comments without the prefix, probably your AGENTS.md is ignored and something is wrong.
Most importantly it respects other developers' time. They get something that makes sense and comments are written for a human to understand.
My name is still on the code I write, I don't want this to become total slop. I want to write the code efficiently and fast with AI agents, but I also want to have a codebase that is still pleasant to work in, to understand as a human. This is one step in that direction (at least until we are fully out of the loop).