A new Laravel application can record project rules as the team makes decisions. An established application already has years of conventions encoded in its controllers, models, tests, directory structure, and deliberate absences.
When a team installs Laravel Boost, either the codebase or the humans have to supply context on that history. Our goal at Laravel is to provide the best developer experience across everything we touch, and it felt less than ideal to offer teams no help documenting their existing conventions.
In that pursuit, we tried two methods: deterministic extractors and an extraction skill.
My first attempt was the hand-written detectors. The implementation was fast and deterministic, but it also recorded patterns with very different levels of value. The version we kept uses an agent skill to collect evidence and lets the developer approve each proposed rule.
Starting with a deterministic Artisan command
The first implementation was an Artisan command named boost:infer-conventions.
It had a source-root resolver, a file sampler, an inspector, and five detectors covering patterns such as enum key casing, guarded versus fillable, query-scope style, and validation-rule syntax. Each detector returned a confidence score. Laravel Prompts presented the likely conventions in a multiselect.
The command spent zero model tokens, which was the reason I built it that way.
I did, however, leave the branch unmerged. It may have been fast, but it’s not scalable from a detection side. Each new convention needed another hand-tuned PHP class for discovery, evidence, confidence, and output.
The detector output also showed a problem with frequency. A codebase can contain hundreds of anonymous migration classes because Laravel generates them by default. Recording that pattern teaches the agent very little. A project rule earns its place when it preserves a choice another agent could plausibly miss.
Choosing useful rules requires judgment about framework defaults, enforcement tools, architecture, and project history. A model can make that judgment from evidence and show its work to the developer.
The skill that replaced the deterministic checks examines roughly 49 convention dimensions across 10 groups. Adding a dimension there takes one line in a Markdown checklist.
The infer-conventions skill
The better replacement is an agent skill. It walks a structured audit across architecture, models, controllers, validation, data representation, testing, and other project surfaces.
Most of the skill explains what deserves to be left out.
Look for project decisions
Boost already provides Laravel-wide rules. A useful project rule carries information specific to this application, not Laravel in general.
The skill asks whether a future agent could reasonably choose a different implementation. A likely divergence gives the convention value.
“Store money as integer cents” changes how the agent models, validates, serializes, and tests a value. “Use anonymous migration classes” usually repeats the framework default.
Let enforcement tools own style
Pint, Rector, linters, and static analyzers already apply many mechanical choices. Repeating those choices in prose spends context on work the tool will perform anyway. Anything that can be a deterministic guard should be one. Project rules are for things that can’t be covered by the myriad of deterministic guards.
That being said, deliberate exceptions still matter.
If a project consistently preserves a form that Rector would rewrite, the evidence may point to an architectural or compatibility decision. The skill surfaces that case for review.
Record architecture and deliberate absences
Architecture rules prevent expensive detours.
“Business logic lives in app/Actions and controllers delegate to actions” gives the agent a destination. “Controllers and actions query Eloquent directly; this application has no repository layer” records a boundary the team already chose.
A missing abstraction can be part of the architecture. Writing it down helps the agent stay within the application's existing shape.
Describe the current code
The audit reports the conventions the application follows today. Mixed evidence stays mixed in the report so the developer can resolve it. Our goal is to help surface conventions, not bless conventions that may or may not be intentional.
Convention inference is a poor place to redesign the application! Represent the application as it exists, and then proposed changes belong in their own discussion and pull request.
Show evidence before recording
The current threshold is at least three consistent examples with no meaningful rival.
The skill presents each proposed rule with the files that support it. The developer can reject the finding, change its scope, or edit the wording. Recording begins after that review.
The audit spends model tokens. Teams run it when adopting Boost and occasionally as the application changes. The rules it produces are then available to every relevant coding task.
Recording the approved rule
After approval, the agent calls Boost's record-rule MCP tool with three values:
globfor the files covered by the rule;titlefor the project decision; andnotefor the context the agent needs while working.
RuleRepository::write() derives an area from the stable part of the glob, finds or creates the appropriate Markdown file, merges the path into its frontmatter, appends the rule, and rebuilds the generated index.
The logical update spans the rule file and its index entry, so Boost owns the write through one tested operation. A successful call leaves both files aligned.
The resulting files live under .ai/rules. They are readable, editable, version-controlled, and visible in pull-request review.
Why we call them rules
The project used the internal name “journal” for a while. The final pull request still carries that history.
“Rules” fit the behavior better. Agents understand that nomenclature better, and it’s important to minimize the potential points of friction. These are shared project instructions committed to the application. Cursor, Windsurf, Cline, and Copilot already use the same word for similar files.
Native agent memory has its own role. Claude Code can maintain notes across sessions for a developer using Claude Code. Boost rules travel with the repository and reach the different agents used by the team. Version control gives them an owner, a review history, and a shared current version.
Guidelines, skills, and rules
Boost now delivers three kinds of agent instruction:
| Layer | Contents | Loading | Owner |
|---|---|---|---|
| Guidelines | Laravel-wide conventions used across many tasks | Always loaded | Laravel Boost |
| Skills | Package knowledge and guided workflows | Loaded for relevant tasks | Laravel or the package author |
| Rules | Decisions and boundaries from one application | Loaded by path or concept | The application team |
I use a simple placement test. Framework advice needed across many tasks belongs in guidelines. A deep workflow belongs in a skill. A decision discovered in one application belongs in its rules.
The split keeps the always-loaded layer small and scopes application knowledge.
Scoping Boost's own guidelines
Project rules also give Boost a way to reduce its own instruction footprint. There are Laravel conventions that only apply to certain parts of your application and you shouldn’t pay the context-tax of having them loaded for every turn.
Model guidance can load for app/Models/** and testing guidance can load for tests/**. Boost's corpus currently contains 16 candidate blocks using an internal @scoped directive. During installation, the experimental path can render those blocks into .ai/rules/boost.
We are still tuning the boundaries, so this behavior remains off by default and outside the public documentation. The experiment lets us apply the same scoping discipline to the guidelines Boost ships.
Auditing stale rules
A project rule can outlive the code that justified it.
Pull-request review gives the team a chance to update a rule alongside the implementation change. Old rules can still survive when the connection is easy to miss. An agent will then follow a clear instruction that describes an earlier version of the application.
Boost has no automated staleness audit today. A future audit could check whether cited examples still exist, flag scopes with zero matches, and rerun convention inference in report-only mode. Any rewrite should still go through developer review.
For now, the rule files live close to the code and move through the same review process.
Review before recording
The infer-conventions skill inspects the project, gathers examples, and proposes rules. The developer reviews the evidence and wording. record-rule writes the approved convention and refreshes its index entry.
Model judgment stays in the discovery step, and predictable code handles the write. The repository keeps the final record for the whole team. Install Boost to try it out.