Stop stuffing every AI rule into one root file: apply-agent-rules

Most projects pile every AI agent rule into a single root CLAUDE.md (or AGENTS.md, or whichever filename their agent reads). The file grows past a thousand lines. Model rules sit next to test rules sit next to deployment notes. The agent has to swim through all of it to find the slice that applies to whatever file it’s editing.

Subdirectory rule files are a much better idea. A rule file in src/models/ describes how to write models. A rule file in tests/ describes how to write tests. A rule file in infra/terraform/ describes how to write Terraform. The agent picks up exactly the rules that apply to whatever it’s touching, nothing more.

The problem is authoring them. Writing 15–30 scoped rule files from scratch on every new project is real work, and most people don’t do it. I do — and I kept rewriting the same files across projects, which is what led to the tool I’m announcing today.

The setup tip first: one canonical filename

Different agents read different filenames. Claude wants CLAUDE.md, Codex wants AGENTS.md, Gemini wants GEMINI.md. Before going further, kill the duplication by telling Codex and Gemini to fall back to whatever filename you prefer:

~/.codex/config.toml

project_doc_fallback_filenames = ["CLAUDE.md", "GEMINI.md"]

~/.gemini/settings.json

{
  "context": {
    "fileName": ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]
  }
}

Note: Pick one canonical filename for your projects — for example CLAUDE.md — and every agent reads it. One file per directory, not six.

Where apply-agent-rules came from

The idea is shamelessly borrowed from skills.sh. I liked that I could install one skill (or a set of them) and have them symlinked into every LLM/agent I used — single install, applied everywhere.

Around the same time, I noticed I had built up a personal library of subdirectory-level rule files (mostly for Laravel and Filament, because that’s what I ship most often) that I was constantly copying into new projects, then editing in one repo and forgetting to backport to the others. It was getting hard to maintain.

So I built apply-agent-rules: the same install-once-applies-everywhere idea, but for scoped agent rule files in a project tree.

apply-agent-rules: drop scoped rule files over any project

apply-agent-rules is an npx-able CLI that takes a “rules template” repo and overlays it onto your project — dropping a rule file into every directory the template defines one for.

npx apply-agent-rules apply some-org/some-rules

That’s the whole pitch. It works for any project. Anything with a conventional directory structure will benefit — Rails, Django, Next.js, SvelteKit, Phoenix, Go services, Python packages, an in-house monorepo, a Terraform repo, whatever you ship on. If the directories carry meaning, a template repo can ship rules for each one.

# Template repo
src/models/CLAUDE.md
src/api/CLAUDE.md
infra/CLAUDE.md
tests/CLAUDE.md

# After install in your project
your-app/src/models/CLAUDE.md   ← scoped to models
your-app/src/api/CLAUDE.md      ← scoped to API code
your-app/infra/CLAUDE.md        ← scoped to infra
your-app/tests/CLAUDE.md        ← scoped to tests

Build a template repo once for whatever stack you ship on, and every new project starts with full scoped rules in seconds.

Not a Claude-only tool

The tool is supports multiple agents. When you run apply, it prompts you for which agents to install for:

Supported today: Claude, Codex, Gemini, Cursor, Windsurf, Cline. A template repo keeps one canonical file per directory (CLAUDE.md, AGENTS.md, etc). At install time the selected agents each get a copy under their expected filename in the same directory:

How install works

# Preview what would be written
npx apply-agent-rules list some-org/some-rules

# Install (interactive agent picker)
npx apply-agent-rules apply some-org/some-rules

# Non-interactive
npx apply-agent-rules apply some-org/some-rules --agents claude,codex

# Pin to a release tag for reproducible installs
npx apply-agent-rules apply some-org/[email protected] --agents claude

# Re-pull later, preserving your local edits, pruning removed files
npx apply-agent-rules update

Sources: GitHub shorthand (owner/repo), a pinned ref (owner/[email protected]), an HTTPS URL, an SSH URL, or a local path.

After install you get .apply-agent-rules.lock.json recording the source, ref, commit, and a SHA-256 for every installed file. That lockfile makes update non-destructive:

• Unmodified files (hash matches) get refreshed with new content.
• Locally-edited files are skipped with a warning — your edits survive.
• Files removed from the template get deleted locally (–no-prune to opt out).
• New files in the template get added.

Pass –force to overwrite drift on purpose.

Two packs I’ve published

To prove the model and give Laravel/Filament users something immediately useful, I published the rule libraries I’d been hauling between projects as two template repos:

• leek/laravel-agent-rules — mirrors the laravel/laravel skeleton.
• leek/filament-agent-rules — mirrors a FilamentPHP panel. Targets v4 and v5.

laravel-agent-rules

A CLAUDE.md next to every directory where Laravel makes a meaningful choice:

• app/Models/ — casts, relationships, scopes, eager loading, transactions
• app/Http/Controllers/ — controller rules + audience namespacing
• app/Http/Requests/ — Form Request rules + toDto() pattern
• app/Http/Resources/ — API Resource pattern + paginated envelope
• app/Policies/ — auto-discovery, before() fall-through, Response::deny* helpers
• app/Jobs/ — retries, afterCommit, unique/overlapping, batching, idempotency
• app/Livewire/ — wire:model.defer, #[Computed], $queryString, authorize-in-action
• app/Notifications/ — channels, viaQueues, shouldSend, on-demand routing
• app/Features/ — feature flags with Laravel Pennant
• database/migrations/ — migration workflow
• tests/ — Pest testing: datasets, Sanctum abilities, soft-delete asserts, allowlisted fakes

…and more across Actions, Support, Observers, Events, Listeners, Providers, routing, config, Blade components.

filament-agent-rules

Same pattern, scoped to FilamentPHP. Covers Resources, Pages, Relation Managers, Schemas (forms + infolists), Tables, Clusters, custom Pages, Widgets, Actions, PanelProviders, and Pest+Livewire tests.

Targets both Filament v4 and v5. v5 shipped in January 2026 with breaking renames — Tables\Actions\* collapsing into Filament\Actions\*, actions → recordActions, bulkActions → toolbarActions, BadgeColumn replaced by TextColumn::badge(), action modals moving from ->form() to ->schema(). Rules show v5 names and flag the v4 form inline so the agent doesn’t generate stale code on a v4 project.

There’s also a .claude/rules/ directory with glob-based frontmatter mirrors, for projects that deviate from the stock layout.

Build your own template

The Laravel and Filament packs are examples, not the point. The point is the model: one canonical rule file per directory, applied automatically to any matching project. Build a template repo for your stack and stop authoring rules from scratch every time you start a new project.

npx apply-agent-rules apply your-org/your-rules

Try it

# Anything you've built or someone else built
npx apply-agent-rules apply some-org/your-rules

# Laravel project
npx apply-agent-rules apply leek/laravel-agent-rules

# Filament project (compose with Laravel; Filament rules are panel-only)
npx apply-agent-rules apply leek/laravel-agent-rules
npx apply-agent-rules apply leek/filament-agent-rules

Repos:

• https://github.com/leek/apply-agent-rules
• https://github.com/leek/laravel-agent-rules
• https://github.com/leek/filament-agent-rules

MIT. Issues, PRs, and rule corrections welcome.