Rails official documentation lookup
Trained knowledge about Rails APIs can be outdated, mixed across versions, or simply wrong on
specifics (option names, defaults, deprecations, callback ordering, etc.). Before answering a
Rails-specific question or relying on a Rails API's exact behavior, check the official docs
rather than guessing — pinned to the version this project actually runs, not whatever version
training data assumed.
Determine the version first
Don't assume the Rails version from memory or from prose in CLAUDE.md — that can go stale the
moment someone bumps the gem without updating the docs. Check the source of truth instead:
grep -m1 '^ rails (' Gemfile.lock
That gives you the exact installed version (e.g. rails (8.0.2.1)). Use its <major>.<minor>
for the pinned doc URLs below.
Sources
- Guides (concepts, how-tos, conventions): https://guides.rubyonrails.org
- Version-pinned:
https://guides.rubyonrails.org/v<major>.<minor>/<guide-name>.html
- API reference (exact method signatures, options, source): https://api.rubyonrails.org
- Version-pinned:
https://api.rubyonrails.org/v<major>.<minor>/
If a pinned URL 404s (e.g. docs for a brand-new version aren't published at that path yet), fall
back to the unpinned root and flag to the user that you're reading possibly-newer docs than the
installed version.
When to look things up
Use WebFetch against the sources above when:
- The question is about a specific Rails API's options, defaults, or behavior (e.g. "does
has_many support :strict_loading?", "what does config.active_record.encryption need?").
- You're unsure whether something changed between Rails versions (deprecated, renamed, new
behavior in the installed version).
- You're about to write code that depends on exact method signatures, callback ordering, or
routing/DSL syntax you're not fully certain of.
- The user asks a "how do I do X in Rails" question that isn't already answered by this project's
own conventions in
CLAUDE.md.
Skip the lookup for things you can verify faster by reading this codebase directly (e.g. "how does
this app handle streaming?" — that's answered by app/services/ai_backend/, not the guides), or for
very basic Ruby/Rails knowledge you're confident hasn't changed across versions.
How to look things up
- Determine the installed Rails version from
Gemfile.lock (see above).
- Identify the right guide or API page (e.g. Active Record Associations, Action Mailer Basics).
- Fetch it with
WebFetch, using the version-pinned URL.
- If the guide doesn't have the exact method signature, cross-check
api.rubyonrails.org for the
precise method/class documentation.
- Prefer the official source over Stack Overflow, blog posts, or other secondary sources when they
conflict.
Applying this project's conventions
Official Rails docs describe what's possible; they don't override this project's own patterns.
After confirming Rails behavior, still follow CLAUDE.md's conventions — e.g. provider logic goes
in app/services/ai_backend/, soft deletion via deleted_at + not_deleted scopes, feature flags
via Feature.<name>?/Setting.<name>, and don't hard-code model lists (models.yml instead).