How to Find and Resolve TODO Comments Across a Codebase

Why TODO Comments Become a Problem

A single TODO comment is harmless. It is a developer's note to themselves or their team that something needs attention later. The problem is that "later" rarely comes. A codebase that has been actively developed for two or three years can easily accumulate hundreds of TODO comments scattered across every directory, many written by people who have since left the team.

These stale TODOs represent real risk. Some mark known bugs that were too minor to fix at the time but have since become relevant. Others mark security shortcuts that were acceptable during prototyping but not in production. Some mark performance optimizations that would prevent scaling issues the team has not yet encountered. Without a systematic way to find and triage them, they sit invisible in the code until the problem they describe actually causes an incident.

Scanning for TODOs Automatically

The simplest starting point is a grep-style scan that finds every comment containing TODO, FIXME, HACK, XXX, or similar markers across the project. Most codebases use a handful of conventional markers, and a single regex pattern catches them all.

An AI-powered scan goes further. Instead of just finding the marker, it reads the surrounding code to understand what the TODO is about. It can categorize each one: is this a bug workaround, a missing feature, a performance concern, a security shortcut, or a code cleanup task? This categorization makes triage much faster because you can address all security-related TODOs first without reading through hundreds of unrelated items.

What to Do With Ancient TODOs

TODOs that have been in the codebase for over a year deserve special attention. If a TODO has survived that long without causing a visible problem, it often means one of two things: either the code path it marks is rarely executed and the issue is genuinely low priority, or the issue has been silently causing problems that nobody has traced back to this location. An AI agent can check git blame to determine when the TODO was written, look at the surrounding code's change history, and make an informed recommendation about whether the item is still relevant.

Categorizing by Priority and Effort

Not all TODOs are equal. A TODO marking a missing input validation on a public API endpoint is far more urgent than a TODO suggesting a cosmetic refactor in a utility function. Categorize each TODO along two axes:

• Priority: What is the impact if this issue is never addressed? Security shortcuts and bug workarounds are high priority. Style improvements and optional optimizations are low priority.
• Effort: How much work is it to resolve? Some TODOs can be fixed in five minutes. Others require significant refactoring or coordination with other teams.

High-priority, low-effort items should be resolved immediately. High-priority, high-effort items should be promoted into your issue tracker. Low-priority items of any effort level can stay as TODOs for now, but should be reviewed periodically so they do not accumulate indefinitely.

Resolving TODOs With AI Assistance

Many TODO comments describe work that an AI coding agent can handle directly. Adding input validation, writing a missing test, refactoring a function for clarity, or updating an API call to use the current interface are all tasks where the intent is clear from the TODO comment and the surrounding code provides enough context for an AI to execute the fix.

The workflow is: the AI scans for TODOs, reads each one in context, determines whether it can resolve the issue, and either makes the fix or creates a detailed report explaining what needs human attention and why. This turns a backlog of invisible technical debt into either resolved issues or tracked work items.

Preventing TODO Accumulation

Scanning and resolving existing TODOs is a one-time cleanup. Preventing new ones from accumulating requires a process change. The most effective approach is to set a quality gate that flags any new TODO comment added in a pull request. The developer either resolves it before merging, converts it to a tracked issue, or provides a justification for why it needs to stay.

This does not mean banning TODO comments entirely. They serve a legitimate purpose during active development. The rule is simply that TODOs should not be merged into the main branch without being tracked somewhere. A TODO with a linked issue is manageable. A TODO with no tracking is how technical debt accumulates silently.