laravel-boost

Laravel Boost

概述

Laravel Boost 是一个官方 Laravel 软件包，通过提供可组合的指南、按需 Agent 技能、MCP（Model Context Protocol）服务，以及支持语义搜索的文档 API（涵盖 17,000 多条 Laravel 专属知识内容），加速 AI 辅助开发。它连接 AI 编码工具与 Laravel 生态系统，确保 AI Agent 生成高质量、符合约定的 Laravel 代码。

在项目中设置、配置或扩展 Laravel Boost，或将 AI Agent 与 Laravel 应用集成时，请应用此技能。

多阶段流程

阶段 1：评估

1. 确认 Laravel 版本兼容性（10.x、11.x、12.x）
2. 确认正在使用的 AI IDE 或 Agent（Cursor、Claude Code、Codex、Gemini CLI、GitHub Copilot、Junie）
3. 检查是否已存在 MCP 配置（.mcp.json）
4. 查看 .ai/ 中现有的指南和技能自定义项

停止——在确认 Laravel 版本兼容性和目标 IDE 之前，不要安装 Boost。

阶段 2：安装和配置

1. 安装软件包并运行安装程序
2. 为目标 IDE 配置 MCP 服务
3. 通过 Composer 钩子设置自动更新
4. 验证 AI Agent 是否可以访问 MCP 工具

停止——至少通过一次工具调用验证 MCP 服务已连接后，才能继续。

阶段 3：自定义

1. 在 .ai/guidelines/ 中添加项目专属指南
2. 在 .ai/skills/ 中创建领域专属技能
3. 当项目约定与默认 Laravel 约定不同时，覆盖内置指南或技能
4. 若要扩展至不受支持的 IDE，请注册自定义 Agent

停止——除非项目约定确实与默认 Laravel 约定不同，否则不要覆盖内置指南。

阶段 4：验证

1. 确认 MCP 服务能响应工具调用（应用信息、数据库架构、搜索文档）
2. 验证指南是否加载到 AI Agent 的上下文窗口中
3. 测试与领域相关的任务能否激活相应技能
4. 检查依赖项变更后，boost:update 是否能保持资源最新

IDE 设置决策表

IDE / Agent	设置方法	配置文件
Claude Code	CLI 命令	.mcp.json（自动生成）
Codex	CLI 命令	.mcp.json
Gemini CLI	CLI 命令	.mcp.json
Cursor	命令面板 GUI	.cursor/mcp.json
GitHub Copilot	命令面板 GUI	.mcp.json
Junie	设置 GUI	.mcp.json
自定义 / 不受支持	自定义 Agent 类	手动配置 MCP

安装

# Install as a development dependency
composer require laravel/boost --dev

# Run the installer — generates .mcp.json, guideline files, and boost.json
php artisan boost:install

安装程序会生成：

• .mcp.json — 用于 IDE 集成的 MCP 服务配置
• 根据检测到的软件包定制的指南文件（CLAUDE.md、AGENTS.md 等）
• boost.json — Boost 配置文件

特定 IDE 的 MCP 设置

IDE / Agent	设置命令或操作
Claude Code	claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp
Codex	codex mcp add laravel-boost -- php "artisan" "boost:mcp"
Gemini CLI	gemini mcp add -s project -t stdio laravel-boost php artisan boost:mcp
Cursor	命令面板 -> “Open MCP Settings” -> 打开 laravel-boost
GitHub Copilot	命令面板 -> “MCP: List Servers” -> 选择 laravel-boost -> “Start server”
Junie	Shift-Shift -> “MCP Settings” -> 勾选 laravel-boost -> Apply

手动配置 MCP

{
    "mcpServers": {
        "laravel-boost": {
            "command": "php",
            "args": ["artisan", "boost:mcp"]
        }
    }
}

保持资源更新

# Manual update after dependency changes
php artisan boost:update

# Automatic updates — add to composer.json scripts
{
    "scripts": {
        "post-update-cmd": [
            "@php artisan boost:update --ansi"
        ]
    }
}

MCP 服务工具

Laravel Boost 通过其 MCP 服务提供以下工具，让 AI Agent 能够直接访问应用上下文：

工具	用途	典型用法
应用信息	读取 PHP 和 Laravel 版本、数据库引擎、生态系统软件包、Eloquent 模型	在会话开始时发现上下文
数据库架构	读取完整数据库架构	规划迁移、生成模型
数据库查询	对数据库执行查询	检查数据、调试
数据库连接	检查可用的数据库连接	多数据库配置
搜索文档	在 Laravel 文档 API 中进行语义搜索	查找最佳实践、API 参考
最近错误	读取最新的应用日志错误	调试工作流
读取日志条目	读取最近的 N 条日志条目	监控、调试
浏览器日志	读取浏览器日志和错误	前端调试
获取绝对 URL	将相对路径 URI 转换为绝对 URL	生成链接

AI 指南

指南是可组合的指令文件，会预先加载到 AI Agent 的上下文中，提供广泛的规范和最佳实践。

可用的内置指南

软件包	支持的版本
Laravel Framework	Core、10.x、11.x、12.x
Livewire	Core、2.x、3.x、4.x
Flux UI	Core、Free、Pro
Inertia	React、Vue、Svelte（1.x-3.x）
Tailwind CSS	Core、3.x、4.x
Pest	Core、3.x、4.x
PHPUnit、Pint、Sail、Pennant、Volt、Wayfinder、Folio、Herd、MCP	Core

自定义指南

在 .ai/guidelines/ 中创建 .blade.php 或 .md 文件：

.ai/guidelines/team-conventions.md
.ai/guidelines/billing/stripe-patterns.blade.php

通过匹配内置指南的路径来覆盖它：

.ai/guidelines/inertia-react/2/forms.blade.php

第三方软件包指南

软件包作者可以在以下位置提供指南：

resources/boost/guidelines/core.blade.php

Agent 技能

技能是按需启用的知识模块，仅在相关时激活，从而减少上下文窗口膨胀。

可用的内置技能

技能	领域
livewire-development	Livewire 组件和响应性
inertia-react-development	使用 React 的 Inertia.js
inertia-vue-development	使用 Vue 的 Inertia.js
inertia-svelte-development	使用 Svelte 的 Inertia.js
pest-testing	Pest 测试模式
fluxui-development	Flux UI 组件
folio-routing	Folio 基于页面的路由
tailwindcss-development	Tailwind CSS 工具类
volt-development	Volt 单文件 Livewire 组件
pennant-development	Pennant 功能标志
wayfinder-development	Wayfinder 类型安全路由
mcp-development	MCP 服务／工具开发

自定义技能

创建 .ai/skills/{skill-name}/SKILL.md：

---
name: invoice-management
description: Build and work with invoice features including PDF generation and payment tracking.
---

# Invoice Management

## When to use this skill
Use when working with the invoicing module...

指南与技能决策表

问题	指南	技能
何时加载？	始终加载——预先加入上下文	按需加载——任务匹配时
适用范围有多广？	基础规范	专注于实现模式
对上下文窗口的影响？	持续存在（始终在上下文中）	最小（仅在需要时加载）
适合什么？	编码标准、软件包版本	分步实现指南
内容是否经常变化？	很少（稳定的规范）	经常（不断演进的模式）
是否适用于整个团队？	高（所有人都遵循）	不定（特定领域）

文档 API

Boost 提供语义搜索，涵盖 17,000 多条文档内容：

软件包	版本
Laravel Framework	10.x、11.x、12.x
Filament	2.x、3.x、4.x、5.x
Flux UI	2.x Free、2.x Pro
Inertia	1.x、2.x
Livewire	1.x、2.x、3.x、4.x
Nova	4.x、5.x
Pest	3.x、4.x
Tailwind CSS	3.x、4.x

Search Docs MCP 工具会查询此 API。指南和技能会自动指示 Agent 在需要实现细节时使用它。

何时使用与何时无需使用

场景	使用 Laravel Boost？	原因
使用 AI 辅助开发的 Laravel 项目	是	主要使用场景
团队使用 Cursor、Claude Code、Copilot 或其他 AI IDE	是	MCP 集成可改善输出
需要确保 AI 生成的代码遵循一致的 Laravel 约定	是	指南可强制执行标准
非 Laravel PHP 项目	否	Boost 专用于 Laravel
工作流中不使用 AI 编码工具	否	Boost 的价值在于与 AI Agent 集成
生产环境运行时性能优化	否	Boost 仅用于开发时，不是运行时优化工具
已有全面的自定义 AI 提示词	可选	Boost 可作为补充，也可替代它们

扩展 Boost

自定义 Agent 注册

对于开箱即用时不支持的 AI 工具：

// In AppServiceProvider::boot()
use Laravel\Boost\Boost;

Boost::registerAgent('custom-ide', CustomAgent::class);

自定义 Agent 类必须扩展 Laravel\Boost\Install\Agents\Agent 并实现相关接口：

• SupportsGuidelines — 用于生成指南文件
• SupportsMcp — 用于配置 MCP 服务
• SupportsSkills — 用于生成技能文件

反模式 / 常见错误

反模式	失败原因	替代做法
在生产环境中安装	Boost 仅用于开发时，会增加不必要的开销	使用 composer require --dev
覆盖所有内置指南	会偏离 Laravel 核心团队的建议	仅在项目确实存在差异时才覆盖
忽略 boost:update	指南会与已安装的软件包失去同步	每次 composer update 后运行
自定义技能范围过广	激活时会浪费上下文窗口令牌	将每项技能聚焦于单一领域
跳过 MCP 验证	配置错误的 MCP 会在无提示的情况下降低 AI Agent 的质量	安装后测试工具调用
不提交 .mcp.json	团队成员的 AI Agent 体验会不一致	提交到版本控制中
混用指南和技能	始终加载的内容会污染上下文窗口	约定放在指南中，模式放在技能中
升级后不运行安装程序	会缺少新的指南文件和 MCP 工具	重大升级后运行 php artisan boost:install

防止合理化的注意事项

• 不要因为“安装成功了”就跳过 MCP 验证——至少测试一次工具调用。
• 没有记录在案的偏离理由时，不要覆盖内置指南。
• 不要创建范围过广的技能——如果涵盖多个领域，就将其拆分。
• 不要在生产环境中安装 Boost——它只能作为 --dev 依赖项使用。
• 不要忘记在依赖项变更后运行 boost:update——过时的指南会降低 AI 输出质量。

文档查询（Context7）

使用 mcp__context7__resolve-library-id，然后使用 mcp__context7__query-docs 获取最新文档。返回的文档优先于记忆中的知识。

• laravel/framework — 用于查询 Laravel 核心 API、配置或 Artisan 命令
• livewire — 用于查询组件生命周期、wire 指令或 Alpine.js 集成

---

集成点

技能	关联方式
laravel-specialist	Boost 指南和技能可提升 AI 生成的 Laravel 代码质量
php-specialist	Boost 在生成的指南中遵循 PHP 版本和 PSR 标准
mcp-builder	Boost 的 MCP 服务是 MCP 模式的示例；可扩展它以创建自定义工具
self-learning	Boost 的 Application Info 工具会将项目上下文提供给学习阶段
senior-backend	Boost 的 Database Schema 和 Query 工具可支持后端架构决策
test-driven-development	Boost 的 Pest 技能为 AI 生成的测试提供测试模式

技能类型

灵活——根据项目需求调整流程阶段。新项目需要完成完整的安装和 IDE 设置（阶段 1-4）。现有的 Boost 安装可能只需进行自定义配置（阶段 3），或在 Laravel 升级后进行验证（阶段 4）。不可妥协的最低要求：验证 MCP 服务连接，并确认指南与已安装的软件包版本相符。