Recipes

Real-world workflows that show how AI + ground truth changes everything.

Quickstart · Tools Reference · Custom Tools · FAQ


Table of Contents


Adding a column to an existing table

TipThis is the #1 place AI goes wrong. Without schema access, it guesses column names and types.

Ask your AI: "Add a subscription_tier column to the users table"

What happens:

→ rails_get_schema(table: "users")
Example output
## Table: users

**Models:** User
**Primary key:** id

| Column | Type | Null | Default |
|--------|------|------|---------|
| id | integer | **NO** |  |
| email | string | **NO** |  |
| subscription_status | string | yes | free |
| created_at | datetime | **NO** |  |

### Indexes
- `index_users_on_email` on (email) (unique)

AI sees subscription_status already exists - asks before proceeding instead of creating a duplicate column.

→ rails_get_model_details(model: "User")
→ rails_migration_advisor(action: "add_column", table: "users", column: "subscription_tier", type: "string")

Without ground truth: AI writes a migration blindly, possibly duplicating a column or missing an index.


Fixing a broken controller action

Ask your AI: "The create action in PostsController is failing"

rails_get_controllers(controller: "PostsController", action: "create")
# → Source code + inherited before_action filters + strong params + render paths

rails_get_routes(controller: "posts")
# → Code-ready helpers: post_path(@record), new_post_path

rails_get_schema(table: "posts")
# → Actual column names, types, constraints

rails_diagnose(error: "ActiveRecord::RecordInvalid", file: "app/controllers/posts_controller.rb")
# → Classification + context + recent git log + log correlation

AI sees the full picture: the parent controller's authenticate_user! filter, the actual strong params whitelist, and the real column names. No guessing.


Building a new feature from scratch

Ask your AI: "Build a notifications system"

→ rails_analyze_feature(feature: "notifications")
Example output
# Feature Analysis: notifications

## Models (1)

### Notification
**Table:** `notifications`
**Columns:** user_id:bigint, title:string, read_at:datetime
**Associations:** belongs_to :user

## Controllers (1)

### NotificationsController
- **Actions:** index, mark_read
- **Filters:** before authenticate_user!

## Routes (2)
- `GET` `/notifications` → notifications#index `notifications_path`
- `POST` `/notifications/:id/mark_read` → notifications#mark_read `mark_read_notification_path(@record)`

## Jobs (1)
- `app/jobs/notification_broadcast_job.rb` (queue: default, retry_on StandardError, attempts: 3, perform(notification_id))

AI sees what already exists before building anything. Then:

→ rails_get_config(section: "conventions")   # Your app's own patterns
→ rails_get_config(section: "gems")          # Sees ActionMailer, Sidekiq, etc.
→ rails_get_schema()                          # Picks the right foreign keys and types

AI scaffolds the feature matching your app's actual patterns - not generic Rails conventions from training data.


Tracing a method across the codebase

Tipsearch_code with match_type: "trace" is the single most powerful tool. Use it first when investigating anything.

Ask your AI: "Where is publishable? used?"

→ rails_search_code(pattern: "publishable?", match_type: "trace")
Example output
# Trace: `publishable?`

## Definition
**app/models/post.rb:45** in `class Post`
```ruby
  def publishable?
    title.present? && body.present? && approved?
  end
```

## Calls internally
- `title`
- `body`
- `approved?`

## Called from (3 sites)
### app/controllers/admin/posts_controller.rb (Controller)
  8: render :draft unless @post.publishable?
### app/controllers/posts_controller.rb (Controller)
  12: redirect_to @post unless @post.publishable?
### app/views/posts/show.html.erb (View)
  8: <% if @post.publishable? %>

## Tested by (1 reference)
- `spec/models/post_spec.rb` (1 reference)

One call. Definition + source + every caller grouped by file and labelled by type + tests. Replaces 4-5 sequential file reads.


Understanding someone else's code

Ask your AI: "Walk me through this app"

rails_onboard(detail: "full")
# → Narrative walkthrough: stack, models, key patterns, conventions, deployment

rails_dependency_graph(format: "mermaid")
# → Visual model relationship graph

rails_get_config(section: "gems")
# → Every notable gem with version, category, and config location

Writing tests that match your patterns

Ask your AI: "Write tests for the Order model"

rails_get_test_info(model: "Order")
# → Existing test files, fixtures, factory definitions

rails_get_model_details(model: "Order")
# → Associations, validations, scopes, callbacks to test

rails_generate_test(file: "app/models/order.rb")
# → Test scaffolding using YOUR framework (RSpec/Minitest) and YOUR patterns (fixtures/factories)

AI generates tests that actually run, using your test helper setup, your factory definitions, your assertion style.


Debugging a view rendering issue

Ask your AI: "The dashboard view is broken"

rails_get_view(path: "dashboard/index.html.erb")
# → Template source with ivars, Turbo frames, Stimulus controllers, partial locals

rails_get_partial_interface(partial: "dashboard/stats_card")
# → Required locals and methods called on them

rails_get_stimulus(controller: "chart")
# → Correct data-attributes with dashes (not underscores)

Reviewing a PR

Ask your AI: "Review the changes in this branch"

rails_review_changes(ref: "HEAD~3")
# → Per-file context + structural warnings

rails_validate(files: ["app/controllers/users_controller.rb", "app/models/user.rb"], level: "rails")
# → Syntax + semantic + Brakeman scan

rails_performance_check()
# → N+1 risks, missing indexes on changed models

Safe database queries

Ask your AI: "How many users signed up this month?"

rails_query(sql: "SELECT COUNT(*) FROM users WHERE created_at > '2026-04-01'")
# → Runs with: regex pre-filter, SET TRANSACTION READ ONLY, 5s timeout, row limit, column redaction
# → Password columns automatically redacted

Ask your AI: "Explain why this query is slow"

rails_query(sql: "SELECT * FROM orders JOIN users ON ...", explain: true)
# → Query plan with index usage, full table scan warnings

Working with concerns

Ask your AI: "What does the Searchable concern do?"

rails_get_concern(name: "Searchable")
# → Methods (including class_methods block), source code, which models include it

rails_search_code(pattern: "include Searchable", match_type: "any")
# → Every file that includes this concern

Checking component patterns

Ask your AI: "What components do we have?"

rails_get_component_catalog(detail: "standard")
# → ViewComponent/Phlex: props, slots, previews, sidecar assets, usage examples

rails_get_config(section: "frontend")
# → React/Vue/Svelte, Hotwire, TypeScript, Vite/Webpacker

Diagnosing production issues

Ask your AI: "Check the app health"

rails_runtime_info(detail: "full")
# → DB pool stats, table sizes, pending migrations, cache stats, queue depth

rails_read_logs(level: "ERROR", lines: 100)
# → Recent errors with sensitive data redacted

rails_security_scan()
# → Brakeman: SQL injection, XSS, mass assignment vulnerabilities

Session context across multiple questions

When AI makes multiple tool calls in a conversation, rails_session_context tracks what's been queried:

# First question: "Tell me about users"
rails_get_schema(table: "users")
rails_get_model_details(model: "User")

# Follow-up: "What context do I have so far?"
rails_session_context(action: "status")
# → Lists all prior tool calls with params and when each ran

This prevents redundant queries and helps AI maintain conversation context.


Migrating from manual AI context

If you've been maintaining a hand-written CLAUDE.md, AGENTS.md, .cursorrules, or similar:

Step 1: Install

rails generate rails_ai_context:install

Step 2: Move your custom content

The gem wraps its generated content in section markers:

<!-- BEGIN rails-ai-context -->
... generated content ...
<!-- END rails-ai-context -->

Add your custom rules outside these markers - they're preserved on regeneration. A hand-written app/models/AGENTS.md or app/controllers/AGENTS.md is kept the same way: your text stays, and the gem's listing goes between the markers above it. The gem no longer writes .cursorrules, so a hand-written one stays as it is; Cursor reads the generated content from AGENTS.md.

Step 3: Remove manual maintenance

You no longer need to manually update:

Your custom rules (coding style, PR conventions, team preferences) stay. The gem handles the facts.


Tips

  1. Start with detail:"summary" - get the lay of the land before drilling down
  2. Use analyze_feature first - it's the best starting point for any feature work
  3. search_code with match_type:"trace" - the single most powerful tool for understanding code flow
  4. Don't read files directly - let tools give you the structured, verified data
  5. Re-query after edits - earlier tool output may be stale after you make changes

← Tools Reference · Custom Tools →

Back to Home