What should a CLAUDE.md for Rails include?
A CLAUDE.md for Rails should list the bin/ commands Claude Code needs to set up, run, migrate, test, lint and security-check the app, give a short map of your folders, and state your rules for migrations, strong parameters, credentials and tests. Keep it under 200 lines, as Anthropic's memory docs recommend, and write down the gotchas Claude cannot see from the code.
Rails already gives Claude a lot: convention over configuration, predictable file names and generators. What it does not give is your choices. Does the app use Minitest or RSpec? Is bin/ci the done-check? Are committed migrations ever edited? Which commands are safe to run against which database? Those are the lines that change what Claude does.
The template below targets Rails 8.1, the current version on Rails Guides, whose getting started guide asks for Ruby 3.2 or newer. Every command is one that a new Rails 8.1 app ships with. PostgreSQL, Minitest and rules like thin controllers and model scopes are common choices, not requirements, so swap them for whatever your team uses. For the CLAUDE.md format in general, see the CLAUDE.md guide.
The Rails CLAUDE.md template
Save this as CLAUDE.md at the root of your app. Replace the angle-bracket placeholders and remove lines that do not apply.
# <App name>
<One sentence: what this app does and who uses it.>
Stack: Rails 8.1, Ruby (see .ruby-version), <PostgreSQL>, Hotwire, Minitest.
## Commands
- Setup: `bin/setup`
- Dev server: `bin/rails server` (http://localhost:3000)
- Console without saving changes: `bin/rails console --sandbox`
- Routes: `bin/rails routes`
- New migration: `bin/rails generate migration AddStatusToOrders status:string`
- Migrate: `bin/rails db:migrate`. Undo the last one: `bin/rails db:rollback`
- Tests: `bin/rails test`. One file: `bin/rails test test/models/order_test.rb`
- One test: add the line number, `bin/rails test test/models/order_test.rb:27`
- System tests (skipped by `bin/rails test`): `bin/rails test:system`. All: `bin/rails test:all`
- Lint: `bin/rubocop`. Autocorrect: `bin/rubocop -a`
- Security scan: `bin/brakeman`
- Local CI, every step in config/ci.rb: `bin/ci`
- Done means: `bin/ci` passes, or at least rubocop, brakeman and the touched tests
## Project structure
- `app/`: models, controllers, views, helpers, mailers, jobs
- `config/routes.rb`: every route. `config/credentials.yml.enc`: encrypted secrets
- `db/migrate/`: migrations. `db/schema.rb`: regenerated by migrations, never hand-edited
- `lib/tasks/`: custom rake tasks (do not edit the Rakefile)
- `test/`: models, controllers, integration, system, fixtures
- File names match the constants they define:
`app/controllers/admin/payments_controller.rb` defines `Admin::PaymentsController`
## Conventions
- Generate files with `bin/rails generate` so names, tests and routes line up
- Never `require` files under `app/`; Rails autoloads them
- Controllers stay thin and RESTful: `resources` routes and the standard actions first
- Permit params with `params.expect`, for example `params.expect(order: [:status, :note])`
- Queries live in model scopes, not in views or helpers
- Slow or external work goes in a job under `app/jobs/`
## Migrations
- Never edit a migration that is committed; write a new one
- A fresh, uncommitted migration may be rolled back, edited and migrated again
- Make every migration reversible; irreversible changes need `up` and `down`
- Commit db/schema.rb together with the migration
## Testing
- Minitest, not RSpec. Fixtures live in `test/fixtures/*.yml`, one file per model
- Models: validations and scopes. Integration tests: request flows. System tests: critical UI paths
- Every bug fix comes with a test that failed before the fix
## Secrets and security
- Secrets go in credentials: `bin/rails credentials:edit`, read with `Rails.application.credentials`
- Never commit `config/master.key` or print credentials
- Run `bin/brakeman` after changing controllers, params or views
- Patch a vulnerable gem with `bundle update --conservative <gem>`
## Do not
- Do not add a gem without asking
- Do not run migrations or console commands against production
- Do not disable RuboCop cops inline without a comment saying why
## Gotchas
- `bin/rails test` does not run system tests; run `bin/rails test:system` when UI changes
- On a db/schema.rb merge conflict, run `bin/rails db:migrate` to regenerate it
- <Your app's own surprises: Solid Queue workers, seeds, external sandboxes>
What does each part of the template do?
Header and stack line. Naming Rails 8.1 and your test framework stops Claude from suggesting APIs from older versions or writing RSpec specs in a Minitest app. Pointing at .ruby-version keeps the file correct when you upgrade Ruby; the getting started guide notes that file holds the app's default Ruby version.
Commands. All of these come from Rails Guides. The getting started guide covers bin/rails server, bin/rails db:migrate, generators, bin/rails test, bin/rubocop -a and bin/brakeman. The command line guide explains that bin/rails console --sandbox wraps all database operations in a transaction that rolls back when you exit, which makes it a safe console for an agent. The :27 line-number syntax and bin/rails test:system come from the testing guide.
bin/ci as the done-check. The Rails 8.1 release notes introduce a default CI declaration in config/ci.rb, run by bin/ci, with steps for setup, RuboCop, a gem audit, an importmap audit, Brakeman and the tests. Giving Claude one command that runs the same checks your CI runs is the clearest possible definition of done.
Project structure. The folder descriptions follow the directory table in the getting started guide, including the advice to add tasks in lib/tasks rather than changing the Rakefile. The file-name rule comes from the autoloading guide: file names have to match the constants they define, and you do not need (and should not write) a require call for autoloadable code.
Conventions. params.expect is the strong parameters API shown in the Action Controller overview. Putting a one-line example in CLAUDE.md shows Claude the exact pattern your app uses, so it does not mix styles across controllers. A resources route creates seven routes by default, per the routing guide, which is why "standard actions first" keeps controllers predictable.
Migrations. The migrations guide says editing migrations already committed to source control "is not a good idea" and that you should write a new migration instead, while editing a fresh, uncommitted one is common. It also strongly recommends checking the schema file into source control, and says to resolve schema merge conflicts by running bin/rails db:migrate.
Secrets and security. The security guide explains that credentials live in the encrypted config/credentials.yml.enc, edited with bin/rails credentials:edit, and that you should never commit your master key. It also suggests bundle update --conservative for vulnerable dependencies.
Which agent mistakes does the template prevent?
Rails is convention-heavy, so most agent mistakes come from applying a convention from the wrong version or the wrong team. Each section of the template targets one:
| Without the rule | Line in the template that prevents it |
|---|---|
| Claude edits an old migration that already ran in production | "Never edit a migration that is committed; write a new one" |
A UI change passes bin/rails test but breaks a system test |
"System tests (skipped by bin/rails test)" and the gotcha line |
| A new class sits in a file whose name does not match, so autoloading fails | "File names match the constants they define" |
| An API key is pasted into an initializer | "Secrets go in credentials" |
| RSpec files appear in a Minitest app | "Minitest, not RSpec" in the stack line and testing section |
| Claude declares a task done without running the checks CI runs | "Done means: bin/ci passes" |
When you add rules later, name the mistake first and then write the shortest line that prevents it. A line that prevents nothing is context Claude has to read every session for no benefit.
How do you adapt it to your project?
- RSpec: replace the testing section and test commands with your
bundle exec rspecsetup and say where factories live. - Older Rails: if you are not on 8.1 yet, remove the
bin/cilines and use your CI script. On older versions, check that eachbin/command exists before you list it. - API-only app: drop views and system tests, and add your serializer and authentication conventions.
- Engines or a big monolith: put a short CLAUDE.md in each engine folder. Claude Code loads CLAUDE.md files in subdirectories on demand, when it works on files there.
- Rules for one area: add
.claude/rules/views.mdwithpaths: ["app/views/**/*"]in the frontmatter, so view rules load only when Claude edits a view.
After saving, run /context in a Claude Code session to check the file is listed under Memory files. In an existing app without a CLAUDE.md, /init generates a draft from your code that you can merge with these sections.
How do you share it with other agents through AGENTS.md?
If your team also uses Codex, Cursor or Copilot, move the template's content into AGENTS.md and keep CLAUDE.md short. Claude Code reads AGENTS.md by itself only when the project has no CLAUDE.md or CLAUDE.local.md, and only from v2.1.277, so an import makes both work together:
@AGENTS.md
## Claude Code only
- Use plan mode before changing billing models or any migration
- Run `/doctor prompt-audit` after editing AGENTS.md or this file
Claude reads the imported file first, then the lines below it. See the AGENTS.md guide for which tools read the file, and Claude Code memory for how root and subfolder files are combined.
How do you keep a Rails CLAUDE.md useful?
Add a line when Claude makes the same mistake twice, and delete lines it follows without being told. When you upgrade Rails, update the commands and the version first. /doctor prompt-audit (Claude Code v2.1.283 or later) reports outdated or conflicting instructions with proposed edits, and changes nothing until you ask. CLAUDE.md is guidance, not enforcement, so for a hard rule such as never running console commands against production, use a hook. The Claude Code best practices page has more on working this way.
If you set up Rails apps often, keep the template where you can reuse it. Kipt stores prompts and Agent Skills as Markdown in a private GitHub repo you own, so you could save this as a prompt with blanks like {{database:PostgreSQL}} and fill them for each app. Templates for other stacks: Next.js, Django and FastAPI.