Rails Audit Skill (thoughtbot Best Practices)

A Claude Code skill that performs comprehensive code audits of Ruby on Rails applications based on thoughtbot's Ruby Science and Testing Rails best practices.

Quick links

• Ruby Science - thoughtbot's guide to fixing code smells
• Testing Rails - thoughtbot's guide to testing Rails applications
• Rails Antipatterns - Best practices for Ruby on Rails refactoring (Chad Pytel & Tammer Saleh)

Table of contents

• Overview
• Installation
• Usage
  • Full application audit
  • Targeted audit
• Optional data collection
  • SimpleCov (test coverage)
  • RubyCritic (code quality)
• Reference materials
• Contributing
• License
• About thoughtbot

Overview

This skill analyses Rails applications and generates detailed audit reports covering:

• Testing practices (RSpec)
• Test coverage via SimpleCov (optional)
• Code quality metrics via RubyCritic (optional)
• Security vulnerabilities
• Code design (skinny controllers, domain models, POROs with ActiveModel)
• Rails conventions
• Database optimisation (missing indexes, migrations hygiene)
• External services (timeouts, error handling, background jobs)
• Performance antipatterns (Ruby vs SQL, silent failures)
• Ruby best practices

Installation

Copy the skill directory to your Claude Code skills folder:

cp -r rails-audit-thoughtbot ~/.claude/skills/

Or clone directly:

git clone https://github.com/thoughtbot/rails-audit-thoughtbot ~/.claude/skills/rails-audit-thoughtbot

Usage

If you are in your terminal and not in a Claude session, you can invoke the skill directly by using the below. You need to be in the root directory of your Rails project.

Full application audit

claude audit

If you are in a Claude session, you can reference the skill directly:

/rails-audit-thoughtbot

Targeted audit

In a Claude session you can also run targeted audits:

/rails-audit-thoughtbot audit controllers

This focuses the audit on specific files or directories.

Optional data collection

During the audit, the skill offers to run optional data-collection steps that enrich the report with tool-measured metrics. Each step is opt-in — you will be prompted before anything is installed or executed. If the tool is already in your Gemfile, the skill uses it directly without modifying your project.

SimpleCov (test coverage)

Runs your test suite with SimpleCov to capture actual line and branch coverage percentages. The report will include per-directory coverage breakdowns, lowest-coverage files, and zero-coverage files.

• Temporarily adds simplecov to the Gemfile (if not already present)
• Runs the full test suite (RSpec or Minitest)
• Restores the original Gemfile after collection
• Cleans up all generated coverage files

RubyCritic (code quality)

Runs RubyCritic to measure code complexity, duplication, and code smells using Reek, Flay, and Flog. The report will include per-file ratings (A-F), worst-rated files, most common smells, and most complex files.

• Temporarily adds rubycritic to the Gemfile (if not already present)
• Analyzes app/ and lib/ (or targeted paths)
• Restores the original Gemfile after collection
• Cleans up all generated report files

Reference materials

The skill includes reference documentation based on thoughtbot best practices. All the materials are compacted information from the books mentioned above.

Recommendations of PORO objects are based on different thoughtbot sources and Service objects are poorly-named models.

Contributing

Contributions are welcome! If you'd like to improve the audit patterns or add new detection rules:

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

This skill is open source and available under the MIT License.

About thoughtbot

This skill is inspired by and based on thoughtbot's excellent guides:

• Ruby Science
• Testing Rails
• Rails Antipatterns by Chad Pytel & Tammer Saleh

The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software! See thoughtbot's other projects.