The Problem: AI Agents That Forget Your Conventions
Every team using an AI coding agent eventually watches it repeat a mistake the team already fixed. The agent extends the wrong base controller, reaches for float when the project stores money as integer cents, or re-introduces a repository layer the team removed two years ago.
The root cause is the same every time: the project has implicit conventions accumulated over its history, but the agent has no durable memory of them.
Laravel Boost already writes Laravel-specific guidelines into AGENTS.md or CLAUDE.md. Teams add their own conventions to the same file. Six months later, every prompt pays a context tax for rules that rarely apply to the task at hand — database migration rules loaded during Livewire work, backend testing rules loaded while editing a frontend component.
GitHub issue #606 captured the complaint clearly: Boost was putting too much into CLAUDE.md. Anthropic's own guidance recommends keeping that file under roughly 200 lines; longer files consume more context and reduce instruction adherence.
Why Semantic Search Was Deleted After Five Days
The first attempt to solve the problem was a semantic memory layer: two MCP tools (memory-search and memory-write) backed by a 359-line MemoryRepository with embeddings and a vector index.
It was deleted five days later.
A mature Laravel application accumulates a few dozen short convention files. A few dozen files do not justify the overhead of embeddings, a vector index, and an invalidation strategy. The index can drift from the Markdown source. Every coding agent already knows how to list files and run grep.
Anthropics's Agent SDK guidance recommends starting with agentic search and adding semantic retrieval only when scale or variation demands it. Boris Cherny described a similar experience building Claude Code: the team tried vector databases, ran into stale indexes and permission complexity, and found glob and grep more useful for code.
The Solution: A Generated Two-Column Index
The version that worked is simpler. Boost stores conventions as Markdown files under .ai/rules/. Each file declares the glob paths it covers. After every rule write, Boost regenerates .ai/rules/index.md — a short two-column table mapping glob patterns to rule file names.
The lookup the agent performs has four steps:
- Identify the file being edited.
- Match its path against the first column of the index.
- Read the rule file named in the second column.
- Apply those rules while planning and editing.
The index is small enough to include in the starting instructions. Detailed rules stay in their files until the task reaches a matching path. This progressive-disclosure shape keeps the starting context lean while ensuring relevant conventions load at the right moment.
Path Lookup Plus Grep
Glob matching handles conventions tied to a specific part of the directory tree. Some conventions — like storing money as integer cents — apply across models, actions, requests, and tests. For those, Boost instructs the agent to run grep -rin over .ai/rules.
The two routes together cover the cases seen in practice:
- Index lookup for path-scoped conventions.
- Grep for concepts that cross directory boundaries.
Writing and Reviewing Rules
Boost records conventions through an MCP tool named record-rule, which accepts a glob, title, and note. Internally, RuleRepository::write() derives an area from the glob, finds or creates the rule file, merges the glob into its frontmatter, appends the rule, and rebuilds index.md atomically.
Because the output is plain Markdown, the team can read every convention and review changes in a pull request — no opaque database required.
Key Takeaways
- Bloated instruction files reduce AI agent adherence; keep
CLAUDE.mdconcise. - Embeddings and vector indexes are overkill for a few dozen short convention files.
- A generated two-column glob-to-file index gives agents a scannable map without loading every rule upfront.
- Grep handles cross-cutting concepts that glob patterns cannot scope.
- Plain Markdown keeps conventions human-readable and pull-request reviewable.
- Staleness remains an open problem; pull-request review helps but does not fully solve drift.
Project rules are enabled by default in Laravel Boost.
