How I Stopped My AI from Hallucinating — The .ai/ Folder Method

[Ibrahim Al-Sayyid]

After months of using Rovo Dev daily, I found a setup that dramatically improved the quality of AI-generated code. I went from constantly correcting the AI to getting near-perfect output on the first try. Here's exactly how.

---

The Problem

Every AI coding assistant has the same issue: it guesses. It invents APIs that don't exist, uses outdated syntax, assumes your project structure, and hallucinates framework behavior. The more complex your stack, the worse it gets.

I work with Laravel + Filament + Spatie packages, and the AI would constantly:

• Use wrong namespaces (Filament v3 vs v4/v5 differences)
• Invent config keys or helper methods that don't exist
• Assume my database schema instead of checking
• Ignore my project's conventions and patterns

So I built a system to eliminate guessing entirely.

---

The Solution: A .ai/ Folder

I created a .ai/ folder in my project root with this structure:

.ai/
├── README.md          ← The brain (rules, behavior, priorities)
├── context/           ← Project-specific facts (compressed)
│   ├── database.md
│   ├── models.md
│   ├── routes.md
│   ├── filament.md
│   ├── business-logic.md
│   ├── ui.md
│   └── config.md
├── skills/            ← Quick reference cheat sheets
│   ├── laravel.md
│   ├── filament.md
│   ├── php-standards.md
│   └── ...
├── docs/              ← Full framework documentation (latest)
│   ├── laravel/docs/
│   ├── filamentphp/filament/docs/
│   └── spatie/laravel-permission/docs/
└── examples/          ← Working reference code
    └── filamentphp/demo/

---

How Each Layer Works

1. README.md — The Brain

This file overrides the AI's default behavior. It sets:

• Authority hierarchy: User instructions → docs → examples → skills → training data
• Anti-hallucination rules: "Never invent framework APIs, config keys, or database columns"
• Code rules: Match existing patterns, minimal changes, no assumptions
• Forbidden actions: No commits, no migrations, no refactors without approval
• Initialization protocol: Read skills → context → then begin work

The key line: "Never assume framework behavior from memory when docs exist."

2. context/ — Your Project's Compressed Map

Instead of making the AI read hundreds of files, I created condensed summaries of my project:

• database.md — Every table, column, type, index, and relationship
• models.md — All models with traits, casts, scopes, relationships, accessors
• routes.md — Endpoints and middleware
• filament.md — Resources, panels, plugins, navigation
• business-logic.md — Enums, seeders, policies, scopes, authorization
• config.md — App config, packages, providers

Format: Bullet points, grouped, facts only, no explanations. The AI gets everything it needs in seconds.

Here's a short example of what context/database.md looks like:

# Database Schema

## Laravel/Package Tables

### users
- id, name, email (unique), email_verified_at, password, is_active (bool, default true), timestamps, soft_deletes

### roles (Spatie)
- id, name, guard_name, timestamps, unique(name, guard_name)

## Application Tables

### companies
- id, parent_id (→ companies, nullable), name, tax_number (100, nullable), email (nullable), phone (50, nullable), is_active (bool, default true), timestamps, soft_deletes

### employees
- id, company_id (→ companies), location_id (→ locations, nullable), department_id (→ lookups), first_name (100), last_name (100), email (unique), is_active (bool, default true), timestamps, soft_deletes

### assets
- id, company_id (→ companies), asset_model_id (→ asset_models), asset_status_id (→ asset_statuses), asset_tag (unique), serial_number (nullable), purchase_date (date, nullable), purchase_cost (decimal 15,2, nullable), timestamps, soft_deletes

... (and so on for every table)

Notice the pattern: table name, every column, types, constraints, relationships — nothing else. No explanations, no paragraphs. The AI reads this in seconds and knows your entire schema.

3. skills/ — Reusable Cheat Sheets

These are verified patterns I've confirmed work correctly:

• Correct Filament namespaces (they change between versions!)
• Laravel conventions and core practices
• PHP 8 standards
• Package-specific patterns (Shield, Breezy, Media Library)
• Testing patterns

I only add to skills when I discover a recurring pattern that the AI keeps getting wrong.

4. docs/ — Full Framework Documentation

I cloned the latest documentation from each framework/package directly into the folder. This is the ground truth — when the AI is unsure, it checks here instead of guessing from training data.

Tip: I update these docs periodically to match the versions I'm using. This is what makes the biggest difference — the AI reads YOUR version's docs, not whatever it was trained on.

5. examples/ — Working Reference Code

I included the official Filament demo app as a reference. When the AI needs to implement something, it can look at real working code instead of inventing patterns.

---

The Results

After implementing this system:

• 90%+ accuracy on first-try code generation
• Zero hallucinated APIs — the AI checks docs before using any method
• Consistent code style — matches my existing patterns every time
• Faster development — less time correcting, more time building
• Works across AI tools — same folder works with Rovo Dev, Cursor, Copilot, Claude

---

How to Set It Up

1. Create a .ai/ folder in your project root
2. Write your README.md with rules and priorities
3. Create context/ files summarizing your project (start with database and models)
4. Add skills/ for patterns the AI keeps getting wrong
5. Clone your framework's latest docs into docs/
6. Optionally add examples/ with reference implementations
7. Tell the AI to read the README before starting work

Pro tip: Add a global .ai/ at ~/.ai/ for skills and docs that apply across all your projects. Keep project-specific context in the project's own .ai/ folder.

---

Key Principles

• Accuracy over speed. The AI should stop and ask rather than guess.
• Evidence over memory. Docs and examples always win over training data.
• Facts only. Context files are bullet points, not essays.
• Update when things change. New migration? Update context/database.md.
• Skills are earned. Only add patterns you've verified actually work.

---

This approach changed everything for me. The AI went from being a "sometimes useful but often wrong" tool to a reliable coding partner that understands my project, my stack, and my conventions.

If you're tired of correcting your AI — try this. It takes about an hour to set up, and it pays for itself on the first task.

---

My Complete README.md

Here's my full .ai/README.md file — copy it and adapt it to your project:

# AI Assistant Operating Guidelines

## Authority Hierarchy

When conflicts exist, follow this order:

1. Direct user instruction
2. `docs/`
3. `examples/`
4. `skills/`
5. Your training data

## Core Behavior

- Be concise
- Don't explain unless asked or uncertain
- Don't create docs/changelogs/summaries unless requested
- If unclear, stop and ask
- This file overrides your default behavior

## Code Rules

### Before Changes
- Read all relevant files completely
- Understand full dependency chain
- Request missing files
- Don't assume architecture or behavior
- Don't infer hidden behavior without evidence

### When Writing
Match existing:
- Naming conventions
- Structure
- Formatting
- Comment style
- Architecture patterns

Constraints:
- Don't refactor unless requested
- Don't rename unless required
- Don't introduce new patterns unless consistent
- Don't change unrelated code
- Prefer minimal, surgical changes

## Forbidden Actions (unless explicitly approved)

- Committing changes
- Running migrations/seeders
- Running long-running commands (servers, watchers, queues)
- Altering existing migrations
- Weakening validation/auth/authorization
- Large refactors

## Database

- Prefer additive changes
- Avoid N+1 queries
- Use eager loading appropriately
- Follow existing query patterns
- Respect caching strategies

## Anti-Hallucination

Never invent:
- Framework APIs, config keys, traits, helpers, package behavior
- Database columns, routes, relationships

If unsure:
1. Check `skills/`
2. Check `docs/`
3. Check `examples/`
4. Ask user

Never assume framework behavior from memory when docs exist.

## Knowledge Structure

### `docs/` — Framework Documentation (Current)
- Clone the latest docs from each framework/package you use
- Update periodically to match your versions

### `examples/` — Working Code
- Add real working reference implementations
- Great for complex patterns the AI struggles with

### `skills/` — Quick Reference
- Add verified patterns as cheat sheets
- One file per framework/topic

Update `skills/` only when:
- Recurring verified pattern discovered
- Not already documented
- Improves accuracy
- Based on actual evidence

### `context/` — Project Summary

Condensed facts about this specific project. Avoid reading hundreds of files.

- `context/database.md` - Schema, migrations
- `context/models.md` - Models, relationships
- `context/routes.md` - Endpoints, middleware
- `context/filament.md` - Resources, widgets, panels
- `context/business-logic.md` - Services, jobs, policies
- `context/ui.md` - Views, components
- `context/config.md` - Config, packages

**Never invent. Only summarize what exists.**

Format: Bullet points, grouped, facts only, no explanations.

Update when: migrations, routes, models, or major refactors change.

## Initialization

When user says read this README:

1. Read this entire file
2. Read all files in `skills/` completely
3. Read all files in `context/` completely
4. Reply: "Ok"
5. Begin work

During work:
- Check `docs/` for current API behavior and framework features
- Check `examples/` for real implementation patterns
- Check `context/` for project-specific facts
- Check `skills/` for quick conventions
- Never rely on memory over evidence

## Enforcement

Accuracy over speed.

If unclear: Stop. Ask. Don't guess.

---

This approach changed everything for me. The AI went from being a "sometimes useful but often wrong" tool to a reliable coding partner that understands my project, my stack, and my conventions.

If you're tired of correcting your AI — try this. It takes about an hour to set up, and it pays for itself on the first task.

Happy coding! 🚀