Author: abavyka
A hallucination is when the model confidently spits out something that doesn’t exist. It’s not lying on purpose: it generates the most plausible text, and if it doesn’t know something, it plausibly guesses.
What it looks like in code
• A non-existent API: await fs.promises.exists(path) — looks logical, but there’s no such method in Node
• An outdated library version: the model writes getServerSideProps in the Next.js app router or the zod v3 API, while you’re on v4. Its knowledge is older than your package.json
• A package that doesn’t exist: npm install with a name the model made up. It’s also a security hole: attackers register these “made-up” names with malware (slopsquatting)
• Made-up CLI flags and config options
• “Tests passed” — and nobody ever ran them
Why it happens
• The model answers off the top of its head instead of reading the code or the docs
• The context is clogged or already squashed by compact, and the details it needed got lost
• The model’s knowledge has a date, and your dependencies have their own versions
How to cut it down
• Ask it to read, not guess: “before making changes, read src/auth and package.json, check which zod version we have”
• Let it say “I don’t know”: “if you’re not sure about an API — check the types in node_modules or the docs, don’t make stuff up”
• Docs in the code. The agent can open the .d.ts in node_modules and see the real signatures
• For up-to-date docs — WebFetch on the official site or an MCP like Context7
The best way to fight hallucinations is not to take it at its word, but to give the agent a way to check itself. Then it catches its own made-up stuff by itself, before it ever gets to you.
• npx tsc —noEmit — most made-up methods and fields blow up right away on typecheck. That’s exactly why TS and agents get along so well
• Tests (vitest/jest). First write a test (hi there, TDD) that fails on the bug, and only then fix
• Linter (eslint)
• Actually running it: curl the endpoint for the backend, the browser (hello there, Claude in Chrome)
• Put it in CLAUDE.md: “after changes always run npm run typecheck && npm test”
• Don’t accept “everything works” without the command output. Want to be sure — ask it to show the result
• Eyeball new dependencies in package.json before npm install
What’s next: you can run typecheck and tests automatically instead of asking.
Read more:
• Hallucinations
• Verifying agent output
• Claude Code best practices (the verification section): https://code.claude.com/docs/en/best-practices
• Anthropic on context engineering: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents