Claude Hallucinated a Package That Doesn't Exist

Perfect syntax, imaginary dependency

The failure mode has a shape every agent user recognizes: Claude writes clean code around a hallucination — proper imports, tidy comments, a function that reads beautifully and references a package that was never published. It compiles in the agent's head.

It explodes in yours. Mastercard's integration team hit the same wall from the other side: assistants inventing API endpoints and auth parameters that looked plausible and failed silently, until they pinned every call to the OpenAPI spec.

Why it happens is structural, not personal. The model predicts likely text; import lines for plausible-sounding packages are likely text.

Then the anti-hallucination problem compounds: challenged, the agent flip-flops and confidently states the opposite — also without checking. And the bill for all this lands in the 67% of developers now spending longer debugging AI-generated code than before they adopted the tools.

The 3-rule file that stops it

Drop this into AGENTS.md (or CLAUDE.md / .cursorrules — same text, every tool reads one of them):

1. Read before claiming. Never describe a file, API, or deploy state from memory. Open it, then speak. "I don't know, let me check" beats a confident lie every time.
2. Cite the source. Every factual claim names where it came from: file + line, or tool output. No source = no claim.
3. Never install without asking. New dependencies need explicit human approval with the reason stated. The default answer to "should I add a package?" is "use what's here."

Then enforce it mechanically, because instructions erode under context pressure. This is the BoringPush shape — a Next.js stack where the verification gate runs before anything ships:

# every agent turn ends here, no exceptions
node --check <changed.js>
npm run lint   # MUST exit 0 with zero warnings

That gate catches phantom imports at the cheapest possible moment: the install fails, the import errors, the turn stops — on the laptop, never in production. Pair it with the smallest possible dependency surface (BoringPush holds under 10 packages: no SDK for uploads, no queue for cron, no ORM for queries), and there is simply less namespace for the agent to hallucinate in.

Ship from anywhere on this Next.js stack and the rule travels with you: phone session or desktop, same file, same gate.

The 30-second pre-install ritual (and the cleanup if you're late)

Before any install, make the agent earn it:

1. Registry check. npm view <exact-name> version time — exists, maintained, no typosquat neighbors with 12 downloads? The anti-hallucination rules call this "tool-first": the registry is always right, memory is often wrong.
2. Repo search. Does the codebase already solve it? Uploads, cron, auth, email — BoringPush answers all four with built-ins, which is exactly how phantom installs die: the agent finds the native path before inventing a package.
3. Lockfile honesty. After install, git diff package-lock.json should show one package, not five. Agents love to drag in transitive "helpers" — each one is future attack surface.

Already infected? Audit this way: npm ls --depth=0 lists direct deps — for each, answer "which feature breaks if I remove this?" in one sentence.

No sentence, no package. Then grep imports for anything not in that list; every hit is either dead code to delete or a phantom to replace.

Teams that run this quarterly report the same surprise: a third of their dependencies were agent-added conveniences nobody chose. Fewer packages, fewer hallucinations, faster cold starts — the same discipline pays three times.

The one-line version for your dotfiles

If your agent config has room for exactly one sentence, make it this: read the file, cite the source, ask before installing. Everything in this post is that sentence unfolded — the registry check is "cite the source" applied to npm, the gate is "read before claiming" enforced by tooling, the sub-ten-package surface is what makes asking rare.

Paste the sentence into AGENTS.md today; add the machinery around it as the team grows.

FAQ

How do I know if my agent hallucinated a package?

npm view <name> — thirty seconds. Better: make the agent run it before every install and paste the registry output. Verification beats vibes.

Is this just a Claude problem?

No. Cursor, Copilot, Codex all invent dependencies — it is a property of predictive models, not a vendor bug.

The 3-rule file is tool-agnostic for exactly that reason.

Won't "never install" slow real work down?

It slows the wrong work down. Legitimate installs get approved in one sentence; the rule only blocks the 2am npm install typo-package that leaks secrets or breaks the container build.

What about hallucinated APIs, not packages?

Same disease, same cure: pin to the spec. Mastercard's fix — "use only endpoints in the OpenAPI document, say so when one is missing" — ports directly to your codebase as "use only routes in app/api/, say so when one is missing."

Does BoringPush really keep dependencies minimal?

Yes — native fetch over SDKs, raw SQL over ORMs, OS cron over queues. Fewer packages means fewer names to invent and a smaller blast radius when one slips through.