跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

apply-code-conventions

Use when applying daily Rails conventions by path (DRY, YAGNI, PORO, CoC, KISS). Style defers to the project linter. Trigger words: conventions, clean code, RuboCop, DRY, YAGNI.

igmarin · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add igmarin/rails-agent-skills --skill apply-code-conventions

技能说明


name: apply-code-conventions type: atomic license: MIT description: > Use when applying daily Rails conventions by path (DRY, YAGNI, PORO, CoC, KISS). Style defers to the project linter. Trigger words: conventions, clean code, RuboCop, DRY, YAGNI. metadata: version: 1.0.0 user-invocable: "true"

Apply Code Conventions

Style source of truth: Style and formatting defer to the project's configured linter(s). This skill adds non-style behavior and architecture guidance only. For Hotwire + Tailwind specifics, see apply-stack-conventions.

Quick Reference

TopicRule
PrinciplesDRY, YAGNI, PORO where it helps, CoC, KISS
Comments / tagsExplain why; tagged notes need actionable context
LoggingFirst arg: static string; second arg: hash with event: key; no interpolation; backtrace on errors
Deep stacksChain apply-stack-conventions → domain skills (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.

Core Process

When reviewing or refactoring Rails code, follow this sequence. Each step maps to a required checkpoint in your output.

  1. Run linter — Detect config (e.g. .rubocop.yml or .standard.yml), run the appropriate tool, note absence if none found. Output: linter detected (or absent); style defers to it.
  2. Apply area-specific rules — Check path patterns and apply targeted guidance from the Apply by area table. Output: concrete per-path recommendations for every relevant changed file.
  3. Verify tests gate — Confirm failing tests exist before any new behavior. Output: failing spec, run command, expected failure, minimal implementation step, passing rerun.
  4. Enforce structured logging — Ensure all Rails.logger calls use static strings + structured hashes with an event: key, plus backtrace for errors. Output: apply structured logging rules from Sub-Rules below.
  5. Enforce comment discipline — Ensure all tags (TODO:, FIXME:) have actionable context (owner, ticket). Output: apply comment discipline rules from Sub-Rules below.
  6. Chain to specialised skills — Use the Integration table to pull in deeper guidance (security, jobs, specs) as needed.

Language: English unless explicitly requested otherwise.

Sub-Rules

Comments and tagged notes

Comment why, not what. Tags — TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE: — must carry actionable context (owner, ticket, next step). Naked tags fail review.

# 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.

Structured Logging

MANDATORY SHAPE — every Rails.logger.* call uses exactly two positional arguments.

Rails.logger.<level>(static_string_message, { event: "dot.namespaced", ...domain_fields })

# GOOD — error path with backtrace
rescue StandardError => e
  Rails.logger.error("order.processing_failed", {
    event: "order.processing_failed",
    error: e.message,
    backtrace: e.backtrace.first(5).join("\n")
  })
  raise
end
  • 1st arg (string): static string literal.
  • 2nd arg (hash): first key is always event:.

Apply by area (path patterns)

AreaPath patternGuidance
ActiveRecord performanceapp/models/**/*.rbEager load in loops; prefer pluck / exists? / find_each.
Controllersapp/controllers/**/*_controller.rbStrong params; thin actions → services; IDOR / PII → security-check.
RSpecspec/**/*_spec.rbFactoryBot; let > let! unless eager setup required.
Service objectsapp/services/**/*.rbSingle responsibility; .call / injected deps.
Background jobsapp/jobs/**/*.rb / app/workers/**/*.rbIdempotency, retries, queue choice, and side-effect boundaries → implement-background-job.

RSpec and let_it_be (test-prof)

Only recommend let_it_be if test-prof is already in Gemfile.lock. Otherwise default to let; reach for let! only when lazy evaluation would break the example. Don't introduce test-prof unless asked.

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

  • assets/checklist.md — Use for detailed code review checklists.
  • assets/snippets.md — Use for quick code snippets of common patterns.

Document which assets were loaded and why in your output so the process is verifiable.

Integration

SkillWhen to chain
apply-stack-conventionsStack-specific: PostgreSQL, Hotwire, Tailwind
model-domainWhen domain concepts and invariants need clearer Rails-first modeling choices
create-service-objectImplementing or refining service objects
implement-background-jobWorkers, queues, retries, idempotency
write-testsSpec style, tests gate (red/green/refactor), request vs controller specs
security-checkControllers, params, IDOR, PII
code-reviewFull PR pass before merge