Laravel Boost Project Rules: Teach AI Agents Your Team's Conventions

What Are Laravel Boost Project Rules?

Laravel Boost v2.5.0, released on August 4, 2026, ships project rules as a first-class feature. Rules are Markdown files stored in .ai/rules and committed to your repository. Each file carries a paths: frontmatter key listing the glob patterns it covers, so an agent reads a rule only when it is about to work on a matching path.

The feature was built by Pushpak Chhajed in pull request #852, shipped behind a flag in Boost v2.4.12, and is enabled by default from v2.5.0 onward.

What a Rule File Looks Like

A rule file is plain Markdown with a small YAML frontmatter block:

---
paths:
  - app/Jobs/**
---

# Jobs

## Reporting jobs run on the reports connection

Any job that reads from the reporting tables must set `$connection = 'reports'`.
The default connection shares its workers with checkout, so one slow report will
hold up every order behind it in the queue.

Boost maintains an .ai/rules/index.md that maps globs to rule files. Agents are instructed to check this index before planning or editing anything, which keeps irrelevant rules out of context entirely.

# Project Rules Index

| Applies to            | Rule file                    |
| --------------------- | ---------------------------- |
| app/Jobs/**           | .ai/rules/jobs.md            |
| database/migrations/** | .ai/rules/migrations.md     |

Because the .ai/rules directory is committed to version control, rules are reviewed in pull requests and apply to every agent any team member points at the codebase — not just the developer who wrote them.

Recording Rules Without Writing Them by Hand

You are not expected to author these files manually. Tell your agent to remember something, and it calls Boost's record-rule MCP tool with a glob, a title, and a note:

Remember that we never call Stripe from a controller. Billing always goes
through App\Billing\Gateway so the retries and logging stay in one place.

Boost determines which rule file the note belongs in, creates it if it does not exist, and rebuilds index.md. Rebuilding the index is critical — agents discover rules through index.md, so any file dropped into .ai/rules manually will go unread until the index is regenerated.

Bootstrapping an Existing Application

For applications already in production, Boost v2.5.0 adds an infer-conventions skill. Ask your agent to run it, and it audits your validation, controllers, authorisation, models, architecture, testing, frontend, database, and console code, then does an open-ended pass for base classes, shared traits, and module layouts.

The skill records what your code actually does, not what it should do. Framework defaults are skipped, Pint and Rector concerns are excluded, and genuinely mixed patterns are flagged for your review rather than recorded as conventions. Every finding includes supporting evidence for you to approve before it becomes a rule.

Why Scoped Rules Beat a Single Instructions File

A monolithic CLAUDE.md or AGENTS.md grows quickly. Six months in it can be five pages long, and all of it loads at the start of every session regardless of what you are working on. Scoped rules solve this: the agent checks the index, finds only the rows matching the current file path, and reads those. It is the same idea behind Boost skills, applied to your own codebase conventions instead of the framework's.

Getting Started

If Boost is already installed, one command brings everything up to date:

php artisan boost:update

This regenerates your CLAUDE.md or AGENTS.md with the instructions that point agents to .ai/rules/index.md, and installs the infer-conventions skill. To disable the feature entirely, set BOOST_RULES_ENABLED=false in your environment.

Key Takeaways

• Project rules live in .ai/rules as committed Markdown files with paths: frontmatter.
• An index.md file maps globs to rule files; agents check it before every edit.
• The record-rule MCP tool creates and indexes rules from a plain-language prompt.
• The infer-conventions skill audits an existing codebase and proposes rules for approval.
• Rules are version-controlled and team-wide, unlike an agent's local memory.
• Run php artisan boost:update to enable the feature on an existing Boost installation.

Source: Laravel Boost Project Rules: Teach Agents Your Conventions — Laravel News