At the bottom of every long-lived codebase is a function nobody has called in three years. Above it is a commented-out block from a refactor that was abandoned halfway through. Above that is a file with no incoming imports, which somebody added during a sprint that got cancelled. None of this code is doing work for the product. All of it is doing work against the team: slowing down reading, confusing search results, surviving every refactor that swept past without touching it.
Dead code accumulates because deletion has a visible cost and keeping has an invisible one. The visible cost is the worry that something somewhere depends on the code in a way nobody noticed. The invisible cost is everything the code makes harder until somebody finally summons the courage to delete it.
Agents amplify both sides of this.
What dead code looks like
The category is broader than "code that runs but does nothing." The forms vary.
Unused functions, exported from a module and not called anywhere. The export keeps them alive against the static analyzer; nobody calls the function, but nobody can prove that without an audit.
Commented-out blocks. The previous version of a function, left in place "in case we need to revert." Six months later, the block uses an API that no longer exists, and reverting it would not even work.
Files nobody imports. A whole module, possibly with tests, possibly with documentation, that has no incoming dependencies. The file is in the repo because nobody noticed when its last caller was deleted.
if (false) { ... } and its variants. The code was disabled by a developer in a hurry. The plan was to come back to it. The plan was not written down.
Test fixtures and mocks for code that no longer exists. The tests pass because they exercise nothing, but they still take time to run and space to read.
Each of these is dead code in the relevant sense: it survives in the codebase without contributing to the running system. All of it costs.
What it costs
The first cost is reading time. Every developer who works in a file with dead code skims over it to find the live code. Multiply that across every visit, every code review, every onboarding tour. The dead code makes the live code less readable by surrounding it with noise.
The second cost is search confusion. A grep for a function name returns matches in the dead code. The developer follows the wrong trail. The agent does the same thing, with less skepticism.
The third cost is refactoring friction. When you change an API, you also have to update the dead callers, or you have to detect that they are dead and skip them. Both add work to every cross-cutting change.
The fourth cost is agent context. Agents load nearby code into their working memory. Dead code in nearby files consumes that budget and contributes nothing. Worse, the agent reads the dead code as if it were live; it pattern-matches against it; it produces new code in the style of code that nobody is using anymore. The dead code teaches the agent the wrong lessons.
The fifth cost is moral. A codebase littered with dead code signals to every contributor that the team does not care enough to clean up. The signal lowers the bar for everyone, including the agent.
Why deletion feels risky
The asymmetry between deleting and keeping has a specific shape. If you delete code that turns out to have been needed, the failure is visible - something breaks, somebody notices, the team blames the deletion. If you keep code that is not needed, the failure is invisible - the codebase just gets a little harder to work in, gradually, with no single cause to point at.
Humans are bad at evaluating invisible costs against visible risks. So we keep the code. The risk is bounded. The cost is unbounded. Eventually the cost wins, but it wins on a timescale where nobody notices the connection between the deletion-aversion and the bad working environment.
The fix is to make the cost visible. Detection tools that report dead code create a number that nobody likes seeing high. A weekly cleanup that removes ten dead exports creates a number that everyone enjoys seeing fall. The visible cost makes the invisible cost visible too.
How to find it
Every language has tooling for this, and most of it goes unused.
For JavaScript and TypeScript: ts-prune, knip, ESLint's no-unused-vars extended to detect unused exports. For Python: vulture. For Go: the unused-checks built into staticcheck. For most languages: coverage reports, which show which lines were never exercised during a test run.
The tools are not perfect. Reflection, dependency injection, dynamic imports, and serialization can all make code look unused when it is not. The right posture is to treat the tool's output as a candidate list, not a directive. Review each finding. Most of them will be real.
The harder cases (dead branches behind feature flags, dead handlers behind disabled routes) are not findable by static analysis. Those require the team to maintain inventories: every flag has a state, every route has a registration. When the state is "off forever" or the route is "disabled," the code behind it is dead.
First steps
If your codebase has accumulated dead code and you want to start removing it:
Run the right detector for your language. Save the output. Do not try to act on all of it at once; the diff will be huge and the review will not happen.
Pick the largest single item in the output: the function or module that is most clearly dead. Delete it. Push the change. See what fails. Usually nothing fails. The deletion takes ten minutes and the codebase is measurably smaller.
Add the detector to CI as a non-blocking report. The team sees the dead-code number every week. The number creates social pressure to make it smaller.
Add a lint rule for unused imports, set to error. Every new file is now prevented from accumulating dead imports. Existing files are grandfathered.
Schedule a quarterly hour where the team deletes dead code as a group. The hour pays for itself many times over in the months after.
Add one rule to your AGENTS.md: "When you change a file, remove any dead imports, unused exports, or commented-out code blocks you encounter in the same change. Do not preserve old code 'in case we need it'; git history has it. Do not leave commented-out code in committed work."
The fear that drives keeping is real but bounded. The cost of keeping is unbounded. Most teams err on the side of keeping for years, until they reach a state where the codebase is mostly dead code and the live code is buried in it. The fix is small, repeated cleanup, with mechanical detection and a team norm that says: when in doubt, delete.
The repository is not a museum. The git history is the museum. The repository is the working code.
Top comments (0)