SuperAPI AI 工具集

apply-stack-conventions

编程与开发

查看项目

更新于 10-27 13:02

技能介绍

用途

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 循环

所有新代码必须先编写并验证测试,然后才实现。每一层都遵循以下精确循环:

  1. 编写 spec 文件——展示完整文件内容,而不仅是路径。
  2. 运行:bundle exec rspec spec/[path]_spec.rb——验证其失败(观察到 RED 输出)。
  3. 编写实现代码。
  4. 重新运行同一命令——验证其通过(观察到 GREEN 输出)。
  5. 如有需要则重构,保持测试通过。

关键要求:使用 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。

功能开发工作流

对于典型功能,按以下顺序组合技术栈模式:

  1. Model——添加验证、关联、作用域;对循环中使用的任何关联用 includes 预加载。
  2. Service object——从控制器中抽取非平凡业务逻辑(参见 create-service-object)。
  3. Controller——保持 action 精简;委托给服务;以 turbo_stream 和 html 格式响应。
  4. View / Turbo 接线——将动态区块包裹在 <turbo-frame> 标签中;从控制器广播 turbo_stream 响应。
  5. Stimulus——仅当客户端交互无法由 Turbo 单独处理时,才添加控制器。
  6. 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。

输出风格

每个响应必须按顺序包含以下部分:

  1. Stack decisions——适用哪些 Rails、PostgreSQL、Hotwire、Stimulus、Tailwind、auth 和服务对象约定。
  2. Tests-first proof before implementation——按层遵循 HARD-GATE 循环(spec 文件内容 → RED 输出 → 实现 → GREEN 输出)。
  3. Layer isolation——为每个更改的层提供聚焦 spec/检查;未更改的层标记为 "not applicable"。
  4. Layered implementation——分离 model/query、service、controller、view、Stimulus 和 Tailwind 更改。
  5. 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 技术栈中编写新代码,以及对照这些约定进行代码审查。不适用于通用架构评审。

限制

该技能明确要求测试命令必须真实执行并粘贴实际输出,不得伪造或模拟;若环境不支持运行测试,应停止并告知用户。关于收费、价格、平台支持范围等信息,资料中暂未提供。