Rails Pattern Finder

name: rails-pattern-finder description: Finds Rails code patterns and best practices using Ref (primary), Grep, and reference patterns with WebFetch fallback version: 1.2.0 author: Rails Workflow Team tags: [rails, patterns, best-practices, code-examples, ref] priority: 3

Purpose

Searches the current Rails codebase for existing patterns and provides best-practice code examples. Helps agents write code consistent with project conventions.

Replaces: Manual codebase exploration and pattern recognition

Usage

Auto-invoked when agents need code examples:

code

Agent: "How is authentication implemented in this project?"
*invokes rails-pattern-finder pattern="authentication"*

Manual invocation:

code

@rails-pattern-finder pattern="service_objects"
@rails-pattern-finder pattern="api_serialization"
@rails-pattern-finder pattern="background_jobs"

Supported Patterns

See reference.md for complete pattern list. Common patterns:

Architectural Patterns

•service_objects - Service layer implementation
•form_objects - Form object pattern
•query_objects - Complex query encapsulation
•decorators - Decorator/presenter pattern
•policies - Authorization policies (Pundit)

API Patterns

•api_versioning - API version management
•api_serialization - JSON response formatting
•api_authentication - Token/JWT authentication
•api_error_handling - Error response patterns

Database Patterns

•scopes - Named scope usage
•concerns - Model concern organization
•polymorphic_associations - Polymorphic pattern
•sti - Single Table Inheritance
•database_views - Database view usage

Testing Patterns

•factory_usage - FactoryBot patterns
•request_specs - API request testing
•system_specs - System/feature testing
•shared_examples - RSpec shared examples

Search Process

Step 1: Pattern Lookup

code

Input: pattern="service_objects"
Lookup: reference.md → search_paths, file_patterns, code_patterns

Step 2: Codebase Search

code

Tool: Grep
Pattern: "class.*Service$"
Glob: "app/services/**/*.rb"
Output: List of matching files

Step 3: Example Extraction

code

Tool: Read
Files: [top 3 matches by relevance]
Extract: Class structure, method signatures, usage patterns

Step 4: Response Formatting

ruby

## Pattern: Service Objects

### Found in Project (3 examples):

**1. UserRegistrationService** (app/services/user_registration_service.rb)
```ruby
class UserRegistrationService
  def initialize(params)
    @params = params
  end

  def call
    user = User.create!(@params)
    send_welcome_email(user)
    user
  end

  private

  def send_welcome_email(user)
    UserMailer.welcome(user).deliver_later
  end
end

2. PaymentProcessingService (app/services/payment_processing_service.rb) [Example code...]

Best Practice from Rails Community:

[Fetch from reference.md or WebSearch]

Source: Project codebase + Rails best practices

code


## Reference Lookup

**Pattern → Search Strategy mapping** in `reference.md`:

```yaml
service_objects:
  title: "Service Objects"
  search_paths: ["app/services/**/*.rb"]
  file_patterns: ["*_service.rb"]
  code_patterns:
    - "class \\w+Service"
    - "def call"
  best_practice_url: "https://example.com/rails-service-objects"
  keywords: [service, business logic, call method]

api_serialization:
  title: "API Serialization"
  search_paths: ["app/serializers/**/*.rb", "app/blueprints/**/*.rb"]
  file_patterns: ["*_serializer.rb", "*_blueprint.rb"]
  code_patterns:
    - "class \\w+Serializer"
    - "ActiveModel::Serializer"
    - "Blueprinter::Base"
  keywords: [json, serializer, blueprint, jbuilder]

Output Format

Pattern Found in Project

markdown

## Pattern: [Pattern Name]

### Found in Project ([N] examples):

**File**: [path/to/file.rb]
**Purpose**: [What this implementation does]

```ruby
[Code example from project]

Key characteristics:

•[Feature 1]
•[Feature 2]

Usage in project: [How this pattern is used - grep for usage examples]

code


### Pattern Not Found
```markdown
## Pattern: [Pattern Name] - Not found in project

**Searched**:
- app/services/**/*.rb
- app/lib/**/*.rb

**Best Practice Implementation**:

```ruby
[Example from reference.md or external source]

To implement in this project:

•Create: app/services/[name]_service.rb
•Follow structure above
•Test in: spec/services/[name]_service_spec.rb

Similar patterns in project:

•[Alternative pattern found]

code


### Multiple Variants Found
```markdown
## Pattern: [Pattern Name] - Multiple variants found

This project uses [N] different approaches:

### Variant 1: [Approach Name] ([N] files)
[Example code...]

### Variant 2: [Approach Name] ([N] files)
[Example code...]

**Recommendation**: [Which variant to use for consistency]

Implementation Details

Tools used (in order of preference):

•Read - Load reference.md pattern definitions
•context7_fetch (primary) - Fetch curated patterns via Context7 MCP
•ref_search_documentation (secondary) - Search Rails pattern docs via Ref MCP
•ref_read_url (secondary) - Fetch specific pattern guides via Ref MCP
•tavily_search (tertiary) - Optimized search via Tavily MCP
•Grep - Search codebase for pattern matches
•Read - Extract code examples from matching files
•WebFetch (fallback) - Fetch pattern docs if MCPs not available
•WebSearch (optional) - Fetch external best practices
•Glob - Find files matching pattern

Optional dependencies:

•context7-mcp: Fastest pattern documentation
•ref-tools-mcp: Token-efficient pattern search
•tavily-mcp: Optimized search for LLMs
•If neither installed: Falls back to WebFetch and local searches (still works!)

Search strategies:

File-based search:

bash

# Find files matching naming convention
glob: "app/services/*_service.rb"

Content-based search:

bash

# Find class definitions
grep: "class \\w+Service$"
path: "app/services"

Usage search:

bash

# Find where pattern is used
grep: "UserRegistrationService\\.new"
path: "app/controllers"

Relevance ranking:

•Most recently modified files (likely current patterns)
•Files with most references (commonly used)
•Files with comprehensive examples (best for learning)

Error Handling

Pattern not found:

markdown

⚠️ Pattern "[pattern]" not found in project

**Searched**:
- [paths searched]

**Options**:
1. View best practice example (from reference.md)
2. Search for similar pattern: [suggestions]
3. Implement from scratch using best practices

Invalid pattern name:

markdown

❌ Unknown pattern: "[pattern]"

Available patterns:
- service_objects
- form_objects
- query_objects
[...from reference.md...]

Try: @rails-pattern-finder pattern="[one of above]"

Ambiguous results:

markdown

⚠️ Multiple pattern variants found for "[pattern]"

Please review all variants and choose one for consistency.

[List all variants found...]

Integration

Auto-invoked by:

•All 7 Rails agents when generating new code
•@rails-architect for architectural decisions
•Agents adapting to project conventions

Workflow:

•Agent needs to generate code (e.g., new service)
•Invokes @rails-pattern-finder pattern="service_objects"
•Receives project-specific examples
•Generates code matching project style

Special Features

Pattern comparison

code

@rails-pattern-finder pattern="service_objects" compare_with="form_objects"
→ Shows differences and use cases for each

Project convention detection

code

@rails-pattern-finder detect_conventions
→ Analyzes codebase and reports common patterns

Anti-pattern detection

code

@rails-pattern-finder anti_patterns
→ Searches for common Rails anti-patterns in codebase

Test pattern search

code

@rails-pattern-finder pattern="service_objects" include_tests=true
→ Shows both implementation and test examples

Pattern Categories

Creation Patterns

•service_objects - Business logic encapsulation
•form_objects - Form handling
•query_objects - Query encapsulation
•builder_pattern - Object construction

Structural Patterns

•concerns - Module organization
•decorators - Presentation logic
•adapters - External API integration
•repositories - Data access layer

Behavioral Patterns

•observers - Event handling
•state_machines - State management
•strategies - Algorithm selection
•commands - Action encapsulation

Rails-Specific

•sti - Single Table Inheritance
•polymorphic_associations - Flexible relationships
•custom_validators - Validation logic
•background_jobs - Async processing

Testing

Test cases:

•Pattern exists in project → Returns project examples
•Pattern doesn't exist → Returns best practice example
•Multiple variants → Lists all with recommendation
•Invalid pattern → Error with suggestions
•Empty project → All patterns return best practices

Notes

•This skill searches current project codebase, not external repos
•Pattern definitions in reference.md include search strategies
•Results prioritize recent, commonly-used code
•Helps maintain consistency across large teams
•Adapts to project-specific conventions automatically
•Use with @rails-docs-search (theory) and @rails-api-lookup (APIs)