laravel-11-12-app-guidelines

Laravel 11/12 应用指南

根据仓库实际安装的内容开展工作。Laravel 11 和 12 应用在骨架、前端、身份验证和命令运行方式上差异很大，大多数错误都源于假定项目使用了其实际并未采用的全新应用默认配置。

委派

默认在主对话中执行。委派可能会增加用量：使用子 Agent 前，先就计划使用的 Agent 数量和范围征得明确批准。在批准范围内可重复使用该批准；若要扩大已批准的数量或范围，则需再次征得批准。

先检测，再决定

阅读仓库说明和相关文档负责人提供的文档，然后通过 composer.json、composer.lock、package.json、前端锁文件、bootstrap/app.php、Compose 文件和 config/ 确认：

• 命令路径：主机 PHP、Sail、Docker Compose 或仓库封装脚本，并始终保持一致；
• 仅 API 还是全栈，以及前端类型：使用 React、Vue 或 Svelte 的 Inertia、Livewire，还是 Blade；
• 身份验证技术栈（Fortify、Sanctum、Passport 或自定义方案）和测试运行器（Pest 或 PHPUnit）。

对于依赖版本的行为，如果有 Laravel Boost，请使用 search-docs，因为它会根据已安装的版本筛选文档；否则请查阅已安装主版本的官方文档。boost-tools.md 介绍了 Boost 的用法及其数据安全限制。

遵循仓库的架构、命名、UI 语言和组件模式，并保留现有依赖，除非用户要求更改。

容易出错的框架细节

• 骨架。 现代骨架在 bootstrap/app.php 中配置中间件、异常和路由，在 bootstrap/providers.php 中注册服务提供者，并在 routes/console.php 中定义闭包命令和计划任务。从 Laravel 10 升级的应用可能仍使用 app/Http/Kernel.php 和 app/Console/Kernel.php；这种结构仍受支持，除非任务是迁移结构，否则应予以保留。
• API 路由。 全新应用不会包含 routes/api.php。install:api 会创建该文件并安装 Sanctum，因此只有在两者都符合预期时才运行。仅 API 的工作不应引入 Vite、Tailwind 或 Node。
• 列变更。 change() 会删除所有未重新声明的修饰符。检查当前列，并重复声明必须保留的修饰符。
• 破坏性数据库命令。 migrate:fresh、migrate:reset、回滚和 db:wipe 需要获得涵盖目标及其数据丢失风险的授权；可重复使用已授予的权限。
• 查询。 如果绑定的原始表达式和查询构造器比 Eloquent 更清晰，可以使用；绝不可将不可信输入插入 SQL。
• Inertia。 根据页面解析器确定页面目录和大小写规则。使用已安装 Inertia 主版本的表单和导航 API；其他主版本的示例不适用。
• Wayfinder（如果已安装）：使用命名导入以便输出进行 tree-shaking，并在路由或控制器变更后重新生成。
• Tailwind。 根据锁文件判断是 v3 还是 v4。v4 在 CSS 中配置（@import "tailwindcss"、@theme），并移除了 v3 中已弃用的实用类；除非要求迁移，否则应让正常运行的 v3 配置继续使用 v3。
• Livewire 和 Blade。 匹配已安装的 Livewire 主版本及相邻组件所采用的组件风格，不要引入第二套前端框架。

验证

保留仓库的测试运行器，并通过 php artisan help make:test 确认生成器标志。运行范围最小的相关测试（php artisan test <file> 或 --filter=），以及仓库要求的检查；在有助于保护重要行为时，添加回归测试。若受影响的契约或尚未解决的风险需要扩大测试范围，可在规定的测试套件预算内扩大。

对变更的代码运行已配置的格式化工具；如果已安装 Pint，可使用 vendor/bin/pint --dirty。

报告变更的行为、运行的检查及其结果，以及任何尚未解决的重要假设。