用途
apply-stack-conventions 用于在编写新的 Rails 代码时,统一应用 PostgreSQL + Hotwire + Tailwind 技术栈的约定。它明确说明不适用于通用架构评审。触发词包括 stack conventions 等。
主要能力
该技能提供一份快速参考,按技术栈区域给出默认约定:
- Rails MVC:控制器保持精简(thin controllers);将非平凡业务逻辑移入服务对象(service objects)。
- PostgreSQL:使用 includes 避免 N+1 查询;使用数据库约束保证完整性。
- Hotwire:优先使用 Turbo Frames/Streams,其次才考虑 Stimulus;仅当 Turbo 无法处理交互性时才使用 Stimulus。
- Tailwind:在视图中使用工具类(utilities);将重复 UI 抽取为 partial/组件。
- Auth:对每个涉及访问受控资源的操作,应用 Devise 认证和 Pundit 授权。
使用方式
HARD-GATE:TDD 循环
所有新代码必须先编写并验证测试,然后才实现。每一层都遵循以下精确循环:
- 编写 spec 文件——展示完整文件内容,而不仅是路径。
- 运行:
bundle exec rspec spec/[path]_spec.rb——验证其失败(观察到 RED 输出)。 - 编写实现代码。
- 重新运行同一命令——验证其通过(观察到 GREEN 输出)。
- 如有需要则重构,保持测试通过。
关键要求:使用 shell/终端工具执行所有测试命令。不得伪造、mock 或模拟终端输出。复制粘贴实际观察到的输出。如果环境不支持运行测试,停止并告知用户——没有验证过的 RED 输出就不要继续实现。
红绿循环示例
Spec 文件——spec/models/order_spec.rb:
require 'rails_helper'
RSpec.describe Order, type: :model do
describe 'validations' do
it 'is invalid without a total' do
order = build(:order, total: nil)
expect(order).not_to be_valid
expect(order.errors[:total]).to include("can't be blank")
end
end
end
运行命令:
bundle exec rspec spec/models/order_spec.rb
观察到的 RED 输出——在此粘贴实际终端输出(预期失败)。
模型实现——app/models/order.rb:
class Order < ApplicationRecord
validates :total, presence: true
end
观察到的 GREEN 输出——在此粘贴实际终端输出(预期通过)。
核心流程
技术栈:Ruby on Rails、PostgreSQL、Hotwire(Turbo + Stimulus)、Tailwind CSS。
风格:如果项目使用 linter,将其视为格式化的唯一事实来源。对于横切设计原则(DRY、YAGNI、结构化日志、按目录的规则),使用 apply-code-conventions。
功能开发工作流
对于典型功能,按以下顺序组合技术栈模式:
- Model——添加验证、关联、作用域;对循环中使用的任何关联用 includes 预加载。
- Service object——从控制器中抽取非平凡业务逻辑(参见 create-service-object)。
- Controller——保持 action 精简;委托给服务;以 turbo_stream 和 html 格式响应。
- View / Turbo 接线——将动态区块包裹在
<turbo-frame>标签中;从控制器广播 turbo_stream 响应。 - Stimulus——仅当客户端交互无法由 Turbo 单独处理时,才添加控制器。
- Tailwind——将工具类应用到视图;将重复模式抽取为 partial 或 Stimulus targets。
每一步在接线到下一层之前,都应保持可独立测试。在最终产物中,包含一个 Layer isolation 部分,为 model/query、service、controller/request、view/Turbo、Stimulus 和 Tailwind 分别命名聚焦的 spec 或检查。如果某层未更改,标记为 "not applicable";不要静默省略任何层。
服务对象模式
控制器通过 .call 委托给服务;服务返回结果哈希。完整模式和实现细节参见 create-service-object 和 assets/snippets/service_object.rb。
# app/controllers/orders_controller.rb
def create
result = CreateOrderService.call(order_params)
if result[:success]
redirect_to result[:record], notice: 'Order created.'
else
render :new, status: :unprocessable_entity
end
end
关于预加载模式和 N+1 修复,参见下方 Extended Resources 部分。
应避免的陷阱
- 控制器 action 包含 15 行以上业务逻辑:使用
.call模式抽取到服务对象。 - 访问受保护资源而未做授权检查:对每个涉及访问受控数据的 action 应用 Pundit policy。
输出风格
每个响应必须按顺序包含以下部分:
- Stack decisions——适用哪些 Rails、PostgreSQL、Hotwire、Stimulus、Tailwind、auth 和服务对象约定。
- Tests-first proof before implementation——按层遵循 HARD-GATE 循环(spec 文件内容 → RED 输出 → 实现 → GREEN 输出)。
- Layer isolation——为每个更改的层提供聚焦 spec/检查;未更改的层标记为 "not applicable"。
- Layered implementation——分离 model/query、service、controller、view、Stimulus 和 Tailwind 更改。
- Performance and security checks——N+1 预防、授权策略使用、不安全参数/内容处理。
扩展资源(渐进式披露)
仅在需要其特定内容时加载这些文件:
assets/snippets/eager_loading.rb——在应用预加载模式修复 N+1 查询时使用。assets/snippets/n_plus_one_fix_example.rb——在需要完整的 N+1 修复前后对比示例时使用。assets/snippets/service_object.rb——在将控制器逻辑抽取到服务对象时使用。assets/snippets/turbo_frame.html.erb——在实现 Turbo Frame 模式时使用。assets/snippets/stimulus_controller.js——在添加 Stimulus 控制器时使用。assets/snippets/tailwind_component.html.erb——在构建 Tailwind 样式视图组件时使用。
集成
- apply-code-conventions:用于设计原则、结构化日志和路径特定规则。
- code-review:在对照这些约定审查现有代码时。
- create-service-object:在将业务逻辑抽取到服务对象时。
- write-tests:用于测试约定和完整的红/绿/重构 TDD 循环。
- review-architecture:用于超出约定的结构评审。
适用场景
适用于在 Rails + PostgreSQL + Hotwire + Tailwind 技术栈中编写新代码,以及对照这些约定进行代码审查。不适用于通用架构评审。
限制
该技能明确要求测试命令必须真实执行并粘贴实际输出,不得伪造或模拟;若环境不支持运行测试,应停止并告知用户。关于收费、价格、平台支持范围等信息,资料中暂未提供。