Claude Code and Cursor on a Filament Codebase: Rules That Work

AI coding agents are very productive on Filament, because it’s declarative, conventional and well documented. They also fail on Filament in a very particular way: they confidently write Filament v3 code into a Filament v5 app. Training data is full of v3 examples. v4 changed the core APIs (schemas, unified actions, new namespaces) and v5 kept them.

Also Read: Filament v3 to v5 Upgrade: Skip v4 Without Breaking Your Panel

This guide sets up Claude Code and Cursor so that stops happening. Everything here also applies to Copilot, Codex-style agents and anything else that reads project rules.

Step 1: Install Laravel Boost and Filament’s skill

Laravel Boost is Laravel’s official toolkit for AI-assisted development: an MCP server, documentation search, and version-aware guidelines and skills. Filament ships an official Agent Skill for it:

composer require laravel/boost --dev
php artisan boost:install

In the installer, select Agent Skills, then filament/filament (skills). Boost detects your editors and agents and writes their config. Check that filament-development/SKILL.md exists in your agent’s skills directory.

If you installed Boost before Filament had a skill, rerun php artisan boost:install and select Agent Skills. The Filament docs note that boost:update alone doesn’t enable new features.

Also Read: Laravel: Filament v5 vs

Why this matters more than your own rules: the skill is maintained by the Filament team and follows the version you have installed. Your rules file should add project-specific knowledge on top, not restate the whole framework.

Step 2: Write a project rules file

Claude Code reads CLAUDE.md in the project root. Cursor reads .cursor/rules/*.mdc. Many agents also read AGENTS.md. Keep one source of truth and point the others at it.

Here’s a Filament v5 rules file you can adapt. It’s deliberately short. Long rules files get skimmed by models too.

# Project rules (Filament v5)

## Stack (do not guess versions)
- PHP 8.4, Laravel 13, Filament 5.x, Livewire 4, Tailwind CSS 4, Pest 4
- Filament v5 has the SAME API as v4. Never use Filament v3 APIs.

## Filament conventions
- Resources live in app/Filament/Resources/{Plural}/ with Pages/, Schemas/, Tables/.
- Forms and infolists use Filament\Schemas\Schema: `$schema->components([...])`.
- Layout components (Section, Grid, Tabs, Fieldset, Wizard) come from Filament\Schemas\Components.
- ALL actions come from Filament\Actions (EditAction, DeleteAction, BulkActionGroup...).
- Tables: `->recordActions([...])`, `->toolbarActions([...])`, `->headerActions([...])`.
- Icons: use the Filament\Support\Icons\Heroicon enum (e.g. Heroicon::OutlinedUsers).
- Enums used in forms/tables implement HasLabel, HasColor, HasIcon.
- Page `$view` is non-static: `protected string $view = '...'`.
- Widget `$pollingInterval` is non-static: `protected ?string $pollingInterval = '30s'`.

## Always
- Generate with artisan first: `php artisan make:filament-resource Name --generate --view`.
- Authorise with model policies. Custom actions use `->authorize('ability')`.
- In tenant-aware forms use `scopedUnique()` / `scopedExists()`, never plain unique/exists.
- Eager-load relationships used in table closures (`modifyQueryUsing(fn ($q) => $q->with(...))`).
- Put business logic in app/Actions classes; Filament closures call them.
- Write/extend Pest tests for every resource change (tests/Feature/Filament).

## Never
- Never publish or edit vendor Filament views. Use CSS hooks, render hooks or custom components.
- Never use `->visible()` as the only authorisation.
- Never run raw interpolated SQL in orderByRaw/DB::raw. Use bindings.
- Never add a Filament plugin without asking.

## Definition of done (run these, report results)
1. vendor/bin/pint --dirty
2. vendor/bin/phpstan analyse
3. php artisan test --filter=Filament

The v3 → v5 cheat sheet

The “Filament conventions” section is where the value is. When an agent slips, it’s almost always one of these:

Also Read: Livewire 4 Islands in PHP Filament: Where They Actually Help

Keep this table in your rules file. It costs a few hundred tokens and prevents most of the “why doesn’t this class exist?” loops.

Step 3: Cursor rules with scoping

Cursor supports scoped rules using front matter. Attach the Filament rules only where they apply:

---
description: Filament v5 conventions for resources, pages, widgets and tests
globs: app/Filament/**/*.php, tests/Feature/Filament/**/*.php, resources/views/filament/**/*.blade.php
alwaysApply: false
---
@CLAUDE.md

Follow the "Filament conventions", "Always" and "Never" sections above.
When unsure about a Filament API, search the docs via the Laravel Boost MCP tools
instead of guessing.

Save it as .cursor/rules/filament.mdc. Scoped rules keep unrelated work, such as a queue job, from being loaded down with Filament guidance.

Step 4: Close the loop with Claude Code hooks

Rules tell the agent what to do. Hooks make sure it happened. Claude Code runs hooks automatically around tool calls. Format every edited file with Pint:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "vendor/bin/pint --dirty --quiet" }
        ]
      }
    ]
  }
}

Put this in .claude/settings.json and commit it, so the whole team shares it. Keep hooks fast (Pint on dirty files takes a second or two). Leave slow checks, like the full test suite, to the “definition of done” step.

Also Read: Filament on Laravel 13: PHP The Complete Compatibility Checklist

Step 5: Reusable commands for common Filament jobs

Custom slash commands turn a good prompt into a team standard. For example, .claude/commands/filament-resource.md:

Create a Filament v5 resource for the model: $ARGUMENTS

1. Read the model, its migration and its policy (create the policy if missing).
2. Run `php artisan make:filament-resource $ARGUMENTS --generate --view`.
3. Refine the generated Schemas/ and Tables/ classes: searchable/sortable columns
   backed by indexes, filters for enum/status columns, eager loading for relationships.
4. Add Pest tests in tests/Feature/Filament/: list, search, create (with a validation
   dataset), edit, delete, and one permission test.
5. Run the Definition of Done commands from CLAUDE.md and report the output.

Cursor supports the same idea with saved prompts. The point is that “make a resource” means the same thing whoever asks.

Step 6: Plan before building bigger features

For anything with workflows (approvals, billing, imports), have the agent plan first, in plan mode or a separate planning session, and write the plan to a file you review. Filament’s paid Blueprint is built for this step. It adds planning, plan-review and security-audit skills, and it’s especially good at surfacing business decisions an agent would otherwise quietly make for you.

Without Blueprint, a good planning prompt still helps a lot:

Plan (don't implement) the refund workflow for orders in this Filament v5 app.
List models/columns, policies, Filament resources/actions (exact classes and
namespaces), state transitions, tests, and any business decisions I must make.
Write it to plans/refunds.md.

What good output looks like

When the setup works, a request like “add a refund action to orders” should come back with:

• a Filament\Actions\Action using ->schema([...]), ->authorize('refund') and a notification,
• the logic in app/Actions/RefundOrder.php,
• a policy method,
• Pest tests using TestAction::make('refund')->table($order),
• Pint, PHPStan and Pest output in the final message.

If you get a Filament\Tables\Actions\Action, your rules aren’t loaded. Check the file location and scoping.

Also Read: Build a Multi-Tenant SaaS Panel with Filament v5 (Step by Step)

Troubleshooting agents on Filament

FAQ

How do I stop AI agents writing Filament v3 code?

Install Laravel Boost with Filament’s Agent Skill, pin the versions in your rules file, and include a v3→v5 API cheat sheet (Schema instead of Form, Filament\Actions namespaces, recordActions()/toolbarActions()).

Where does Claude Code read project rules from?

From CLAUDE.md in the repository (and parent directories), plus settings, hooks and commands in .claude/. Laravel Boost can generate guideline files for the agents you select.

How do Cursor rules work with Filament?

Create .cursor/rules/filament.mdc with front matter (description, globs, alwaysApply) scoped to your Filament directories, and reference your main rules file inside it.

Is Filament Blueprint required for AI agents?

No. The free Laravel Boost Filament skill plus a good rules file covers most work. Blueprint helps most with planning complex features and with security audits.

Sources and further reading

• Filament: AI-assisted development
• Laravel Boost / AI documentation
• Claude Code documentation: memory and CLAUDE.md
• Claude Code hooks
• Cursor rules documentation

Related on The Web Tier: Filament Blueprint review · Testing Filament with Pest