rails_ai_agents
AGENTS.md665 starsChanged 6 months agoMITView on GitHub
Follow TDD: Red -> Green -> Refactor: 1. RED: Write a failing test describing desired behavior 2. GREEN: Write minimal code to pass the test 3. REFACTOR: Improve code structure while keeping tests green See @docs/rails-development-principles.md for the complete development principles guide.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository43 other files it gives its agents.
- .claude_37signals/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- accessibility-reviewSkill
- action-cable-patternsSkill
- active-storage-setupSkill
- api-versioningSkill
- authentication-flowSkill
- behavioral-guidelinesSkill
- caching-strategiesSkill
- code-reviewSkill
- codex-reviewSkill
- dependabot-reviewSkill
- extraction-timingSkill
- friction-reviewSkill
- i18n-patternsSkill
- mutation-testingSkill
- performance-optimizationSkill
- postgres-patternsSkill
- rails-architectureSkill
- rails-concernSkill
- security-auditSkill
- solid-queue-setupSkill
- accessibility-reviewSkill
- action-cable-patternsSkill
- active-storage-setupSkill
- api-versioningSkill
- authentication-flowSkill
- behavioral-guidelinesSkill
- caching-strategiesSkill
- code-reviewSkill
- codex-reviewSkill
- dependabot-reviewSkill
- extraction-timingSkill
- friction-reviewSkill
- i18n-patternsSkill
- mutation-testingSkill
- performance-optimizationSkill
- postgres-patternsSkill
- rails-architectureSkill
- rails-concernSkill
- security-auditSkill
- solid-queue-setupSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 55
Follow TDD: Red -> Green -> Refactor:
- Distinctive: line 56
RED: Write a failing test describing desired behavior
- Distinctive: line 57
GREEN: Write minimal code to pass the test
- Very specific: line 63
Callbacks: Only for data normalization (before_validation, before_save).
- Distinctive: line 65
No premature abstraction: Don't extract until complexity demands it.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Project Configuration
Tech Stack
- Ruby 3.3, Rails 8.1, PostgreSQL
- Frontend: Hotwire (Turbo + Stimulus), Tailwind CSS 4, ViewComponent
- Testing: RSpec, FactoryBot, Shoulda Matchers, Capybara
- Auth:
has_secure_password(Rails 8 built-in), Pundit (authorization) - Background Jobs: Solid Queue (database-backed, no Redis)
- Caching: Solid Cache | WebSockets: Solid Cable
- Assets: Propshaft + Import Maps (no Node.js)
- Deployment: Kamal 2 + Thruster
Architecture
app/
controllers/ # Thin. Delegates to services. Renders responses.
models/ # Persistence: validations, associations, scopes, simple predicates.
views/ # ERB markup only. No logic.
services/ # Business logic. Orchestrates models, APIs, side effects.
queries/ # Complex database queries. Returns relations or hashes.
forms/ # Multi-model form objects.
policies/ # Pundit authorization. Default deny.
presenters/ # View formatting (SimpleDelegator).
components/ # ViewComponents (reusable UI with tests).
jobs/ # Background jobs (Solid Queue). Must be idempotent.
mailers/ # Email delivery. Always HTML + text templates.Key Commands
# Tests
bundle exec rspec # Full suite
bundle exec rspec spec/path/to_spec.rb # Specific file
bundle exec rspec spec/path/to_spec.rb:25 # Specific line
# Linting
bundle exec rubocop -a # Auto-fix Ruby
bundle exec rubocop -a app/models/ # Specific directory
# Security
bin/brakeman --no-pager # Static analysis
bundle exec bundler-audit check --update # Gem vulnerabilities
# Database
bin/rails db:migrate # Run migrations
bin/rails db:migrate:status # Check status
bin/rails console # Interactive consoleDevelopment Workflow
Follow TDD: Red -> Green -> Refactor:
- RED: Write a failing test describing desired behavior
- GREEN: Write minimal code to pass the test
- REFACTOR: Improve code structure while keeping tests green
Core Conventions
- Skinny Everything: Controllers orchestrate. Models persist. Services contain business logic. Views display.
- Callbacks: Only for data normalization (
before_validation,before_save). Side effects (emails, jobs, APIs) belong in services. - Services:
.callclass method, return Result objects, namespace by domain (Entities::CreateService). - No premature abstraction: Don't extract until complexity demands it. Three similar lines > wrong abstraction.
- Explicit > implicit: Clear service calls over hidden callbacks. Named methods over metaprogramming.
See @docs/rails-development-principles.md for the complete development principles guide.
Naming Conventions
| Layer | Pattern | Example |
| Model | Singular PascalCase | Entity, OrderItem |
| Controller | Plural PascalCase | EntitiesController |
| Service | Namespaced + Service | Entities::CreateService |
| Query | Namespaced + Query | Entities::SearchQuery |
| Policy | Singular + Policy | EntityPolicy |
| Job | Descriptive + Job | ProcessPaymentJob |
| Presenter | Singular + Presenter | EntityPresenter |
| Form | Descriptive + Form | EntityRegistrationForm |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

