AGENT SKILL

ruby-architect

Architect-level Ruby guidance — application layering beyond fat models and controllers, service and query object boundaries, ActiveRecord usage limits, background job and connection-pool discipline, and the concurrency reality of a Ruby service. Use when designing or reviewing a Ruby (Rails or Rack) backend.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 0
Forks
0

01 前言 Front Matter

name
ruby-architect
license
MIT
metadata
{ "crusor-path": "website-architect/backend-development-architect/ruby-architect", "crusor-domain": "website-architect", "crusor-origin": "original", "crusor-sources": "guides.rubyonrails.org; api.rubyonrails.org; shopify.github.io/ruby-style-guide", "crusor-triggers": "ruby, rails, activerecord, sidekiq, rack, ruby on rails, service objects", "crusor-verified-on": "2026-10-30" }
description
Architect-level Ruby guidance — application layering beyond fat models and controllers, service and query object boundaries, ActiveRecord usage limits, background job and connection-pool discipline, and the concurrency reality of a Ruby service. Use when designing or reviewing a Ruby (Rails or Rack) backend.
compatibility
Ruby 3.2+; Rails 7/8 or Sinatra/Rack

03 SKILL.md 正文

Ruby Architect

Ruby's flexibility is the risk: without explicit boundaries, business logic dissolves into models, controllers and callbacks.

When to use

  • Rails product development, internal tools, API backends.
  • Existing Ruby codebase whose models have 900 lines.

When NOT to use

  • CPU-bound services or high-concurrency fan-out (Ruby's thread model and GVL make other runtimes cheaper).
  • Edge/serverless workloads with cold-start constraints.

Decision 1 — Layering

app/controllers/    params, auth, response codes
  app/services/     use-cases, transactions
    app/queries/    read paths (query objects)
      app/models/   persistence + small domain behaviour
  • A service object takes plain arguments, returns a result, raises typed errors.
  • Controllers never contain business rules; models never call external APIs.
  • Callbacks are for persistence invariants only — anything else is a hidden action that will surprise someone.
  • concerns/ only for genuinely shared behaviour; it is the most common hiding place for coupling.

Decision 2 — ActiveRecord discipline

  • Scopes for reusable filters; never build queries in views or controllers.
  • Eager-load (includes/preload) deliberately; N+1 is the default failure.
  • Keep transactions in services, short; no HTTP calls inside them.
  • find_by with explicit nil handling; avoid rescue nil and try chains that hide state.
  • Migrations reversible or explicitly forward-only; no data logic in schema migrations.

Decision 3 — Concurrency and runtime

  • Puma workers × threads sized to the DB pool — the pool is the real limit.
  • Assume the GVL: CPU-heavy work belongs in a job or a separate process.
  • Background jobs (Sidekiq) are idempotent and safe to retry; no job depends on a transient in-memory state.
  • Timeouts: DB statement timeout, HTTP client timeouts, job timeout.
  • Memory bloat: monitor RSS; long-running processes need restart policies.

Decision 4 — Testing and quality

  • Request specs for boundaries, model/unit specs for rules; avoid testing Rails itself.
  • Factories produce the minimum valid object; no shared mutable global state.
  • RuboCop for style, brakeman for security, bundler-audit for dependencies, all in CI.

Failure modes at scale

  • N+1 queries discovered in production on the busiest page.
  • A callback that sends email inside a transaction.
  • Job retries creating duplicate side effects.
  • Threads > DB pool → connection timeouts under load.
  • A 1,500-line model with 40 public methods used nowhere else.

Verification receipts

  1. Query count per endpoint (no N+1) in request specs.
  2. Transaction duration on the busiest write path.
  3. Puma threads vs pool size documented and load-tested.
  4. Job idempotency test: run twice, one effect.
  5. Brakeman + bundler-audit clean in CI.

04 同仓库更多 Skills

SriAkhilSJ
SriAkhilSJ/PulseAIRepo

interaction-patterns-architect

Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

design-system-ops-architect

Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

design-handoff-architect

Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

content-microcopy-architect

Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

ui-ux-implementation-architect

Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

test-strategy-architect

Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.

★ 0