TODOs Considered Harmful

Summary

In the age of coding agents operating with decreasing human oversight, TODOs are becoming dangerous. Often written off-the-cuff or with insufficient context, they are now time bombs waiting to go off when an agent stumbles upon them and acts. More than ever, TODO comments need to be limited and clarified in order to prevent unintended problems later.

Why This Is a Problem

In the past year, developers have switched from using agents like an on-demand StackOverflow, to delegating larger tasks to them. Agents are being asked to act on their own, sometimes with the expectation to find and fix issues. TODOs are a convenient example. Often considered technical debt, they are an easily identified target for agent cleanups. After all, if a developer left a note about something that needed to be fixed later, why not have an agent do it?

Unfortunately, TODOs rarely receive the same scrutiny as executable code. They may be written quickly, and lack detail. They may be written during development and then other code changes render them irrelevant, or worse. They are certainly never tested by unit tests, mutation tests, or integration tests.

Agents have limited ability to judge the logical correctness of the TODO statement. Indeed, since the code forms part of their context, TODOs can influence the LLM input weights, so they generate output as if they were facts. In practice, this can cause an agent to turn a faulty TODO into actual code, resulting in bugs or outages.

This is not a theoretical issue. I've seen this happen in a production environment. Given the prevalence of agents and the enthusiasm for using them to amplify development productivity, I doubt this is an isolated incident.

What You Can Do

Minimize TODOs. In new code, reduce the number of TODOs. In reviews, request TODOs to be fixed, removed, or replaced with stories.
Set up scans for aging TODOs. The older the TODO, the greater the chance that other changes have made it irrelevant or inaccurate.
Fix TODOs versus leaving them. If a TODO is important enough to document, consider if it is important enough to fix right away.
Document Clearly. If absolutely necessary, make sure TODOs are documented clearly with full rationale and context.
Convert to stories. If a TODO is valid but will be deferred, perhaps create a story with acceptance criteria to replace it, so it can be tracked and prioritized.

Last modified on 12 Sep 2026 by AO