ruby-workflow - Claude MCP Skill

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

# Ruby Projects Workflow

## Tool Grid

| Task | Tool | Command |
|------|------|---------|
| Lint | StandardRB | `bundle exec standardrb` |
| Format | StandardRB | `bundle exec standardrb --fix` |
| Type check | Sorbet | `bundle exec srb tc` |
| Semantic | Reek | `bundle exec reek` |
| Dead code | debride | `bundle exec debride .` |
| Complexity | Flog | `bundle exec flog lib/` |
| Test | RSpec | `bundle exec rspec` |
| Test | Minitest | `bundle exec rake test` |

---

## Ruby Version

- Projects SHOULD target Ruby 3.x+
- `.ruby-version` file MUST be present in project root
- YJIT SHOULD be enabled in production (`--yjit` flag or `RUBY_YJIT_ENABLE=1`)

---

## Ruby 3.x+ Features

### Pattern Matching

Pattern matching SHOULD be used for complex conditionals:

```ruby
# Preferred
case response
in { status: 200, body: }
  process(body)
in { status: 404 }
  handle_not_found
in { status: 500.. }
  handle_server_error
end

# Also valid for single patterns
response => { data: { users: } }
```

### Data Class

`Data.define` SHOULD be used for immutable value objects (Ruby 3.2+):

```ruby
# Preferred over Struct for immutable data
Point = Data.define(:x, :y) do
  def distance_from_origin
    Math.sqrt(x**2 + y**2)
  end
end

point = Point.new(3, 4)
point.x = 5  # => FrozenError (immutable by default)
```

### The `it` Keyword

The `it` keyword (Ruby 3.4+) SHOULD be used for single-parameter blocks:

```ruby
# Preferred (Ruby 3.4+)
users.map { it.name.upcase }

# Also acceptable
users.map { _1.name.upcase }

# Legacy (still valid)
users.map { |user| user.name.upcase }
```

---

## Bundler & Dependencies

### Gemfile Rules

- `Gemfile` MUST be present for all projects
- `Gemfile.lock` MUST be committed to version control
- Gems SHOULD specify version constraints:

```ruby
# Preferred - pessimistic version constraint
gem "rails", "~> 7.1"

# Acceptable - exact version for critical deps
gem "pg", "1.5.4"

# Avoid - no version constraint
gem "nokogiri"  # May break unexpectedly
```

### Bundle Commands

| Command | Use Case |
|---------|----------|
| `bundle install` | Install dependencies |
| `bundle update GEM` | Update specific gem |
| `bundle exec CMD` | Run command with bundled gems |
| `bundle outdated` | Check for updates |
| `bundle audit` | Security vulnerability check |

All Ruby commands MUST use `bundle exec` prefix to ensure correct gem versions.

---

## Naming Conventions

| Element | Convention | Example |
|---------|------------|---------|
| Files | snake_case | `user_service.rb` |
| Classes/Modules | PascalCase | `UserService` |
| Methods | snake_case | `find_by_email` |
| Variables | snake_case | `current_user` |
| Constants | SCREAMING_SNAKE | `MAX_RETRIES` |
| Predicates | trailing `?` | `valid?`, `empty?` |
| Dangerous | trailing `!` | `save!`, `destroy!` |
| Setters | trailing `=` | `name=` |

### Method Naming

- Predicate methods MUST return boolean and end with `?`
- Bang methods SHOULD indicate danger (mutation, exceptions) with `!`
- Private methods SHOULD NOT use underscore prefix (use `private` keyword)

---

## Code Style

### StandardRB

StandardRB SHOULD be used over RuboCop for simplicity:

- Zero configuration required
- Consistent style across projects
- Auto-fix available

```ruby
# .standard.yml (optional overrides)
ruby_version: 3.3
ignore:
  - "db/schema.rb"
  - "vendor/**/*"
```

### Style Guidelines

```ruby
# String literals - prefer double quotes
name = "Ruby"

# Symbol arrays
%i[foo bar baz]

# String arrays
%w[apple banana cherry]

# Heredocs for multiline strings
query = <<~SQL
  SELECT * FROM users
  WHERE active = true
SQL

# Safe navigation operator
user&.profile&.avatar_url

# Endless methods (Ruby 3.0+) for simple one-liners
def full_name = "#{first_name} #{last_name}"
```

### Method Definitions

```ruby
# Keyword arguments SHOULD be preferred for optional params
def create_user(name:, email:, role: :member)
  # ...
end

# Avoid positional arguments beyond 2-3 parameters
# Bad
def create_user(name, email, role, active, verified)

# Good
def create_user(name:, email:, role:, active:, verified:)
```

---

## Testing

### RSpec (Preferred)

RSpec SHOULD be the default testing framework:

```ruby
# spec/services/user_service_spec.rb
RSpec.describe UserService do
  describe "#create" do
    context "with valid attributes" do
      it "creates a new user" do
        result = described_class.new.create(name: "Test")
        expect(result).to be_success
      end
    end

    context "with invalid attributes" do
      it "returns failure" do
        result = described_class.new.create(name: "")
        expect(result).to be_failure
      end
    end
  end
end
```

### Test Structure

- `describe` for classes/methods
- `context` for conditions/scenarios
- `it` for specific behaviors
- `let` for lazy-loaded test data
- `let!` for eager-loaded test data
- `before` for setup (use sparingly)

### Minitest (Alternative)

```ruby
# test/services/user_service_test.rb
class UserServiceTest < Minitest::Test
  def test_create_with_valid_attributes
    result = UserService.new.create(name: "Test")
    assert result.success?
  end
end
```

---

## Blocks, Procs, and Lambdas

### Preference Order

1. **Blocks** - SHOULD be preferred for most cases
2. **Lambdas** - MAY be used when storing/passing callable
3. **Procs** - SHOULD be avoided unless specific behavior needed

```ruby
# Preferred: blocks
users.each { |user| notify(user) }

# Acceptable: lambda for callbacks
validator = ->(value) { value.present? }

# Lambda with arguments
process = ->(x, y) { x + y }

# Avoid: Proc.new unless needed
callback = Proc.new { |x| x * 2 }  # Different arity handling
```

### Block Conversion

```ruby
# Symbol to proc (preferred for simple cases)
names = users.map(&:name)

# Method reference
def process(item)
  item.upcase
end
items.map(&method(:process))
```

---

## Metaprogramming

### Guidelines

- Metaprogramming SHOULD be used sparingly
- All metaprogrammed methods MUST be documented
- Prefer explicit over implicit magic
- `define_method` over `method_missing` when possible

```ruby
# Acceptable: documented DSL
class Validator
  # Defines validation methods for each attribute
  # @param attrs [Array<Symbol>] attribute names to validate
  def self.validates(*attrs)
    attrs.each do |attr|
      define_method("validate_#{attr}") do
        # validation logic
      end
    end
  end
end

# Document what methods are generated
# Generated methods: validate_name, validate_email
validates :name, :email
```

### Avoid

```ruby
# Avoid: unbounded method_missing
def method_missing(name, *args)
  # Hard to debug, no autocomplete
end

# Prefer: explicit delegation or define_method
```

---

## Error Handling

```ruby
# Custom errors SHOULD inherit from StandardError
class ServiceError < StandardError; end
class ValidationError < ServiceError; end

# Rescue specific exceptions
begin
  risky_operation
rescue ValidationError => e
  handle_validation(e)
rescue ServiceError => e
  handle_service_error(e)
rescue StandardError => e
  handle_unexpected(e)
end

# Result objects SHOULD be used for expected failures
Result = Data.define(:success, :value, :error) do
  def success? = success
  def failure? = !success

  def self.success(value) = new(true, value, nil)
  def self.failure(error) = new(false, nil, error)
end
```

---

## File Structure

```
project/
  lib/           # Application code
  spec/          # RSpec tests
  test/          # Minitest tests
  bin/           # Executables
  Gemfile        # Dependencies
  Gemfile.lock   # Locked versions
  .ruby-version  # Ruby version
  .standard.yml  # StandardRB config (optional)
```

---

## Out of Scope

- Rails specifics -> see `rails-workflow`
- Hanami specifics -> see `hanami-workflow`
- Gem publishing -> see `gem-publishing`