apply-stack-conventions

应用技术栈约定

快速参考

技术栈领域	默认约定
Rails MVC	精简控制器；将非平凡的业务逻辑移到服务对象中
PostgreSQL	使用 includes 避免 N+1；使用数据库约束保证数据完整性
Hotwire	优先使用 Turbo Frames/Streams，再考虑 Stimulus；只有当 Turbo 无法处理交互时才使用 Stimulus
Tailwind	在视图中使用工具类；将重复的 UI 提取为局部模板/组件
认证	对每个涉及访问受控资源的操作应用 Devise 认证和 Pundit 授权

硬性关卡：TDD 循环

所有新代码必须先编写并验证测试，然后再进行实现。对每一层都严格遵循以下循环：

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

关键： 使用你的 shell/终端工具执行所有测试命令。不要伪造、模拟或仿真终端输出。复制粘贴实际观察到的输出。如果环境不支持运行测试，请停下来并告知用户——在没有验证 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。

代码风格： 如果项目使用了代码检查工具，将其视为格式化的唯一依据。对于跨领域的设计原则（DRY、YAGNI、结构化日志、按目录划分的规则），请使用 apply-code-conventions。

功能开发工作流

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

1. 模型 — 添加验证、关联、作用域；对循环中使用的任何关联使用 includes 进行预加载
2. 服务对象 — 从控制器中提取非平凡的业务逻辑（参见 create-service-object）
3. 控制器 — 保持 action 精简；委托给服务；使用 turbo_stream 和 html 格式响应
4. 视图 / Turbo 接线 — 将动态部分包裹在 <turbo-frame> 标签中；从控制器广播 turbo_stream 响应
5. Stimulus — 只有当客户端交互无法仅由 Turbo 处理时，才添加 Stimulus 控制器
6. Tailwind — 对视图应用工具类；将重复模式提取为局部模板或 Stimulus targets

每一步在接线到下一层之前都应保持可独立测试。在最终产物中，包含一个 Layer isolation 部分，指明针对模型/查询、服务、控制器/请求、视图/Turbo、Stimulus 和 Tailwind 的聚焦 spec 或检查。如果某一层未变更，标记为「不适用」；不要静默省略任何层。

服务对象模式

控制器通过 .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 修复，请参见下方的扩展资源部分。

应避免的陷阱

问题	正确做法
控制器 action 中有 15 行以上的业务逻辑	使用 .call 模式提取到服务对象中
访问受保护资源时没有授权检查	对每个涉及访问受控数据的操作应用 Pundit 策略

输出风格

每条响应都必须按顺序包含以下部分：

1. 技术栈决策 — 适用哪些 Rails、PostgreSQL、Hotwire、Stimulus、Tailwind、认证和服务对象约定。
2. 实现前的测试优先证明 — 按每一层遵循 HARD-GATE 循环（spec 文件内容 → RED 输出 → 实现 → GREEN 输出）。
3. 层隔离 — 对每个变更的层进行聚焦的 spec/检查；将未变更的层标记为“不适用”。
4. 分层实现 — 分别处理 model/query、service、controller、view、Stimulus 和 Tailwind 的变更。
5. 性能与安全检查 — 防止 N+1、使用授权策略、处理不安全的参数/内容。

扩展资源（渐进式披露）

仅在需要其特定内容时才加载这些文件：

• assets/snippets/eager_loading.rb — 在应用预加载模式以修复 N+1 查询时使用
• assets/snippets/n_plus_one_fix_example.rb — 当你需要一个包含修改前/后的完整 N+1 修复示例时使用
• assets/snippets/service_object.rb — 在将 controller 逻辑提取到服务对象中时使用
• 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	用于测试约定和完整的 red/green/refactor TDD 循环
review-architecture	用于超出约定的结构性审查