Quem usa Claude Code, Cursor ou Codex num projeto Laravel já viu o agente inventar uma coluna que não existe, sugerir uma sintaxe do Laravel 10 num projeto em Laravel 13 ou perguntar de novo uma regra que você explicou ontem. O problema não é falta de inteligência do modelo. É falta de contexto sobre a sua aplicação.
O Laravel Boost é o pacote oficial que resolve isso. Ele entrega ao agente três coisas: um servidor MCP que enxerga o banco, os logs e a documentação certa para as versões instaladas; instruções sobre o ecossistema Laravel; e um lugar para guardar as regras do seu projeto. Neste tutorial vou instalar o Boost num projeto real, rodando em Docker, e mostrar cada recurso com um exemplo de uso.
O Boost é um pacote Composer mantido pela equipe do Laravel, instalado só como dependência de desenvolvimento. Ele não muda nada no comportamento da aplicação em produção. O trabalho dele é preparar o terreno para o agente de IA que você usa no editor ou no terminal.
Esse preparo acontece em quatro frentes:
A busca na documentação merece destaque. Segundo a documentação oficial, ela consulta uma base com mais de 17 mil trechos sobre o ecossistema Laravel, com busca semântica por embeddings, filtrada pelas versões que estão no seu composer.json. É isso que evita a sugestão de API antiga.
O exemplo deste tutorial é o projeto de estudo de RAG com editais de licitação que estou montando: Laravel 13, PostgreSQL 17 com pgvector, Redis e tudo em Docker. Os comandos valem para qualquer projeto Laravel a partir da versão 10.
A instalação tem dois passos. Primeiro o pacote:
composer require laravel/boost --devDepois o instalador interativo:
php artisan boost:installO comando pergunta quais agentes você usa (Claude Code, Cursor, Codex, Copilot, Junie e outros) e quais recursos quer instalar. Com base nisso, ele gera os arquivos que cada agente lê: o .mcp.json com a configuração do servidor, os arquivos de guidelines como AGENTS.md ou CLAUDE.md, as skills e um boost.json com as escolhas feitas.
Um detalhe importa para quem já tem um CLAUDE.md escrito à mão. O Boost só reescreve o conteúdo dentro do bloco <laravel-boost-guidelines>. O que estiver fora dele fica intacto. No meu projeto, o CLAUDE.md carrega as decisões técnicas da série, e elas continuaram lá depois da instalação.
No Claude Code e no Codex, o servidor costuma ser reconhecido sozinho. Se não for, dá para registrar pelo terminal, na pasta do projeto:
claude mcp add -s local -t stdio laravel-boost php artisan boost:mcpNo Cursor, o caminho é a paleta de comandos, opção "/open MCP Settings", ativando o laravel-boost. No Copilot do VS Code, a opção é "MCP: List Servers" e depois "Start server".
A documentação parte do princípio de que o PHP roda na sua máquina. Em projeto com Docker isso não vale, e o erro é silencioso: o agente tenta executar php artisan boost:mcp no host, onde não há PHP, ou há PHP mas o banco só responde pelo nome do serviço dentro da rede do Compose.
A instalação em si roda dentro do container, como qualquer comando do projeto:
docker compose exec app composer require laravel/boost --dev
docker compose exec app php artisan boost:installPara o servidor MCP, o comando registrado precisa entrar no container. No Claude Code:
claude mcp add -s local -t stdio laravel-boost -- docker compose exec -T app php artisan boost:mcpDuas observações. O app é o nome do serviço PHP no meu docker-compose.yml; troque pelo seu. E a flag -T desliga o terminal interativo, o que é necessário porque o MCP conversa pela entrada e saída padrão do processo. Com o terminal alocado, a comunicação quebra.
Para outros editores, a mesma ideia vai no JSON de configuração:
{
"mcpServers": {
"laravel-boost": {
"command": "docker",
"args": ["compose", "exec", "-T", "app", "php", "artisan", "boost:mcp"]
}
}
}O container precisa estar de pé antes de abrir o agente. Se não estiver, o servidor aparece como desconectado.
Estas são as ferramentas que o servidor expõe na versão atual:
| Ferramenta | O que faz |
|---|---|
| Application Info | Versões do PHP e do Laravel, banco em uso, pacotes do ecossistema e models Eloquent |
| Database Connections | Lista as conexões configuradas e a padrão |
| Database Schema | Lê a estrutura das tabelas |
| Database Query | Executa uma consulta no banco |
| Last Error | Lê o último erro dos logs da aplicação |
| Read Log Entries | Lê as últimas N entradas de log |
| Browser Logs | Lê erros do console do navegador |
| Get Absolute URL | Converte caminhos relativos em URLs completas |
| Search Docs | Busca na documentação filtrada pelas versões instaladas |
| Record Rule | Grava uma regra do projeto em .ai/rules
|
Você não chama essas ferramentas diretamente. Você escreve o pedido normalmente e o agente decide qual usar. Três exemplos do dia a dia:
Conferir o banco em vez de adivinhar. Pergunte algo como "quais colunas a tabela de chunks tem e quais aceitam nulo?". Sem o Boost, o agente lê as migrations e deduz. Com ele, consulta o schema real, que pode ter divergido das migrations depois de um rollback ou de uma alteração manual.
Investigar uma falha. "O job de embeddings falhou na fila, o que aconteceu?" leva o agente ao Last Error ou ao Read Log Entries. Ele lê o stack trace sem você precisar abrir o storage/logs e colar no chat.
Confirmar uma API. "Como declaro uma coluna vector no schema builder?" aciona o Search Docs. A resposta vem da documentação do Laravel 13, não do que o modelo lembra do treinamento.
Sobre segurança: desde a versão 2.6.0, o Database Query roda dentro de uma transação somente leitura imposta pelo banco. O agente consegue consultar, mas não altera dados por essa ferramenta.
As guidelines são o texto que o agente recebe assim que a sessão começa. O Boost traz guidelines para o framework e para os pacotes mais comuns do ecossistema, como Livewire, Inertia, Pest, Tailwind e Pint. Ele escolhe as versões certas lendo o composer.json.
O recurso mais útil é acrescentar as suas. Qualquer arquivo .md ou .blade.php dentro de .ai/guidelines/ entra junto com as guidelines oficiais na próxima execução do boost:install. No projeto de editais, criei este:
.ai/guidelines/project-stack.md## Stack do projeto
- Tudo roda em Docker. Comandos artisan, composer e testes sempre via `docker compose exec app`.
- Banco: PostgreSQL 17 com pgvector. Embeddings com 1536 dimensões (text-embedding-3-small).
- Paginação nas APIs usa os parâmetros skip e take.
- Nomes de variáveis, classes e arquivos em inglês.A primeira linha sozinha já economiza tempo: sem ela, o agente tenta rodar php artisan test no host e só depois descobre o Docker.
Também é possível substituir uma guideline oficial. Basta criar um arquivo com o mesmo caminho dela dentro de .ai/guidelines/. A documentação dá como exemplo a orientação de formulários do Inertia React 2, que pode ser trocada por um arquivo em .ai/guidelines/inertia-react/2/forms.blade.php.
Guideline boa é curta. Tudo que está ali ocupa contexto em toda sessão, mesmo quando a tarefa não tem relação com o assunto.
As skills resolvem justamente esse custo. Em vez de carregar tudo no início, o agente lê só a descrição de cada skill e abre o conteúdo completo quando a tarefa combina. O Boost instala as skills conforme os pacotes do projeto: com Pest instalado, vem a pest-testing; com Livewire, a livewire-development.
Uma skill própria fica em .ai/skills/{nome-da-skill}/SKILL.md, com um cabeçalho YAML contendo name e description. A descrição é o que o agente usa para decidir quando abrir a skill, então ela precisa dizer quando usar, não só o que é.
No projeto de editais, a extração de texto do PDF tem detalhes que não aparecem no código. Uma skill para isso ficaria assim:
.ai/skills/extracting-pdf-text/SKILL.md---
name: extracting-pdf-text
description: Extrair texto de editais em PDF preservando a página de origem. Use ao alterar a leitura de PDFs ou a limpeza do texto extraído.
---
# Extração de texto de editais
## Quando usar
Sempre que mexer no serviço de extração ou na limpeza do texto.
## Pontos de atenção
- Cada trecho precisa guardar a página de origem, porque a resposta final cita página e cláusula.
- O rodapé gerado pelo Word sai com letras espaçadas ("P á g i n a 3 | 48"). Uma regex escrita para "Página" não casa e falha sem erro.
- A numeração das cláusulas reinicia em cada anexo. Cláusula sozinha não identifica um trecho.Depois de criar o arquivo, rode o boost:update para instalar a skill junto com as do Boost. Como nas guidelines, uma skill com o mesmo nome de uma oficial a substitui.
A regra prática para escolher entre os dois: o que vale para quase toda tarefa vai em guideline; o que vale para um tipo de tarefa vai em skill.
Guidelines e skills ensinam o agente a escrever Laravel. As regras do projeto ensinam a escrever a sua aplicação: decisões tomadas, armadilhas que o código não revela, preferências que o agente insiste em ignorar.
A forma recomendada de gravar uma regra é pedir no chat. No projeto de editais, esbarrei num comportamento do Laravel: o $table->vector() cria a coluna como not null, e isso impede gravar os chunks antes de gerar os embeddings. Para o agente não repetir o erro, bastou escrever:
Lembre que colunas vector nas migrations devem ser nullable, porque os chunks são gravados antes dos embeddings.O agente chama a ferramenta Record Rule com um padrão de arquivos (glob), um título e a nota. O Boost cria ou atualiza o arquivo da área correspondente em .ai/rules/, num formato como este:
---
paths:
- database/migrations/**
---
# Migrations
## Colunas vector devem ser nullable
Os chunks são gravados antes dos embeddings. Uma coluna vector not null bloqueia esse fluxo.O Boost também mantém um .ai/rules/index.md que liga cada padrão de arquivos à sua regra. O agente consulta esse índice antes de editar um arquivo e só carrega as regras que se aplicam a ele. Por isso a documentação recomenda gravar sempre pela ferramenta: um arquivo criado à mão não entra no índice até a próxima regeneração.
Em projeto que já existe há anos, gravar regra por regra demora. A skill infer-conventions, instalada em todo projeto, varre o código e propõe as convenções que encontrar:
Use the infer-conventions skillEla percorre validação, controllers, autorização, models, testes, banco e outras áreas, e registra só o que foge do padrão do framework e aparece com consistência. Cada convenção é apresentada com a evidência encontrada, para você aprovar antes de virar regra. Padrões misturados são relatados, não gravados.
Se não quiser usar regras, a variável BOOST_RULES_ENABLED=false no .env desliga o recurso e remove a ferramenta Record Rule.
Guidelines e skills acompanham as versões dos pacotes. Quando você atualiza dependências, vale atualizá-las também:
php artisan boost:updateO comando também procura pacotes novos e oferece instalar as guidelines e skills deles. Para automatizar, entra nos scripts do Composer:
{
"scripts": {
"post-update-cmd": [
"@php artisan boost:update --ansi"
]
}
}Rodando por script, a pergunta sobre pacotes novos é pulada. Se quiser só atualizar o que já está instalado, use --no-discover.
Sobre o que versionar no Git, a divisão é esta:
.gitignore: .mcp.json, boost.json e os arquivos de guidelines gerados (CLAUDE.md, AGENTS.md, pasta do Junie). Eles são recriados pelo boost:install e pelo boost:update..ai/, com suas guidelines, skills e regras. É ela que a equipe compartilha.Aqui cabe um cuidado. Se o seu CLAUDE.md tem conteúdo escrito à mão fora do bloco do Boost, como o meu, ignorá-lo no Git significa perder esse conteúdo para quem clonar o repositório. Ou você continua versionando o arquivo, ou move esse texto para .ai/guidelines/, que é o caminho mais limpo.
Na versão 2.10, publicada em setembro de 2026, o Boost passou a usar o AGENTS.md também para as guidelines do Claude Code. Se você atualizou de uma versão anterior, confira qual arquivo o seu agente está lendo.
O Boost reduz chute, não elimina revisão. Um agente com o schema certo e a documentação certa ainda pode escrever uma consulta ineficiente ou um teste que não testa nada.
Ele também não sabe o que você não contou. A regra da coluna nullable só existe porque alguém esbarrou no problema e mandou gravar. O ganho real aparece com o tempo, à medida que as decisões do projeto saem da cabeça de quem desenvolve e vão para .ai/rules.
Por fim, é ferramenta de desenvolvimento. O --dev na instalação não é detalhe: o servidor MCP lê banco e logs, e não tem motivo para existir em produção.
Nenhum comentário ainda. Seja o primeiro.
Na última parte da série, um agente do Laravel AI SDK usa a busca vetorial como ferramenta e devolve uma checklist validada por schema, com o trecho e a página de cada exigência. Depois vêm a tela em React e uma lista do que um RAG mínimo deixa de fora.
Artigo, Avançados, Banco de dados, Docker, FrontEnd, Inteligência Artificial, Intermediários, Laravel, php, Postgres
A palavra "harness" tomou conta das conversas sobre agentes de IA em 2026, e por um bom motivo: ela descreve a peça que decide se um agente sobrevive fora de uma demonstração bonita e passa a resolver problema real em produção. Neste artigo, explico o que é um agent harness, mostro como ele aparece na prática num fluxo real de entrega de software (do épico até o deploy) e discuto por que a qualidade dessa camada importa mais do que o modelo de linguagem escolhido.
Artigo, Inteligência Artificial