agentleFS
ThibautBaissacThibautBaissac/rails_ai_agents/AGENTS.md

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.

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
  1. Distinctive:

    Follow TDD: Red -> Green -> Refactor:

    line 55
  2. Distinctive:

    RED: Write a failing test describing desired behavior

    line 56
  3. Distinctive:

    GREEN: Write minimal code to pass the test

    line 57
  4. Very specific:

    Callbacks: Only for data normalization (before_validation, before_save).

    line 63
  5. Distinctive:

    No premature abstraction: Don't extract until complexity demands it.

    line 65

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 console

Development Workflow

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

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: .call class 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

LayerPatternExample
ModelSingular PascalCaseEntity, OrderItem
ControllerPlural PascalCaseEntitiesController
ServiceNamespaced + ServiceEntities::CreateService
QueryNamespaced + QueryEntities::SearchQuery
PolicySingular + PolicyEntityPolicy
JobDescriptive + JobProcessPaymentJob
PresenterSingular + PresenterEntityPresenter
FormDescriptive + FormEntityRegistrationForm

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.