FAQ
Answers about rails-ai-context: MCP support, production safety, running without a database, generated files, and how it compares to a hand-written CLAUDE.md.
General
What does this gem do?
It gives AI coding assistants verified, real-time access to your Rails app's structure - schema, models, routes, controllers, views, conventions, and more. Instead of guessing from training data, AI queries your actual app.
Which AI tools are supported?
Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI. Each gets tailored context files and an MCP config it finds when it opens the project; you approve the server once in the tool.
Do I need MCP support in my AI tool?
No. The gem works three ways:
- MCP server - AI calls tools via the protocol (best experience)
- Static files - Generated context files (CLAUDE.md, .cursor/rules/, etc.)
- CLI - Same 35 tools from the terminal, no server needed
Is this safe for production?
The gem is designed for development environments. All tools are read-only. The query tool is disabled in production by default. Sensitive files (.env, *.key, credentials) are blocked.
Does it work without a database?
Yes. The gem gracefully degrades - it parses db/schema.rb as text when no database connection is available.
Installation
Can my AI tool install it for me?
Yes. Copy-paste prompts has one prompt per setup: the usual install, no Gemfile change, CLI only, MCP only, every AI tool for a team, a folder of apps, a private setup with nothing committed, and a try-out that writes nothing. More cover changing the setup, upgrading, fixing and uninstalling. Each runs the install with every answer given as a flag, so it never waits on a question.
How do I uninstall it?
bundle exec rails-ai-context uninstall (or rails-ai-context uninstall standalone), then bundle remove rails-ai-context if the Gemfile lists it. It removes what the gem wrote and keeps what you wrote, such as your own lines in CLAUDE.md. See Uninstalling.
Gemfile or standalone - which should I use?
In-Gemfile is recommended if you own the project. Gives you the install generator, rake tasks, and initializer config.
Standalone is for when you can't modify the Gemfile (client projects, quick exploration, CI).
Can I switch between Gemfile and standalone?
Yes, freely. Both write the same context files and serve the same 35 tools; only the commands those files name follow the install (rails ai:context and rails 'ai:tool[...]' in the Gemfile, rails-ai-context context and rails-ai-context tool ... standalone). Re-run the install or init after switching: it updates the MCP config files and regenerates the context files with the new commands.
My editor opens a folder that holds several apps. Does that work?
Yes. Run rails-ai-context init in that folder. It asks once, gives each app its own .rails-ai-context.yml and context files, and writes one MCP server per app into the folder's configs, rails-ai-context-<app folder>, so your AI tool sees every app and each app's tools are named after it. Start the tool in that folder: the entries name each app relative to it. See init. The Claude Code plugin needs no entries there: started in that folder, its one server serves every app, and each call names its app.
Do I need to commit the generated files?
Yes, commit these:
.mcp.json,.cursor/mcp.json,.vscode/mcp.json,.github/mcp.json,opencode.json,.codex/config.toml- so teammates get the MCP server after approving it once in their AI toolCLAUDE.md,.claude/rules/,.cursor/rules/,.github/copilot-instructions.md,.github/instructions/,AGENTS.md- so AI has contextconfig/initializers/rails_ai_context.rb,.rails-ai-context.yml- so config is shared
Don't commit:
.ai-context.json- auto-added to .gitignore by the install generator
Can I use only the MCP server?
Yes:
rails generate rails_ai_context:install --mcp-only # or: rails-ai-context init --mcp-only
rails generate rails_ai_context:install --tools claude --mcp-only --defaults # asks nothing
The MCP config is written, config.context_files = false is recorded, and no
CLAUDE.md, AGENTS.md, rules file or .ai-context.json is written or
touched. Every tool still answers over MCP and over the CLI. See
CONFIGURATION.md.
MCP & Tools
How do I know which tool to use?
Start with rails_onboard for an app overview, rails_analyze_feature for feature work, and rails_search_code with match_type: "trace" for code investigation. Your AI will learn to pick the right tools.
Can I add my own tools?
Yes. See Custom Tools. Create an MCP::Tool subclass, register it via config.custom_tools, and it appears alongside the 35 built-in tools, in the generated context files' tool counts and lists too.
Can I remove built-in tools?
Yes. Use config.skip_tools:
config.skip_tools = %w[rails_security_scan rails_query]
The server, the CLI and the generated context files then leave them out alike, so no context file tells the AI to call a tool that answers "Unknown tool".
What's the detail parameter?
Every tool that takes detail takes the same three levels: summary (compact), standard (default), full (everything). The generated tool guide lists which tools take it. Start with summary and drill down as needed. This keeps AI context windows lean. Composite tools (rails_get_context, rails_analyze_feature) do not accept detail - they always return their full bundled output.
What are [VERIFIED] and [INFERRED] tags?
Confidence tags from Prism AST parsing:
[VERIFIED]- all arguments are static literals. This is ground truth.[INFERRED]- arguments contain dynamic expressions. Needs runtime verification.
Does the query tool support all databases?
PostgreSQL, MySQL (with MariaDB) and SQLite. Each gets database-specific safety mechanisms (read-only transactions, timeouts). On any other adapter the tool answers with the adapter's name and runs nothing. See Security.
Configuration
What's the difference between :full and :standard preset?
:full(default) - 40 introspectors. Full context for every aspect of your app.:standard- 17 introspectors. Faster, covers the essentials (schema, models, routes, controllers, tests, etc.).
What's :compact vs :full context mode?
:compact(default) - the root file stays within 150 non-blank lines (claude_max_lines) and 12,000 bytes, and names the 10 most connected models. The tools answer the rest.:full- no line cap. All introspection data, within 24,000 bytes, cut from the bottom when it does not fit.
Can I use YAML config with the Gemfile approach?
Yes. The file is applied first and a configure block wins only the keys it assigns, so a key the initializer never touches keeps the YAML value. See Precedence.
What's generate_root_files?
When true (default), generates the root files the chosen AI tools read: AGENTS.md, CLAUDE.md and copilot-instructions.md. Set to false to only generate split rules (.claude/rules/, .cursor/rules/, etc.), which then carry the project overview and the tools guide too. .ai-context.json is written either way.
Context Files
What files get generated?
Depends on your ai_tools config. For all tools:
| AI Tool | Files |
|---|---|
| Claude | CLAUDE.md, .claude/rules/*.md |
| Cursor | AGENTS.md, .cursor/rules/*.mdc |
| Copilot | .github/copilot-instructions.md, .github/instructions/*.instructions.md |
| OpenCode | AGENTS.md, app/models/AGENTS.md, app/controllers/AGENTS.md |
| Codex | Shares AGENTS.md and OpenCode rules |
The root content is written once, into a file every chosen tool reads. AGENTS.md carries it when Cursor, OpenCode or Codex is chosen, and CLAUDE.md then holds only @AGENTS.md, which Claude Code expands at launch. Copilot keeps an identical copy in .github/copilot-instructions.md. .cursorrules is no longer written, and a run with root files on takes out the block an earlier release wrote there and keeps your own lines. See Generated Files.
How do I regenerate context files?
rails ai:context # All formats
rails ai:context:claude # Claude only
Do context files update automatically?
Only if you run watch mode:
rails ai:watch
Otherwise, regenerate manually after significant changes.
Can I add my own content to CLAUDE.md?
Yes. Add content outside the <!-- BEGIN/END rails-ai-context --> markers. The gem preserves content outside these markers during regeneration.
Performance
Is introspection slow?
Introspection results are cached with TTL (default: 60s) and fingerprint invalidation. The first call is slower; subsequent calls use cache until a watched file changes. Prism AST parsing uses a single-pass Dispatcher - all 8 listeners run in one tree walk.
Does this affect my app's performance?
No, as long as the gem sits in the Gemfile's :development group, where bundle add rails-ai-context --group development puts it: Bundler then never loads it in production. Where the gem is loaded in production, it refuses two things there by default: rails_query, and MCP over HTTP from inside the app (the mounted engine and auto_mount). Tools execute on demand (not continuously). The MCP server is a separate process (stdio), or an HTTP endpoint that exists only when you mount it or set auto_mount.
How does live reload work?
The listen gem watches app/, config/, db/, lib/, rakelib/, test/, spec/, the pack and engine folders, and the folders outside those that hold a file a reader reads (bin/, .github/workflows/, .circleci/, .buildkite/), and when files change, MCP clients are notified. Debounce interval: 1.5s (configurable). A file at the app root (Gemfile, Dockerfile, .gitlab-ci.yml), in a frontend root, or in a folder outside the app sends no notice of its own; the next tool call still sees the edit.
Answers do not depend on it. Every tool call first checks those files, with listen or without it (a new Rails 8 app does not bundle it), and when one changed it reloads the app's code and drops the caches, so a call sees an edit made a moment before it. The check costs about a millisecond on a small app and about 30 ms at 10,000 files.
Under RAILS_ENV=test, or in production with eager loading, the app does not reload code, so what reflection reads (associations, enums) stays as it was at boot; once app code changes, every answer ends with a note naming the files, and a restart brings it up to date.
Security
Can tools modify my database?
No. The query tool uses SET TRANSACTION READ ONLY + rollback on PostgreSQL and MySQL, and a read-only connection on SQLite. Even if SQL validation were bypassed, the database layer prevents writes.
Can tools read my .env or credentials?
No. Sensitive files (.env*, *.key, *.pem, credentials.yml.enc) are blocked by default. The pattern list is configurable.
Is the Anti-Hallucination Protocol necessary?
It's enabled by default and targets real AI failure modes. If you prefer your own prompting rules, disable it:
config.anti_hallucination_rules = false
How does this compare to...
...a hand-written CLAUDE.md?
A manual CLAUDE.md goes stale the moment someone adds a column or changes a route. rails-ai-context reads your app live - schema, models, routes, controllers are always current. You can still add your own rules alongside the generated content. See Recipes: Migrating.
...cursor-rules repos / awesome-cursorrules?
Community cursor rules are generic Rails patterns. rails-ai-context generates rules from your app - your actual schema, your associations, your conventions. Generic rules say "Rails uses before_action"; this gem tells AI which specific filters your ApplicationController applies.
...pasting schema.rb into the prompt?
Pasting works once, then goes stale. It also burns context window on tables AI doesn't need. The get_schema tool returns only the requested table, on demand, always current.
...Copilot Workspace / Cursor Composer / Windsurf?
Those are AI coding interfaces. This gem is a data layer that makes any of them better. It provides the ground truth they're missing. Works with Claude Code, Cursor, Copilot, OpenCode, and Codex simultaneously.
Troubleshooting
My AI tool doesn't see the MCP server
Each AI tool holds a project's MCP server back until you take a step in the tool itself: approve it in Claude Code, turn it on in Cursor, trust the folder in VS Code and Codex CLI, restart OpenCode. The install's summary names the step for each tool you picked. If it is done and the tools still don't appear, run rails ai:doctor - it checks each configured tool's MCP config file, and whether the command it holds can start. See Troubleshooting for detailed steps.
Tools return empty results
Check that your Rails app boots (rails runner "puts 'ok'") and that schema/models exist. Run rails ai:doctor.
Context files are too large
Use compact mode (default), and lower claude_max_lines for a shorter root file:
config.context_mode = :compact
config.claude_max_lines = 100
Every file already has a byte budget (Generated Files). Turning root files off does not shrink what Claude Code and Copilot load: the overview and the whole tools guide move into rules files they load in every session.