DEV Community: Alberto Arena

AI Code Hallucinations: When Your AI Writes Confident Nonsense

Alberto Arena — Sat, 18 Jul 2026 14:51:18 +0000

AI coding agents are becoming part of our daily workflow. Tools like GitHub Copilot, Cursor, and Claude Code can write functions, refactor modules, and scaffold entire features in seconds. They're genuinely useful.

But they have a problem: they hallucinate.

What is AI hallucination?

In the context of coding agents, hallucination means the AI generates code that looks correct, reads well, follows reasonable patterns, but is factually wrong. It invents APIs that don't exist, references packages that were never published, or creates logic that subtly breaks under edge cases.

The tricky part? Hallucinated code often compiles. It passes a quick glance. It has the right shape. That's what makes it dangerous.

Why it happens

Large language models don't "know" things the way we do. They predict the most likely next token based on patterns in their training data. When they encounter a gap in their knowledge, they don't stop and say "I don't know." They fill the gap with something plausible.

This means an AI coding agent will confidently:

Call a method that doesn't exist in the library version you're using
Import a package with a name that sounds right but isn't real
Generate test assertions that pass by coincidence, not by correctness
Produce code that works for the happy path but silently fails on edge cases

5 practical tips to spot hallucination

Here's what I've learned from working with AI agents on real projects.

1. Verify every import and dependency

If the AI suggests a package or module you don't recognise, check it exists before installing it. A quick search on npm, Packagist, or PyPI takes seconds. I've seen AI agents invent package names that are plausible but fictional.

This also applies to methods. If the agent calls response.getStatusText() and you're not sure that method exists, check the docs. Don't trust the autocomplete.

2. Read the code, don't just run it

It's tempting to accept generated code if it compiles and the tests pass. Resist that urge. Read through the logic line by line. Ask yourself: does this actually do what I intended?

AI-generated code can be syntactically perfect and logically wrong. A function might return the right result for your test input but fail for negative numbers, empty strings, or concurrent access.

3. Test the edges, not just the happy path

AI agents tend to generate code that works for the obvious case. Write tests for boundary conditions, null inputs, large datasets, and error scenarios. This is where hallucinated logic breaks down.

If the AI also wrote your tests, be extra sceptical. It may have written tests that confirm its own assumptions rather than truly validating behaviour.

4. Cross-reference with official documentation

When an AI agent generates code using a framework or library, open the official docs and verify the API calls. Check parameter order, return types, and version compatibility.

I've caught hallucinations where the AI mixed up APIs from different library versions, or combined method signatures from two different frameworks into something that looked right but wasn't.

5. Watch for confident but vague explanations

When you ask an AI agent why it wrote something a certain way, pay attention to the explanation. Hallucinating models tend to give answers that sound authoritative but lack specifics. If the explanation is vague or circular ("this is the standard approach" without citing where), dig deeper.

A reliable answer references specific documentation, versions, or known patterns. A hallucinated answer just sounds good.

Trust but verify

AI coding agents are a genuine productivity multiplier. I use them daily and I've built projects entirely with their help. But they work best when you treat their output as a first draft, not a final answer.

The developer's job hasn't changed: understand the problem, validate the solution, and take responsibility for what ships. The AI writes the code faster. You make sure it's correct.

Stay sceptical. Stay curious. And always read the diff.

Heads up: GitHub user @doraemonxxx is squatting on 359+ repositories including Laravel packages. If you see their fork in search results, use the original author's version instead.

Alberto Arena — Tue, 14 Jul 2026 04:04:09 +0000

Curious to know how big everyone's CLAUDE.md has gotten. Mine hit 300 lines before I figured out why Claude kept getting worse, not better.

Alberto Arena — Wed, 08 Jul 2026 12:19:05 +0000

Alberto Arena

Jun 29

CLAUDE.md Is RAM, Not Disk: A Memory Model for Claude Code Projects

#ai #claude #laravel #php

4 min read

CLAUDE.md Is RAM, Not Disk: A Memory Model for Claude Code Projects

Alberto Arena — Mon, 29 Jun 2026 07:00:47 +0000

Most Claude Code projects I see have one giant CLAUDE.md that keeps growing until it is three hundred lines long, and somewhere around line two hundred the assistant starts getting worse instead of better. That is not bad luck. That file is loaded into context at the start of the session and stays resident there, so every line you add is a line Claude carries in front of it on every turn that follows — context it reads past before it gets to your actual task. The fix is not a longer file. It is treating CLAUDE.md like RAM and the rest of your docs like disk.

Here is the whole idea in one sentence: CLAUDE.md is working memory, loaded constantly and paid for constantly, so it stays small; the docs/ folder is long-term memory, loaded only when something points to it. Once that distinction clicks, every other decision about where a piece of information should live answers itself.

Why the big file hurts

Claude Code reads CLAUDE.md automatically at the start of every session and keeps it in context the whole time. That is exactly what you want for the handful of things Claude needs on every task: your stack, your commands, the rules that must always hold. It is exactly what you do not want for the things Claude needs once a week. A long domain description or a full architecture writeup sitting in CLAUDE.md does not make Claude smarter. It crowds the context with detail that is irrelevant to the task in front of it, and it costs you tokens on every turn whether you use it or not.

The test I use is simple. Does Claude need this every time, or only sometimes? Every time goes in CLAUDE.md. Sometimes goes in docs/, with a one-line pointer from CLAUDE.md so Claude knows where to look when it actually needs it.

What belongs in RAM

CLAUDE.md should be short enough that you can read it in under a minute. Mine for a Laravel project holds five things:

A two or three sentence overview of what the project is.
The stack with versions pinned. "Laravel" is not enough. "Laravel 11, PHP 8.3, Pest 3" is.
The exact commands: test, lint, static analysis, dev server. Claude should never guess these.
The conventions that must hold on every change. For me that is TDD with Pest first, KISS, event sourcing through Spatie where it earns its place, domain logic kept free of framework code, and envaudit validating .env in CI.
Pointers out. One line each: architecture is in docs/DESIGN.md, current work is in docs/PLAN.md, decisions are in docs/DECISIONS.md.

That last group is the trick. CLAUDE.md does not contain the architecture. It contains the address of the architecture. Claude loads the detail on demand when a task needs it, and the rest of the time that detail is not burning context.

What belongs on disk

The docs/ folder is where the long material lives, and because it loads on demand it can be as long as it needs to be. Three files cover most projects:

DESIGN.md is the architecture and domain model. Bounded contexts, aggregates, the events each one records, the invariants they protect. This is your thinking written down once so Claude does not reinvent it every session, and so that when it asks "where does this logic belong" the answer is derivable from the file.

PLAN.md is the phased, plan-first breakdown of the work. Small phases, each finishable and verifiable, checked off as they land, with a short done log at the bottom so progress survives between sessions.

DECISIONS.md is a lightweight decision log. One short entry per significant choice: context, decision, trade-off. This is the file that stops you and Claude relitigating the same question three sessions later.

Add more only when a real need shows up. A TESTING.md when your test strategy is genuinely non-obvious. A separate DOMAIN.md when the glossary outgrows DESIGN.md. Not before. Empty scaffolding is just more for Claude to read.

The trick most setups miss: nested files

Claude Code does not only read the root CLAUDE.md. It also reads a CLAUDE.md in the directory it happens to be working in, layered on top of the root one. That means rules which only matter inside one folder can live in that folder instead of bloating the root file.

In a Laravel project with a real domain layer, I put a CLAUDE.md inside app/Domains that says: no framework imports here, aggregates extend Spatie's AggregateRoot and only record events, events are immutable and past-tense, and every change starts with a Pest test. None of that needs to be in the root file, because it is irrelevant when Claude is editing a controller or a Blade view. It loads exactly when Claude steps into the domain layer, and not before.

The starter

I put all of this into a small template repo you can copy straight into a project: claude-code-laravel-starter. It is the structure above, with every file as a fillable template rather than lorem ipsum, the Laravel and event sourcing conventions already baked in, and a nested domain-layer CLAUDE.md so the pattern is concrete.

claude-code-laravel-starter/
├── CLAUDE.md              # the lean anchor, auto-loaded every session
├── README.md
├── docs/
│   ├── DESIGN.md         # domain model, aggregates, events
│   ├── PLAN.md           # phased, plan-first implementation
│   └── DECISIONS.md      # lightweight ADR log
└── app/
    └── Domains/
        └── CLAUDE.md     # rules for the domain layer only

Copy it onto a fresh Laravel app, fill in your real stack and commands, replace the example domain with yours, and keep the root file tight.

Three rules to take away

If Claude needs it every time, it goes in CLAUDE.md. If only sometimes, it goes in docs/. Start with three files and add more only when something real demands it. And when a folder gets its own rules, give it its own CLAUDE.md instead of stretching the root one.

Start small, keep working memory tight, and let the disk hold the rest.

What if every Filament write went through an aggregate?

Alberto Arena — Tue, 23 Jun 2026 13:15:35 +0000

Filament is a great admin panel. Event sourcing is a great architectural pattern. Getting the two to work together, though, has always meant compromises: either you bypass your aggregates and write directly to the database, or you ditch Filament's create/edit flows and build everything from scratch. I've been using both in the same projects for a while, and that friction kept bothering me. So I built a plugin to remove it.

filament-event-sourcing is a Filament plugin that intercepts the standard create, edit, and delete actions and routes them through your domain aggregates. Your forms stay the same. Your validations and notifications stay the same. The only change is what happens on write: instead of an Eloquent save, the data flows through your aggregate and gets stored as a domain event. The read model is still updated by your projectors, exactly as you'd expect.

What you get out of the box

The plugin ships with a few things I found myself needing every time I mixed Filament with event sourcing.

The first is an event history browser. Every record gets a dedicated view of its event log: event class, timestamp, version, and the full JSON payload on expand. It's available either as a relation manager tab or as a slide-over action on the table. No extra setup, add the trait to your resource and it appears.

The second is a system-wide stored events browser. This gives you a searchable, filterable view of every event in your application, across all aggregates. You can filter by event class, aggregate UUID, or date range. It's read-only by design, which keeps the event log immutable.

The third is a projector replay page. You can trigger a replay for any registered projector directly from the admin panel, one at a time, with a live count of how many events were processed. Access is controlled by a three-layer authorization system: a plugin-level option, a config flag, and a Gate ability for fine-grained control.

How to install it

composer require albertoarena/filament-event-sourcing

You'll need Laravel 11 or 12, Filament 4.0+, and Spatie's laravel-event-sourcing 7.0+. The plugin registers itself automatically via Filament's plugin system.

From there, you add two traits to your resource (CreatesEventSourcedRecord and EditsEventSourcedRecord), wire up the delete action, and the rest is your aggregate logic. The plugin doesn't try to generate your events or commands, that's your domain, and it should stay that way.

A full working example with a Post entity is available in the demo repository, which walks through the complete setup from aggregate to Filament resource.

Where to go from here

The package is at version 0.1.0 and working. There's more I want to add, but the core is solid enough to use in real projects today. The documentation covers installation, each feature in detail, configuration, and authorization. If you're already using Spatie's event sourcing package with Filament, this plugin is probably the missing piece.

Feedback and contributions are welcome.

Your README Deserves Real Numbers

Alberto Arena — Fri, 05 Jun 2026 07:21:44 +0000

If you maintain an open-source repo, you have probably wondered at some point how many people actually visit it. GitHub has the answer buried in the Insights tab, but nobody looks there. It resets after 14 days, there is no history, and your README, the thing everyone sees, tells them nothing.

I built traffic-badge to fix that.

What it does

It is a GitHub Action that runs on a schedule, hits the official GitHub Traffic API, and commits a live SVG badge to a dedicated branch in your repo. You embed that badge in your README once and it updates automatically from then on.

The badge shows whatever you care about: total views, unique visitors, clones, unique cloners. One workflow file per metric, or stack them all.

Why it is different from the alternatives

A lot of traffic badge solutions rely on a third-party counting server. Which means you are trusting someone else's infrastructure, someone else's uptime, and someone else's definition of "a view." When that server goes down or changes its counting logic, your badge quietly becomes wrong.

traffic-badge does not phone home. The numbers come straight from GitHub's own API, the same data you would see in your Insights tab. The raw JSON is committed to your repo under a traffic-data branch, so you can inspect every data point, diff it, delete it, whatever you want. Full transparency.

It also handles the awkward overlap problem. GitHub's Traffic API returns a rolling 14-day window, so if you run the action daily you would normally double-count the days that appear in both runs. traffic-badge deduplicates by date automatically, so your cumulative totals stay accurate without any extra work on your end.

Setting it up

First, a heads-up that saves you the most common mistake: the default GITHUB_TOKEN does not work here. The Traffic API requires push or admin access, which that token does not have, so it fails with 403 Resource not accessible by integration. You need a Personal Access Token instead: a classic PAT with the repo scope, or a fine-grained PAT with Administration: read on the repo. Add it as a repository secret called TRAFFIC_TOKEN.

Then add a workflow file:

name: Traffic Badge
on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  badge:
    runs-on: ubuntu-latest
    steps:
      - uses: albertoarena/github-traffic-badge@v1
        with:
          token: ${{ secrets.TRAFFIC_TOKEN }}
          metric: views
          color: blue

Run it once manually, then grab the badge URL it creates and drop it in your README:

![Views](https://raw.githubusercontent.com/OWNER/REPO/traffic-data/badge.svg)

That is it. No server to maintain, no API key for a third-party service, no monthly bill. It runs on free GitHub-hosted runners.

The options worth knowing

The metric field accepts views, clones, views-unique, and clones-unique. You can run multiple workflows with different metrics if you want to show both.

color takes any named colour or a hex value. style supports the standard shields.io styles: flat, flat-square, plastic, for-the-badge. And if your numbers get large enough that the badge looks cluttered, there is an abbreviated flag that turns 12345 into 12.3K.

A note on how it is built

If you like to read the code before trusting an Action with a PAT, it is worth a look. Zero runtime dependencies, Node 20+ with built-in fetch and the built-in test runner. The counting and rendering logic is written as pure functions with the network, filesystem, and clock injected, so it is fully tested without touching disk or hitting the API. The zero-dependency constraint is enforced in CI.

It is open source, MIT licensed, and available on the GitHub Marketplace. The source is at albertoarena/github-traffic-badge. If you run into anything odd or have a feature request, issues are open.