用 CLAUDE.md 统一 Laravel 技能冲突

给 Claude Code 多装几个 Laravel skill，可能得到一套互相冲突的开发规范：控制器该用单数还是复数，类要不要默认加 final，数据库测试该放在哪里，不同 skill 都有自己的答案。作者的建议是：只保留一个负责代码风格的 skill，把争议规则写进 CLAUDE.md。

这篇值得读的地方，是把「最佳实践」拆成了可以核对的具体指令。它提醒日常用 AI 编程的人：生成结果不一致，有时是上下文里的要求打架了。

六处分歧，先解决谁有权拍板

作者运营独立扩展目录 Skillselion，声明与 Anthropic、Laravel 团队无关联。2026 年 11 月 10 日，他们重新阅读了五个 Laravel skill 的当前 SKILL.md，以及 Boost 引用的规则文件。这是静态规则比较，没有展示实际生成代码的对照实验。

第一处分歧决定后面所有问题：已有代码和 skill 冲突时，听谁的？

Laravel Boost 的 laravel-best-practices 要求服从项目惯例，即便另一种方案理论上更好；Spatie 的 Laravel PHP style 要求服从 Laravel 约定，同时保持改动一致；jeffallan 的 laravel-specialist 则要求每次实现都以自己的模板为起点。

对于维护中的项目，我赞同作者偏向 Boost。同一代码库持续使用一套规则，通常比局部换成另一套「最佳实践」更容易维护。

接下来三处分歧，直接影响生成代码：

• Spatie 反对默认使用 final 或 readonly；laravel-specialist 要求使用 PHP 8.2+ 的 readonly、枚举和类型化属性，模型、API resource、队列任务模板又都声明 final class。ECC 的 laravel-security 示例也有七处 final class。两者解决的问题不同，不该被合并成一个默认开关。
• Boost 要求 ArticleController 这样的单数名称，Spatie 要求 PostsController。asyrafhussin 的示例是 PostController，原文引用的 Laravel 文档命令是 php artisan make:controller UserController。不过，三处用单数，也不能替已经统一复数命名的团队做决定。
• Boost 推荐 casts() 方法，但允许沿用 $casts 属性；Laravel 11、13 的项目骨架使用 protected function casts(): array。laravel-specialist 和 asyrafhussin 的模板却都用 $casts，后者还自称「Laravel 13 Best Practices」。

模板还有可直接核查的缺漏：laravel-specialist 的 scopePublished(Builder $query) 没有导入 Builder；asyrafhussin 调用 Attribute::make(...)，却没导入 Attribute。

skill 的名字和模板，都不能替代代码检查。

测试规则冲突，比命名更容易影响交付

第五处分歧是测试边界。Boost 的 testing-best-practices 要求先写 feature test，只有不使用框架的逻辑才写 unit test；ECC 的 laravel-tdd 却把使用 RefreshDatabase、通过 factory 写数据库的模型测试，放进 namespace Tests\Unit\Models;。

按 Boost 的定义，这些测试应该进入 tests/Feature。这里争论的是分类方式：如果团队以为 tests/Unit 可以脱离 Laravel 和数据库快速执行，目录里的实际依赖就会打破这个预期。

第六处分歧是覆盖率。laravel-specialist 要求超过 85%；laravel-tdd 要求 Models、Policies 达到 95%+，Overall 达到 80%+，并用 vendor/bin/pest --coverage --min=80 执行总体门槛。Boost 不设百分比，要求覆盖每个改动的决策和适用的高价值失败场景。

这些目标不能直接互换。覆盖率检查代码有没有被执行，分支和失败场景检查则更接近「行为有没有被验证」，两者仍都依赖断言质量。

测试框架也有分歧。Boost 的测试 skill 是 Blade 模板，会检查是否安装 pestphp/pest，再选择 Pest 或 PHPUnit；laravel-specialist 的 feature test 示例使用 Pest。laravel-tdd 当前英文文件同时展示两种框架，红绿循环示例从 PHPUnit 开始，而且「新测试优先 Pest」的旧指令已于 2026 年 6 月删除。要固定使用 Pest，就得明确写出来。

把争议写进 CLAUDE.md，还要检查版本前提

原文引用的 Claude Code 文档说明：CLAUDE.md 内容会进入会话上下文，skill 正文则在使用时加载。这让项目约定能够更早出现，但文档没有给出 CLAUDE.md 与 skill 的明确优先级排名。

因此，作者建议直接声明哪些约定覆盖 skill 默认值。下面是原文的配置示例，具体选择都需要按项目替换：

## Laravel conventions (these override any skill default)
- Controllers: singular resource name, e.g. ArticleController.
- Classes: no `final` or `readonly` unless the file already uses them.
- Casts: `casts()` method in new models. Keep `$casts` where it exists.
- Tests: Pest. Feature tests first. tests/Unit only for code that does not boot Laravel.
- Coverage: no percentage gate. Every changed branch, validation and policy gets a test.
- If a skill example disagrees with sibling files, copy the sibling files.

最后一行尤其关键：当示例与同目录代码冲突时，要求参考同目录文件。它把抽象的「保持一致」变成了可以执行的动作。不过，这段文字仍是约束提示，不能保证模型每次都遵守。

作者同时建议只保留一个风格 skill，其他能力按职责补充。例如 laravel-verification 会运行 Composer、Pint、PHPStan、测试、composer audit 和 migrate --pretend，并要求环境与 Composer 检查失败后立即停止。安全 skill 仍需受项目规则约束，它的生产配置示例包含 'debug' => (bool) env('APP_DEBUG', false)，类模板也会带入 final。

版本兼容同样要先核对。原文记录的 Boost 最新发布版是 2026 年 10 月 29 日的 v2.10.4，依赖要求如下：

"php": "^8.2",
"illuminate/support": "^11.45.3|^12.41.1|^13.0",

这里要看第二行的最低小版本要求，不能只看 Laravel 大版本。主分支已改为 ^12.41.1|^13.0；作者据此推测下一次发布可能结束 Laravel 11 支持，这还不是已发布的事实。Laravel 10 只能回退到 Boost v1.8 系列，而该系列不包含 skills。

我的判断

这篇最有用的建议，是把团队决策从扩展模板里拿回来。控制器命名、测试目录、覆盖率门槛，都应该能在仓库里找到明确答案。

但「只留一个风格 skill」仍是经验之谈。作者没有比较单 skill 与多 skill 的成功率，也没有实测规则写入 CLAUDE.md 后还会发生多少次冲突。「周一生成带 final、周二不带」是在描述潜在后果，并非实验结果。

此外，现有惯例也可能需要升级。Boost 的保守策略适合日常维护；如果任务就是迁移旧写法，仍应明确迁移范围和验收方式，不能让「沿用项目」阻止有计划的改动。

安装量也不是质量证明。laravel-specialist 当日累计安装量为 23,827，但这不能证明它适合与 Boost 同时加载。asyrafhussin 宣称有 7 类、31 条规则，其中 Performance 和 API Design 两类却注明尚无规则文件。选择时应该读实际内容。

能拿来做什么

• 在 Laravel 仓库的 CLAUDE.md 中写清控制器命名、类修饰符、casts 写法、测试框架、测试边界和覆盖率要求，并让 AI 优先参考同目录文件。
• 盘点现有 Laravel skills，只留一个负责风格的入口；需要安全或提交前检查时，再补充对应能力，同时检查示例是否夹带风格要求。
• 给 AI 生成的模型和测试做针对性审查：检查 Builder、Attribute 的导入，以及数据库测试的目录和依赖，配合静态分析与测试执行验证结果。
• 更新 Boost 前核对 PHP、illuminate/support 的实际约束，区分发布版与主分支；团队使用 Pest 时，明确写出 Tests: Pest，不要依赖旧指令。