apply-code-conventions

应用代码规范

风格的唯一来源： 风格与格式以项目配置的 linter 为准。本技能仅增加非风格行为和架构指导。关于 Hotwire + Tailwind 的具体内容，参见 apply-stack-conventions。

快速参考

主题	规则
原则	DRY、YAGNI、在有帮助之处使用 PORO、CoC、KISS
注释 / 标签	解释为什么；带标签的备注需要可操作的上下文
日志	一个经过验证的消息参数（通常是 JSON hash）；不要插值；出错时包含脱敏的回溯信息
深层技术栈	串联 apply-stack-conventions → 领域技能（services、jobs、RSpec）

HARD-GATE

TESTS GATE IMPLEMENTATION:
When this skill guides new behavior, the tests gate still applies:
PRD → TASKS → TEST (write, run, fail) → IMPLEMENTATION → …
No implementation code before a failing test. See write-tests.

核心流程

在审查或重构 Rails 代码时，请遵循以下顺序。每个步骤都对应输出中一个必需的检查点。

1. 运行 linter — 检测配置（例如 .rubocop.yml 或 .standard.yml），运行相应的工具，如果没有找到则注明缺失。输出：检测到 linter（或缺失）；风格以其为准。
2. 应用特定区域的规则 — 检查路径模式，并应用“按区域应用”表中的针对性指导。输出：针对每个相关已更改文件的具体逐路径建议。
3. 验证测试关卡 — 在任何新行为之前确认存在失败的测试。输出：失败的 spec、运行命令、预期失败、最小实现步骤、通过后的重新运行。
4. 强制结构化日志 — 确保所有 Rails.logger 调用都使用已安装 logger 经过验证的单消息接口；包含 event: 字段，并为错误包含脱敏的回溯信息。输出：应用下方子规则中的结构化日志规则。
5. 强制注释纪律 — 确保所有标签（TODO:、FIXME:）都有可操作的上下文（负责人、工单）。输出：应用下方子规则中的注释纪律规则。
6. 串联到专门技能 — 根据需要，使用集成表引入更深入的指导（安全、jobs、specs）。

语言： 除非明确要求其他语言，否则使用英语。

子规则

注释和带标签的备注

注释为什么，而不是是什么。标签 —— TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE: —— 必须携带可操作的上下文（负责人、工单、下一步）。裸标签无法通过审查。

# BAD — naked tag, no context
# TODO: fix this

# GOOD — TODO with next step + dependency
# TODO(jsmith, JIRA-1234): replace TIER_RATES with DB-backed lookup once billing API v2 is stable.

结构化日志

使用项目已安装的 logger 接口。标准 Ruby/Rails logger 接受一个消息参数；两参数的结构化调用需要经过验证的自定义适配器。在恢复边界处记录一次，脱敏敏感数据，并保留意外异常。

rescue Timeout::Error => e
  Rails.logger.error({ event: "order.processing_failed", error_class: e.class.name, backtrace: e.backtrace&.first(5) }.to_json)
  raise
end

按区域应用（路径模式）

区域	路径模式	指导
ActiveRecord 性能	app/models/**/*.rb	在循环中预加载；优先使用 pluck / exists? / find_each。
Controllers	app/controllers/**/*_controller.rb	强参数；精简 action → services；IDOR / PII → security-check。
RSpec	spec/**/*_spec.rb	FactoryBot；除非需要立即初始化，否则 let 优于 let!。
Service objects	app/services/**/*.rb	单一职责；.call / 注入依赖。
Background jobs	app/jobs/**/*.rb / app/workers/**/*.rb	幂等性、重试、队列选择以及副作用边界 → implement-background-job。

RSpec 和 let_it_be（test-prof）

仅当 test-prof 已在 Gemfile.lock 中时才推荐 let_it_be。否则默认使用 let；仅当惰性求值会破坏示例时才使用 let!。除非被要求，否则不要引入 test-prof。

扩展资源（渐进式披露）

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

• assets/checklist.md — 用于详细的代码审查清单。
• assets/snippets.md — 用于常见模式的快速代码片段。

在你的输出中记录加载了哪些资源以及原因，以便该过程可验证。

集成

技能	何时串联
apply-stack-conventions	技术栈特定：PostgreSQL、Hotwire、Tailwind
model-domain	当领域概念和不变量需要更清晰的 Rails 优先建模选择时
create-service-object	实现或完善服务对象
implement-background-job	Worker、队列、重试、幂等性
write-tests	Spec 风格、测试门禁（红/绿/重构）、request spec 与 controller spec
security-check	Controller、参数、IDOR、PII
code-review	合并前的完整 PR 审查