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.
\nWhen 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.
\nIn that pursuit, we tried two methods: deterministic extractors and an extraction skill.
\nMy 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.
\nThe 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.
\nI 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.
\nThe 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.
\nChoosing 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.
\nThe 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.
\nThe better replacement is an agent skill. It walks a structured audit across architecture, models, controllers, validation, data representation, testing, and other project surfaces.
\nMost of the skill explains what deserves to be left out.
\nBoost already provides Laravel-wide rules. A useful project rule carries information specific to this application, not Laravel in general.
\nThe skill asks whether a future agent could reasonably choose a different implementation. A likely divergence gives the convention value.
\n“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.
\nPint, 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.
\nThat being said, deliberate exceptions still matter.
\nIf 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.
\nArchitecture rules prevent expensive detours.
\n“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.
\nThe 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.
\nConvention 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.
\nThe current threshold is at least three consistent examples with no meaningful rival.
\nThe 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.
\nThe 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.
\nAfter approval, the agent calls Boost's record-rule MCP tool with three values:
glob for the files covered by the rule;title for the project decision; andnote for 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.
\nThe resulting files live under .ai/rules. They are readable, editable, version-controlled, and visible in pull-request review.
The project used the internal name “journal” for a while. The final pull request still carries that history.
\n“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.
\nNative 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.
\nBoost now delivers three kinds of agent instruction:
\n| 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.
\nThe split keeps the always-loaded layer small and scopes application knowledge.
\nProject 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.
\nModel 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.
\nA project rule can outlive the code that justified it.
\nPull-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.
\nBoost 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.
\nFor now, the rule files live close to the code and move through the same review process.
\nThe 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.
","headings":[{"level":2,"text":"Starting with a deterministic Artisan command","id":"starting-with-a-deterministic-artisan-command"},{"level":2,"text":"The infer-conventions skill","id":"the-infer-conventions-skill"},{"level":3,"text":"Look for project decisions","id":"look-for-project-decisions"},{"level":3,"text":"Let enforcement tools own style","id":"let-enforcement-tools-own-style"},{"level":3,"text":"Record architecture and deliberate absences","id":"record-architecture-and-deliberate-absences"},{"level":3,"text":"Describe the current code","id":"describe-the-current-code"},{"level":3,"text":"Show evidence before recording","id":"show-evidence-before-recording"},{"level":2,"text":"Recording the approved rule","id":"recording-the-approved-rule"},{"level":2,"text":"Why we call them rules","id":"why-we-call-them-rules"},{"level":2,"text":"Guidelines, skills, and rules","id":"guidelines-skills-and-rules"},{"level":2,"text":"Scoping Boost's own guidelines","id":"scoping-boost-s-own-guidelines"},{"level":2,"text":"Auditing stale rules","id":"auditing-stale-rules"},{"level":2,"text":"Review before recording","id":"review-before-recording"}]}}