rails-conventions

rails-conventions 技能概览

rails-conventions 是什么

rails-conventions 是一项实用的 Rails 8.x 技能，适合基于你现有应用中的约定来编写和审查生产代码。它能帮助 agent 为模型、控制器、路由、Hotwire、任务、API 和测试选择更合适的实现形态，而不是套用那些未必符合当前代码库的通用 Rails 建议。

最适合后端工作的场景

当你需要 Rails 8 的后端开发指导时，适合使用 rails-conventions 技能，尤其是任务涉及 Active Record、Active Job、路由、params、缓存、安全或测试时。它对重视一致架构、可读 Ruby 代码，以及能融入现有系统的小改动的团队最有价值。

它优化的重点

这项技能的目标是在写代码前尽量减少猜测。它会推动 agent 先检查本地应用、沿用现有模式，并在一个需求可能有多种解法时明确指出取舍。因此，rails-conventions 指南非常适合功能开发、代码审查和真实代码库中的重构。

如何使用 rails-conventions 技能

安装并触发它

使用 rails-conventions install 流程，并带上仓库包名：npx skills add ethos-link/rails-conventions --skill rails-conventions。当提示词提到 Rails 8、Rails 后端重构、模型/控制器改动、后台任务或生产就绪性时，就该触发它。rails-conventions skill 最适合用于足够具体、能够映射到应用结构的任务，而不是笼统的“把这个改好”。

提供正确的输入

先说明用户目标、Rails 版本，以及涉及应用的哪一部分。一个更强的提示是：“在 Rails 8 中添加一个面向用户的导出任务，沿用现有队列适配器，匹配当前控制器和命名约定，并补上测试。”像“实现导出”这样较弱的提示会留下太多空白，尤其是在路由、任务后端选择和响应格式方面。

先读对文件

为了获得最佳结果，请按仓库的扫描顺序读取：Gemfile、config/application.rb、config/routes.rb、当前启用的 config/environments/*.rb，然后是 app/models/、app/controllers/ 以及 test/ 或 spec/ 中有代表性的文件。只要任务会触及这些领域，也要阅读 references/01-baseline-rails-8.md、references/04-controllers-and-params.md、references/07-background-jobs-overview.md 和 references/10-testing-strategy.md。

更能产出好结果的工作流

先让 agent 识别当前约定，再在修改前提出计划。比如：“先检查应用的路由风格、任务适配器和控制器模式，然后给出一个最小改动方案，确保与这些约定一致。”这和 rails-conventions usage 配合得很好，因为这项技能更看重与代码库对齐，而不是套用新的框架默认值。

rails-conventions 技能 FAQ

这只适用于 Rails 8 吗？

它是针对 Rails 8.x 以及 Rails 8 默认生态优化的，但如果你的应用已经在 8.x 线上、同时混有一些旧模式，它依然有用。如果项目更老，而且你还没准备好向 Rails 8 约定对齐，那么它可能不如一个普通的 Rails 提示词来得相关。

它和普通提示词有什么区别？

普通提示词也可能生成正确的 Rails 代码，但 rails-conventions 会加入安装阶段的引导：先扫描应用、保留本地约定，并避免对队列后端、序列化或测试风格做想当然的假设。通常这意味着第一次输出后需要重写的地方更少。

对初学者友好吗？

友好，前提是初学者手上已经有一个真实的 Rails 任务，并且希望得到约束和护栏。它不是纯教学型技能；最适合的场景是你能说清功能、指出相关文件，并接受答案可能是“沿用现有模式，而不是新建一套”。

什么时候不该用它？

不要在刻意保持框架无关的 greenfield 头脑风暴中使用 rails-conventions，也不要用于 Rails 后端开发之外的任务。如果你想在不先对照现有应用约定的情况下，把代码库统一到一套新的架构上，它也不是好选择。

如何改进 rails-conventions 技能

提供更强的上下文

最有效的改进来自更好的应用上下文，而不是更长的提示词。请包含 Rails 版本、队列适配器、测试框架，以及你想改动的文件或功能区域。如果你已经知道期望风格，也可以直接说出来：例如“匹配现有的 RESTful 路由和控制器命名”比“让它更地道”更有帮助。

明确要求做约定检查

当你要求先做本地约定审查、再实施时，这项技能会表现得更好。请它检查命名、路由形态、模型边界和测试放置位置。对 rails-conventions for Backend Development 尤其如此，因为最大的风险是写出能跑、但不符合应用风格的代码。

留意常见失败模式

最常见的问题，是过度依赖 Rails 默认值，而忽略仓库自己的模式。另一个常见失误，是跳过任务的适配器相关行为，或者默认只有一种测试框架。如果第一次输出显得很泛泛，就要求它再走一遍，并明确引用用于支撑判断的具体文件、约定和取舍。

用具体 diff 迭代

拿到第一版回答后，可以通过收窄范围来继续改进：一次只请求一个控制器、一个模型、一个路由或一个任务。如果技能给出多个都可行的方案，就让它按与当前代码库的契合度排序。这样通常能产出更紧的 rails-conventions guide，下一轮也更容易得到更好的后端代码。