Writing Code That Still Makes Sense After the Agent Moves On

Agent-written code has a smell when you read it six weeks later. Slightly too verbose. Helper functions nobody calls twice. Comments that narrate the obvious. After eight months, I have a checklist I run before I merge anything an agent produced. It turns generated code into code I would have written myself.

The Review Checklist

Before I accept an agent's PR, every file goes through these questions:

• Is every comment earning its place, or is it narrating the code?
• Are there helpers used only once? Inline them.
• Do variable names match the domain vocabulary my team uses?
• Is the error handling appropriate to the layer, or generic try/except?
• Does the logic match how I would explain it on a whiteboard?

An Example Before and After

# agent output
def process_user_input(input_string):
    # First we strip whitespace from the input
    stripped = input_string.strip()
    # Then we check if it is empty
    if not stripped:
        return None
    # Finally return the processed value
    return stripped
 
# after review
def clean_email(raw: str) -> str | None:
    return raw.strip() or None

Same behavior, half the code, domain-specific name. The function tells me what it is for, not what it does.

Why This Matters Six Months Later

Code lives longer than the session that produced it. When I come back in March, I read the file without context. If the agent's verbosity is still there, I waste time parsing it. If I cleaned it up at merge time, I read it in seconds. The review is an investment that pays back every time I revisit the module.

The Repo-Level Signal

I grep for common agent tells across my repos every month: # First we, # This function, unused helpers, empty except blocks. They are canaries. When the count rises, it means I am merging too fast. That is the signal to slow down, not the agent's fault. The PEP 8 style guide still applies to AI output.

Agent-resistant code is code that reads like a human wrote it. That is the standard.

The Maintenance Math

A five-minute cleanup per file at merge time costs thirty minutes across a typical feature. The alternative is revisiting that file in three months and spending two hours re-understanding it. Cleanup is cheap debt paydown. Skipping it is borrowing at high interest. Over a full year, the difference between a repo that was cleaned at merge time and one that was not is enormous. I measure it in how many questions new contributors ask me. The cleaner the history, the fewer the questions.