laravel

此技能是一个用于路由到参考资料集的外壳，而不是重述整个 Laravel 开发手册的地方。

不可妥协的规则：

1. 先加载 references/stack.md，然后仅加载与任务相关的参考资料。
2. 在使用特定版本的 API 之前，检查 composer.json 和 composer.lock。新应用和明确要求升级时，推荐 Laravel 13；切勿在处理无关工作时悄悄升级现有应用。
3. 控制器中不得包含业务逻辑。 控制器负责验证（Form Request）、委派（Action）和返回（API Resource），除此之外不得做其他事情。
4. 不得直接返回 Eloquent 模型。 所有响应都必须通过 API Resource 返回。
5. 不得内联验证。 所有验证都必须放在 Form Request 类中。
6. 不得使用 $guarded = []。 每个模型都必须显式定义 $fillable。
7. 不得使用原始查询。 使用 Eloquent 或带参数绑定的查询构造器。
8. 不得直接使用 queue:work。 所有队列处理都必须使用 Horizon。
9. 必须在 AppServiceProvider::boot() 中启用 Model::shouldBeStrict()。

laravel

输入

• $request：正在处理的 Laravel 任务、错误、功能或子系统

目标

按照正确的项目约定处理 Laravel 工作，使实现遵循现有后端架构，而不是采用通用的框架默认做法。

步骤 0：阅读技术栈约定

始终从以下文件开始：

• references/stack.md

该文件明确了此 Laravel 项目所采用的运行时、软件包和架构选择。

对于新应用、框架版本决策或从 Laravel 12 升级到 13，还需阅读：

• references/upgrading.md

成功标准：开始实现前，明确项目的 Laravel 技术栈选择。

步骤 1：仅加载相关参考资料

使用路由表选择与实际任务匹配的参考文件。不要批量加载整个参考目录树。

任务	阅读
开始会话 / 了解技术栈	references/stack.md
新建应用、选择框架版本、将 Laravel 12 升级到 13	references/upgrading.md
创建或修改文件、目录约定	references/folder-structure.md
API 路由、版本控制、中间件	references/routing.md
创建或编辑控制器	references/controller-pattern.md
为请求添加验证	references/form-requests.md
创建或编辑模型、关联、作用域	references/eloquent-models.md
API 响应转换、分页、筛选	references/api-resources.md
业务逻辑、Actions、DTO、服务提供者	references/service-layer.md
身份验证、令牌、角色、策略	references/auth.md
迁移、播种器、工厂、查询优化	references/database.md
错误响应、异常处理	references/error-handling.md
日志配置、结构化日志	references/logging.md
Redis 缓存、缓存失效、TTL 策略	references/caching.md
作业、队列、事件、Horizon、广播	references/queues-jobs.md
编写测试（功能或单元测试）	references/testing.md
安全加固、CORS、速率限制、Webhook	references/security.md
生成 API 文档	references/api-docs.md
Telescope、Horizon 仪表板、Pulse、健康检查	references/observability.md
Laravel/Filament 集成边界	references/filament.md，然后使用 laravel-filament 技能编写 Filament 代码
Docker 设置、CI/CD、部署	references/docker.md
通知、电子邮件、短信	references/notifications-mail.md
文件上传、S3、媒体库	references/file-storage.md
任务调度、cron 作业	references/scheduling.md
AI Agent、文本/图像/音频生成、嵌入、RAG	references/ai-sdk.md
AI 辅助开发、Boost 设置、指南、技能	references/boost.md
MCP 服务、向 AI 客户端开放应用、工具/资源/提示词	references/mcp.md

涉及多个任务？阅读多个文件。参考资料均为独立内容。

成功标准：仅应用与任务相关的 Laravel 约定。

步骤 2：遵循 Laravel 核心防护规则进行实现

始终遵循以下规则：

• 控制器负责验证、委派并返回结果
• 响应通过 API Resources 返回
• 列表端点使用分页
• 模型显式定义 $fillable
• 修改操作使用正确的 Action 或事务模式
• 队列遵循项目的队列和 Horizon 约定

成功标准：变更符合项目的 Laravel 架构，而不是走框架默认的捷径。

步骤 3：通过最精简的相关检查进行验证

使用与任务匹配的最小验证流程：

• PHPUnit 或 Pest 测试
• 针对性的 artisan 或框架检查
• 如果代码库工作流中已有静态分析或 lint 检查，则使用这些检查
• 对于框架升级，执行 references/upgrading.md 中的依赖项和回归检查

成功标准：按照此 Laravel 项目的预期方式验证变更。

防护规则

• 不要将整本 Laravel 手册内联到 SKILL.md 中。
• 不要跳过 references/stack.md。
• 不要直接返回原始 Eloquent 模型。
• 不要将业务逻辑放在控制器中。
• 除非任务包含升级，否则不要在 Laravel 12 项目中使用仅适用于 Laravel 13 的 API。
• 不要固定为今天发布的 Laravel 补丁版本；使用受支持的 ^13.0 约束和锁文件。
• 不要添加 disable-model-invocation；这是常规领域技能。

何时加载参考资料

• references/stack.md 始终加载。

• 然后仅加载 references/ 下与任务相关的文件

输出约定

报告：

1. 检测到的 Laravel 主版本，以及是否推荐使用 Laravel 13 或已在使用 Laravel 13
2. 加载了哪些 Laravel 参考资料
3. 选择的架构模式
4. 所做的更改
5. 运行的验证