Skip to content
Skills Library
Programming · Building & coding

lang-ruby

/lang-ruby

Use when writing, reviewing, testing or setting up Ruby backend code in a loops run (the ruby language pack) - toolchain, layout, race policy, coverage, idioms and footguns.

Repository
ai-loops ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing, reviewing, testing or setting up Ruby backend code in a loops run (the ruby language pack) - toolchain, layout, race policy, coverage, idioms and footguns.

Original author description

Use when writing, reviewing, testing or setting up Ruby backend code in a loops run (the ruby language pack) - toolchain, layout, race policy, coverage, idioms and footguns.

How it works

  1. When it applies
  2. Project rules first
  3. Toolchain the gate runs
  4. Race policy
  5. Coverage recipe
  6. Layers in Ruby
  7. Cache and cleanup
  8. Footguns
  9. Load on demand
Original SKILL.md headings · 109 lines, 1,003 words
SKILL.md preview
---
name: lang-ruby
description: Use when writing, reviewing, testing or setting up Ruby backend code in a loops run (the ruby language pack) - toolchain, layout, race policy, coverage, idioms and footguns.
---

# Ruby backend (pack `ruby`)

Rules: `specs/languages/ruby/RULES.md` (IDs `RUBY-<SEC>-NN`). Pack data: `specs/languages/ruby/pack.json` (`loops lang show ruby`). Ruby 4.0 (3.4 acceptable), Rails 8.1, as of 2026-11.

## When it applies

`loops lang detect` reports `ruby` (a `Gemfile`, `.ruby-version` or `*.gemspec` at the root). Rails, Sinatra, Roda, Hanami and plain gems all use this pack. Read the project's `.ruby-version` instead of assuming a Ruby version (RUBY-TOOL-01, RUBY-REPO-08).

## Project rules first

The repo's own config beats the pack defaults: `.rubocop.yml` or `.standard.yml`, `.rspec`, `sorbet/config` or `Steepfile`, `packwerk.yml`, `.editorconfig`, Rails conventions (RUBY-FW-02). The pack's `config_files` list is what the practices-researcher reads. Log every override: `loops run override --rule "<loops rule>" --project "<project rule, file:line>" --note "<what you did>"` (ROLES.md "Project rules first").

## Toolchain the gate runs

Agents run `loops gate` (WORKFLOW §6), or one check while iterating. Every command goes through `bundle exec` or a binstub, never a global gem (RUBY-TOOL-08). Checks are gated on committed config files (D17); a missing config skips the check.

| Check | Command | Runs when |
|---|---|---|
| `bundle` (deps) | `bundle check` | `Gemfile` exists; verify form, never installs |
| `rubocop` (lint, includes Layout) | `bundle exec rubocop {pkgs}` | `.rubocop.yml` |
| `standard` (lint) | `bundle exec standardrb {pkgs}` | `.standard.yml` (never with rubocop, RUBY-TOOL-02) |
| `sorbet` / `steep` (typecheck) | `bundle exec srb tc` / `bundle exec steep check` | `sorbet/config` / `Steepfile` |
| `packwerk` (arch) | `bundle exec packwerk check` | `packwerk.yml` or `package.yml` |
| `test` | `bundle exec rspec --order random --seed {seed} {pkgs}` (twice) | `.rspec` or `spec/` |
| `coverage` | loops reads `coverage/lcov.info` | after `test` |
| `brakeman` (sast) | `bundle exec brakeman -q --no-pager` | `config/application.rb`; optional |
| `bundler-audit` (vuln) | `bundle exec bundle-audit check --update` | `Gemfile.lock`; off by default (`--vuln`) |

Variant `minitest` (detected by `test/` + `bin/rails`): `test` becomes `bin/rails test --seed {seed} {pkgs}`. Variants are picked from the repo (D17); pin one in `.loops/config.json` `languages` if both `spec/` and `test/` exist. Test commands the guard recognises: `bundle exec rspec`, `rspec`, `bin/rspec`, `bin/rails test`, `rails test`, `bundle exec rake test`, `bundle exec parallel_rspec`.

Post-edit hook: `bundle exec rubocop -a --only Layout <file>` formats one file; `bundle exec rubocop <dir>` lints its directory. Missing tools fail open.

Install hints for optional tools: `bundle add <gem> --group development` (rubocop, standard, sorbet, steep, packwerk, brakeman, bundler-audit). Add one only in wave 0 and record it.

## Race policy

CRuby has no race detector, so `race.mode = none` (WORKFLOW §6, RUBY-CONC-05). The required substitute is the `test` check: random order, the seed printed by the runner, and a second run with a new seed (`repeat: 2`). To satisfy it:

- Never pin a seed, never disable random order (`config.order = :defined`), never add retries that hide a flake.
- A failure that passes on rerun is a bug: report the seed (`Randomized with seed N`) and fix the shared state.
- Stress tests (N threads against one shared object) and parallel runs (`parallel_rspec -n N`, Rails `parallelize`) are review items for code with shared state (RUBY-CONC-02/03).
- The GVL does not make `@x ||= v` or `count += 1` safe (RUBY-CONC-02).

## Coverage recipe

loops parses **lcov** at `coverage/lcov.info` (`./`-prefixed `SF:` paths are normalised). SimpleCov has no native lcov, so the project needs the `simplecov-lcov` gem and a helper that starts SimpleCov first. This is a D13 prerequisite: the architect or `ruby-engineer` adds it in wave 0 (an override, logged); otherwise the gate preflight fails with this snippet.

```ruby
# top of spec/spec_helper.rb (or test/test_helper.rb), before any app code loads
require "simplecov"
require "simplecov-lcov"
SimpleCov::Formatter::LcovFormatter.config do |c|
  c.report_with_single_file = true
  c.single_report_path = "coverage/lcov.info"
end
SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
  [SimpleCov::Formatter::HTMLFormatter, SimpleCov::Formatter::LcovFormatter]
)
SimpleCov.start do
  enable_coverage :branch
  track_files "{lib,app}/**/*.rb" # without it a never-loaded new file is absent from lcov and the gate cannot see it
  skip "/spec/"; skip "/test/"; skip "/config/"; skip "/db/"; skip "/vendor/"
end
```

New code needs at least 70% coverage (WORKFLOW §6). `skip` replaces the deprecated `add_filter` in SimpleCov 1.x (RUBY-TEST-06). Parallel runs: merge result sets with `SimpleCov.collate` first (RUBY-TEST-07). Details: `testing.md`.

## Layers in Ruby

```text
app/domain/            pure Ruby: entities, Data.define value objects, services (no Rails, no Time.now)
app/application/       use cases with one public `call`, ports as small modules
app/adapters/inbound/  controllers, jobs: thin
app/adapters/outbound/ ActiveRecord repositories, Faraday clients
config/initializers/container.rb   composition root
packs/<name>/package.yml           Packwerk boundaries
```

Constants are autoloaded by Zeitwerk from each `app/*` root; dependencies are constant references, not imports, so `loops arch` delegates to Packwerk (`arch.parser = none`, `native_check = packwerk`). The pack still lists `forbidden_in_domain` (`ActiveRecord`, `ActionController`, `Rails`, `Net::HTTP`, `Faraday`, `ENV`, `File`, `Sidekiq`) and `impure_calls` (`Time.now`, `Time.current`, `Date.today`, `rand`, `SecureRandom`, `Thread.new`, `sleep`, `puts`) for review (RUBY-ARCH-09). Rails conventions win over the hexagon when they conflict; log the override (RUBY-FW-02).

## Cache and cleanup

Per run: `BOOTSNAP_CACHE_DIR` and `TMPDIR`. Shared, never relocated: `BUNDLE_PATH` and `BUNDLE_USER_CACHE` (D15), because a per-run gem dir forces re-downloads (RUBY-OPS-05). Cleanup candidates: `coverage/`, `tmp/`, `log/*.log`, `.rspec_status`, `*.gem`, `.yardoc/`.

## Footguns

1. No race detector: do not assume the GVL protects compound operations.
2. `Marshal.load`/`YAML.load` on untrusted data: use `JSON.parse` or `YAML.safe_load`.
3. SQL interpolation: `where(name: x)`, never `"... #{x}"`.
4. Mass assignment: strong params, never `permit!`.
5. N+1 queries: `includes`, `strict_loading`.
6. Shared mutable state under Puma: class variables, class-level memoisation, mutable constants.
7. `rescue Exception` or an empty `rescue`.
8. Jobs that are not idempotent, or enqueued inside a transaction.
9. Callback side effects and fat models: use explicit use cases.
10. `Hash.new([])` and unfrozen literals: block form, `# frozen_string_literal: true`.

## Load on demand

- `repo.md`: layout, Gemfile and lockfile policy, version pins, CI order.
- `architecture.md`: hexagon in Rails, Zeitwerk, Packwerk, ports and DI.
- `idioms.md`: errors, nil, immutability, pattern matching, style.
- `testing.md`: RSpec or Minitest, SimpleCov and lcov setup, random order, doubles.
- `concurrency.md`: GVL, Puma threads, pools, jobs, Ractors, the race substitute.
- `security.md`: injection, deserialization, strong params, secrets, supply chain.
- `data-api.md`: Active Record, migrations, N+1, HTTP edges, logging, config, deployment.
- `frameworks.md`: Rails, Hanami, Sinatra, Roda, Puma, Sidekiq.
Files in this package (9)
  • SKILL.md 8 KB
  • architecture.md 3 KB
  • concurrency.md 2 KB
  • data-api.md 3 KB
  • frameworks.md 2 KB
  • idioms.md 2 KB
  • repo.md 3 KB
  • security.md 2 KB
  • testing.md 3 KB

Versions

The database has no other skills named lang-ruby.

Database snapshot: 13.11.2026 · package version c79e9fdda010 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100lang-go
    Use when writing, reviewing, testing or setting up Go backend code in a loops run (the go language pack) - toolchain, layout, race policy, coverage, idioms and footguns.
  • 100lang-python
    Use when writing, reviewing, testing or setting up Python backend code in a loops run (the python language pack) - toolchain, layout, race policy, coverage, idioms and footguns.
  • 100ruby
    Ruby language conventions, idioms, and modern features (3.x+) for writing idiomatic Ruby code. Covers error handling patterns, performance optimization, and Ruby-specific idioms. Use when writing or reviewing pure Ruby code, using modern Ruby features (pattern matching, ractors,…
  • 100ruby-script
    Use when writing a Ruby script. Covers the template, conventions, and required patterns.
  • 100ruby-idioms
    Modern Ruby (3.x) idioms: pattern matching, keyword arguments, immutable data structures, error hierarchies, and RSpec testing. Use when writing, modifying, or reviewing Ruby scripts, gems, or business logic. Pair with rails-idioms for Rails applications.
  • 86ruby-on-rails
    Ruby on Rails coding conventions and guidelines Triggers on: **/*.rb

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.