Why Existing Codebases Need AI Context
A brand-new Laravel application can record project rules as the team makes decisions. An established application already has years of conventions baked into its controllers, models, tests, and directory structure. When a team installs Laravel Boost, something has to supply that historical context to the AI agent — either the codebase itself or the humans who built it.
The Laravel team tried two approaches before settling on the one that ships today.
Approach 1: Deterministic Artisan Command
The first attempt was an Artisan command called boost:infer-conventions. It used a file sampler, an inspector, and five hand-written detectors covering patterns such as enum key casing, guarded vs fillable, query-scope style, and validation-rule syntax. Each detector returned a confidence score, and Laravel Prompts presented the results in a multiselect.
The command spent zero model tokens — but it was never merged. Two problems killed it:
- Scalability: every new convention required a new hand-tuned PHP class covering discovery, evidence, confidence, and output.
- Signal quality: high-frequency patterns (e.g., anonymous migration classes) are framework defaults, not meaningful project decisions. Recording them teaches the agent very little.
Choosing useful rules requires judgment about framework defaults, enforcement tooling, architecture, and project history. That judgment is better delegated to a model.
Approach 2: The infer-conventions Skill
The replacement is an agent skill that audits roughly 49 convention dimensions across 10 groups. Adding a new dimension takes one line in a Markdown checklist.
What the Skill Looks For
Project decisions, not framework defaults. A useful rule carries information specific to this application. The skill asks: could a future agent reasonably choose a different implementation? If yes, the convention earns its place.
"Store money as integer cents" changes how the agent models, validates, serializes, and tests a value. "Use anonymous migration classes" repeats the framework default.
Deliberate absences. A missing abstraction can be part of the architecture. For example:
"Controllers and actions query Eloquent directly;
this application has no repository layer."
Writing that down keeps the agent within the application's existing shape.
Evidence threshold. A rule is proposed only when there are at least three consistent examples with no meaningful rival. The skill presents each candidate with the supporting files so the developer can reject, rescope, or reword it before anything is recorded.
What the Skill Deliberately Skips
Pint, Rector, linters, and static analyzers already enforce mechanical style choices. Repeating those in prose wastes context on work the tool will perform anyway. Project rules are for decisions that deterministic guards cannot cover — with one exception: if a project consistently preserves a form that Rector would rewrite, that may signal an architectural or compatibility decision worth surfacing.
Recording Approved Rules
After the developer approves a finding, the agent calls Boost's record-rule MCP tool with three values:
glob— the files covered by the ruletitle— the project decisionnote— context the agent needs while working
RuleRepository::write() derives an area from the glob, finds or creates the appropriate Markdown file, merges the path into its frontmatter, appends the rule, and rebuilds the generated index. The resulting files live under .ai/rules, are version-controlled, and appear in pull-request review.
Guidelines, Skills, and Rules — Three Layers
| Layer | Contents | Loading | Owner | |---|---|---|---| | Guidelines | Laravel-wide conventions | Always loaded | Laravel Boost | | Skills | Package knowledge and guided workflows | Loaded for relevant tasks | Laravel or package author | | Rules | Decisions from one application | Loaded by path or concept | The application team |
Keeping the always-loaded layer small and scoping application knowledge to path-matched rules reduces the context overhead on every agent turn.
Key Takeaways
- Deterministic detectors are fast but don't scale and can't judge convention value.
- The
infer-conventionsskill covers 49 dimensions; adding one takes a single Markdown line. - Rules require at least three consistent examples and explicit developer approval before being written.
- Enforcement tools (Pint, Rector) own style; project rules own decisions those tools can't encode.
- Rule files live in
.ai/rules, travel with the repo, and pass through normal PR review. - A future staleness audit could flag rules whose cited examples no longer exist.
Source: Extracting AI rules from an existing codebase — Laravel Blog
