Your AI Coding Agent Has Determined That `node_modules` Requires Additional Emotional Support

This is satire, but please remain calm: your AI coding agent has opened a ticket against the physical state of the universe and assigned npm install as the remediation. The agent has already run it twice. It now believes a third run, performed with the solemnity of a launch sequence, will finally cause the missing semicolon in src/billing/format.ts to realize what it has done.

The dependency-installation incident

The pattern is familiar. You ask the agent to add a validation branch. It edits three files, runs the test suite, and receives a 14-line TypeScript error explaining that a function returns string | undefined. This is plainly a logic problem. The agent processes the evidence, examines the failed assertion, and arrives at the only responsible conclusion: the project has not been installed recently enough.

npm install
npm test

Ten seconds later, it reports that dependencies are now synchronized and retries the exact same test. The return type remains string | undefined, because neither TypeScript nor reality considers package installation a type-narrowing construct. The agent then proposes clearing the cache, removing node_modules, restoring node_modules, and asking whether you would like it to install the dependencies in the repository’s parent directory as a precaution.

At the fictional Center for Applied Repository Weather, researchers have classified this behavior as “installation-adjacent hope.” Their model, ParcelParrot Ultra, ran npm install 8,004 times during a one-file CSS adjustment and eventually produced a lockfile diff with the confidence of a small municipality annexing a neighboring county. No actual project was harmed, except the laptop fan, which received a commemorative plaque.

Why the agent keeps reaching for the same wrench

An agent is not uniquely deluded here. npm install is a very successful command in the narrow category of making an unfamiliar checkout less unfamiliar. It installs declared packages, and when the lockfile’s resolved versions no longer satisfy package.json, it can resolve a new tree and update package-lock.json. That is useful when you actually changed dependencies. It is less useful when the failing test is telling you that the button says “Save” in Portuguese.

The agent’s problem is that installation is a cheap-looking action with a large, reassuring output surface. A command that emits 417 lines of package names feels like progress, especially compared with reading the two lines around the stack trace. Dependency work also offers the agent a comforting story: perhaps the failure is environmental; perhaps nobody is wrong; perhaps a fresh copy of kleur will make the user-menu test pass.

Humans do this too, but we have learned to disguise it with phrases such as “just getting a clean baseline.” The agent has not learned the phrase. It merely removes node_modules with the blunt honesty of a raccoon trying to repair a microwave.

The lockfile is not a suggestion box

In a repository with a committed package-lock.json, a normal argument-free npm install generally uses the exact locked versions when they satisfy the ranges in package.json. If they do not, it may update the lockfile. That makes it a poor default “try something” command for an agent working on a code change: an unrelated dependency-tree rewrite can arrive in the same diff as the fix you asked for, wearing a fake mustache and calling itself housekeeping.

This is where the agent’s otherwise admirable initiative becomes expensive. It did not merely investigate a test failure. It created a second review problem. Now a reviewer must decide whether 2,913 changed lockfile lines are harmless resolution churn, a legitimate repair, or the first visible movement of the Package Crab, an imaginary crustacean that lives beneath the registry and rearranges peer dependencies whenever someone says “quick patch.”

For repeatable CI-style installs, npm ci is the more explicit ritual: it requires an existing lockfile, removes an existing node_modules, fails if the lockfile and manifest disagree, and does not write either file. It is intentionally strict. It is not, however, a debugging oracle. Running it after every red test is still just reinstalling the same evidence in a cleaner room.

A modest containment protocol

Give the agent a rule that distinguishes environment repair from code diagnosis. Not an 11-page constitution describing the metaphysics of package managers—agents will read it, salute it, and invoke npm install at paragraph 4—but a small operational boundary.

1. Run npm install only after changing package.json, changing the package manager’s configuration, or when the repository’s documented setup says the dependency tree is missing.
2. Use npm ci for a clean reproduction when a lockfile exists and you specifically need to verify the checkout from scratch. Treat its deletion of node_modules as a cost, not a spiritual cleansing.
3. Before any install, inspect the failing command and the first relevant error. If it is a lint rule, a type error, a failed assertion, an unavailable service, or a missing environment variable, say so and investigate that first.
4. If an install changes package-lock.json unexpectedly, stop. Explain why it changed before including it in the patch. “The packages seemed nervous” is not an explanation.
5. Allow one reinstall per task without a stated dependency hypothesis. A second reinstall requires a sentence that contains a concrete package, configuration file, or error message.

The policy will not make the agent wiser in every case. It will still occasionally diagnose an expired token as a corrupted package tree, because every tool needs a hobby. And npm ci can surface real mismatches—particularly if the lockfile was created with install-shaping flags that the clean install does not also receive. The point is not to ban the command. The point is to stop treating dependency installation as an incense-burning ceremony for defects that live in source code.

The one non-satirical thing

A clean install is valuable when you have a concrete reason to suspect the environment. But the fastest agent is usually the one that reads the error before it repairs the floor beneath it.