What to put in an AGENTS.md for Rails

Rails conventions are well known to agents, so spend the file on where you depart from them, and on the commands with your flags. Since 8.1, bin/ci runs what CI runs; if you have it, that is the one command to name.

Which commands should it list?

bin/cithe steps in config/ci.rb (Rails 8.1+)
bin/rails test test/models/user_test.rb:27one file, or one test by line
bin/rails test:systemsystem tests, which bin/rails test skips
bin/rubocop -a && bin/brakemanlint with autocorrect, then the security scan

Write them as your repo runs them, with its package manager and flags, plus how to run one test.

What layout should it explain?

Where code lives outside app/: service objects, lib/, engines or packs.
Which test framework you use: Minitest under test/, or RSpec under spec/.
Background jobs and their queue, if a change can enqueue work.

What do agents get wrong?

db/schema.rb is regenerated by bin/rails db:migrate; on a conflict, rerun it rather than editing.
Never commit config/master.key; edit secrets with bin/rails credentials:edit.
Use bin/rails generate for new models and migrations, so the files land where Rails expects.

From the official docs: guides.rubyonrails.org/testing.html · guides.rubyonrails.org/command_line.html · guides.rubyonrails.org/active_record_migrations.html · guides.rubyonrails.org/security.html · guides.rubyonrails.org/8_1_release_notes.html . The rest of the file is the same for any project: what goes in an AGENTS.md.

Rails repos with an AGENTS.md or CLAUDE.md (4)

Built on Rails; 4 pass the AGENTS.md check in full. rails/rails has one too, for contributors to Rails itself.

Rails repos with an AGENTS.md or CLAUDE.md
Repo	File	Length	Stars	Language	Score
discourse/discourse	AGENTS.md	6,245 chars	48k ★	Ruby	89.8
forem/forem	AGENTS.md	9,952 chars	22.8k ★	Ruby	81.7
antiwork/gumroad	AGENTS.md	978 chars	10.1k ★	Ruby	84.6
gitlab-org/gitlab	AGENTS.md	5,570 chars	6.2k ★	Ruby	80.9

More examples: Next.js · FastAPI · Django · all examples