用途
本指南用于在 Laravel 11 或 Laravel 12 项目中实施代码变更。核心原则是“以仓库实际安装的内容为准”：Laravel 11 与 12 应用在骨架、前端、认证和命令运行器方面差异很大，多数错误源于假设项目使用了全新应用的默认配置。
委派
默认在主对话中运行。委派可能增加用量：在使用子代理前，须就拟定的代理数量和范围获得明确批准。在该批准范围内可复用；若需扩大已批准的数量或范围，应再次询问。
决策前先检测
阅读仓库说明和相关文档归属，然后从 composer.json、composer.lock、package.json、前端锁文件、bootstrap/app.php、Compose 文件和 config/ 确认：
- 命令路径：宿主 PHP、Sail、Docker Compose 或仓库包装脚本，并保持一致使用；
- 是纯 API 还是全栈，以及前端：Inertia 配 React、Vue 或 Svelte；Livewire；或 Blade；
- 认证栈（Fortify、Sanctum、Passport 或自定义）和测试运行器（Pest 或 PHPUnit）。
对于版本敏感的行为，当 Boost 可用时使用 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 适用。
报告更改的行为、运行的检查及其结果，以及任何未解决的实质性假设。