Skip to content
Back to search

rails-audit-thoughtbot

Claude skill to run code audits

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/thoughtbot--rails-audit-thoughtbot/badge.svg)](/listings/thoughtbot--rails-audit-thoughtbot)

HTML

<a href="/listings/thoughtbot--rails-audit-thoughtbot"><img src="/api/listings/thoughtbot--rails-audit-thoughtbot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 183 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: rails-audit-thoughtbot
  3. description: Perform comprehensive code audits of Ruby on Rails applications based on thoughtbot best practices. Use this skill when the user requests a code audit, code review, quality assessment, or analysis of a Rails application. The skill analyzes the entire codebase focusing on testing practices (RSpec), security vulnerabilities, code design (skinny controllers, domain models, PORO with ActiveModel), Rails conventions, database optimization, and Ruby best practices. Outputs a detailed markdown audit report grouped by category (Testing, Security, Models, Controllers, Code Design, Views) with severity levels (Critical, High, Medium, Low) within each category.
  4. ---
  5. # Rails Audit Skill (thoughtbot Best Practices)
  6. Perform comprehensive Ruby on Rails application audits based on thoughtbot's Ruby Science and Testing Rails best practices, with emphasis on Plain Old Ruby Objects (POROs) over Service Objects.
  7. ## Audit Scope
  8. The audit can be run in two modes:
  9. 1. **Full Application Audit**: Analyze entire Rails application
  10. 2. **Targeted Audit**: Analyze specific files or directories
  11. ## Execution Flow
  12. ### Step 1: Determine Audit Scope
  13. Ask user or infer from request:
  14. - Full audit: Analyze all of `app/`, `spec/` or `test/`, `config/`, `db/`, `lib/`
  15. - Targeted audit: Analyze specified paths only
  16. ### Step 2: Collect Optional Metrics (SimpleCov + RubyCritic)
  17. Ask the user **both questions upfront** in a single `AskUserQuestion` so they can decide once:
  18. - **Question**: "Before starting the audit, would you like to collect automated metrics?\n\n1. **SimpleCov** — runs your test suite to capture actual code coverage percentages\n2. **RubyCritic** — analyzes code complexity, duplication, and smells (does not run tests)\n\nBoth are recommended for the most thorough audit."
  19. - **Options**: "Yes to both (Recommended)" / "SimpleCov only" / "RubyCritic only" / "Skip both"
  20. Based on the user's choice, spawn the accepted subagents **in parallel** using the Task tool. Both can run at the same time because SimpleCov modifies the test helper while RubyCritic only reads source files — they don't conflict.
  21. **SimpleCov subagent** (if accepted):
  22. > Read the file `agents/simplecov_agent.md` and follow all steps described in it. The audit scope is: {{SCOPE from Step 1}}. Return the coverage data in the output format specified in that file.
  23. **RubyCritic subagent** (if accepted):
  24. > Read the file `agents/rubycritic_agent.md` and follow all steps described in it. The audit scope is: {{SCOPE from Step 1}}. Return the code quality data in the output format specified in that file.
  25. **After both agents finish**, clean up:
  26. - If SimpleCov ran: `rm -rf coverage/`
  27. - If RubyCritic ran: `rm -rf tmp/rubycritic/`
  28. **Interpreting responses:**
  29. - `COVERAGE_FAILED` / `RUBYCRITIC_FAILED`: no data for that tool — use estimation mode (SimpleCov) or omit the section (RubyCritic). Note the failure reason in the report.
  30. - `COVERAGE_DATA`: parse and keep in context for Steps 4 and 5 (overall coverage, per-directory breakdowns, lowest-coverage files, zero-coverage files).
  31. - `RUBYCRITIC_DATA`: parse and keep in context for Steps 4 and 5 (overall score, per-directory ratings, worst-rated files, top smells, most complex files).
  32. ### Step 3: Load Reference Materials
  33. Before analyzing, read the relevant reference files:
  34. - `references/code_smells.md` - Code smell patterns to identify
  35. - `references/testing_guidelines.md` - Testing best practices
  36. - `references/poro_patterns.md` - PORO and ActiveModel patterns
  37. - `references/security_checklist.md` - Security vulnerability patterns
  38. - `references/rails_antipatterns.md` - Rails-specific antipatterns (external services, migrations, performance)
  39. ### Step 4: Analyze Code by Category
  40. All analysis must stay within the project root and the bundle path. To inspect gem source, use `bundle show <gem>` to locate it (see "Locate gem source" under Analysis Commands) — never run filesystem-wide searches like `find /`. If you delegate any category below to subagents, include this constraint in each subagent's prompt.
  41. Analyze in this order:
  42. 1. **Testing Coverage & Quality**
  43. - If SimpleCov data was collected in Step 2, use actual coverage percentages instead of estimates
  44. - Cross-reference per-file SimpleCov data: files with 0% coverage = "missing tests"
  45. - Check for missing test files
  46. - Identify untested public methods
  47. - Review test structure (Four Phase Test)
  48. - Check for testing antipatterns
  49. 2. **Security Vulnerabilities**
  50. - SQL injection risks
  51. - Mass assignment vulnerabilities
  52. - XSS vulnerabilities
  53. - Authentication/authorization issues
  54. - Sensitive data exposure
  55. 3. **Models & Database**
  56. - Fat model detection
  57. - Missing validations
  58. - N+1 query risks
  59. - Callback complexity
  60. - Law of Demeter violations (voyeuristic models)
  61. - If RubyCritic data was collected, flag models with D/F ratings or high complexity
  62. 4. **Controllers**
  63. - Fat controller detection
  64. - Business logic in controllers
  65. - Missing strong parameters
  66. - Response handling
  67. - Monolithic controllers (non-RESTful actions, > 7 actions)
  68. - Bloated sessions (storing objects instead of IDs)
  69. - If RubyCritic data was collected, flag controllers with D/F ratings or high complexity
  70. 5. **Code Design & Architecture**
  71. - Service Objects → recommend PORO refactoring
  72. - Large classes
  73. - Long methods
  74. - Feature envy
  75. - Law of Demeter violations
  76. - Single Responsibility violations
  77. - If RubyCritic data was collected, cross-reference D/F rated files and high-complexity files with manual code review findings
  78. 6. **Views & Presenters**
  79. - Logic in views (PHPitis)
  80. - Missing partials for DRY
  81. - Helper complexity
  82. - Query logic in views
  83. 7. **External Services & Error Handling**
  84. - Fire and forget (missing exception handling for HTTP calls)
  85. - Sluggish services (missing timeouts, synchronous calls that should be backgrounded)
  86. - Bare rescue statements
  87. - Silent failures (save without checking return value)
  88. 8. **Database & Migrations**
  89. - Messy migrations (model references, missing down methods)
  90. - Missing indexes on foreign keys, polymorphic associations, uniqueness validations
  91. - Performance antipatterns (Ruby iteration vs SQL queries)
  92. - Bulk operations without transactions
  93. ### Step 5: Generate Audit Report
  94. Create `RAILS_AUDIT_REPORT.md` in project root with structure defined in `references/report_template.md`.
  95. When SimpleCov coverage data was collected in Step 2, use the **SimpleCov variant** of the Testing section in the report template. When coverage data is not available, use the **estimation variant**.
  96. When RubyCritic data was collected in Step 2b, include the **Code Quality Metrics** section in the report using the RubyCritic variant from the report template. When RubyCritic data is not available, use the **not available variant**.
  97. ## Severity Definitions
  98. - **Critical**: Security vulnerabilities, data loss risks, production-breaking issues
  99. - **High**: Performance issues, missing tests for critical paths, major code smells
  100. - **Medium**: Code smells, convention violations, maintainability concerns
  101. - **Low**: Style issues, minor improvements, suggestions
  102. ## Key Detection Patterns
  103. ### Service Object → PORO Refactoring
  104. When you find classes in `app/services/`:
  105. - Classes named `*Service`, `*Manager`, `*Handler`
  106. - Classes with only `.call` or `.perform` methods
  107. - Recommend: Rename to domain nouns, include `ActiveModel::Model`
  108. ### Fat Model Detection
  109. Models with:
  110. - More than 200 lines
  111. - More than 15 public methods
  112. - Multiple unrelated responsibilities
  113. - Recommend: Extract to POROs using composition
  114. ### Fat Controller Detection
  115. Controllers with:
  116. - Actions over 15 lines
  117. - Business logic (not request/response handling)
  118. - Multiple instance variable assignments
  119. - Recommend: Extract to form objects or domain models
  120. ### Missing Test Detection
  121. For each Ruby file in `app/`:
  122. - Check for corresponding `_spec.rb` or `_test.rb`
  123. - Check for tested public methods
  124. - Report untested files and methods
  125. ## Analysis Commands
  126. Use Claude Code's built-in tools instead of shell commands — they're faster, handle permissions correctly, and give better output:
  127. - **Find Ruby files by type**: Use the Glob tool with patterns like `app/models/**/*.rb`, `app/controllers/**/*.rb`, `app/services/**/*.rb`
  128. - **Find test files**: Use Glob with `spec/**/*_spec.rb` or `test/**/*_test.rb`
  129. - **Search for patterns in code**: Use the Grep tool (e.g., search for `rescue\s*$`, `\.save\b`, `params\.permit!`)
  130. - **Read and count lines in files**: Use the Read tool to inspect files; count lines from the output
  131. - **Find long files**: Use Glob to list all `app/**/*.rb` files, then Read each to check line count
  132. - **Locate gem source**: When analysis requires reading gem-provided code (e.g., a base controller or concern from an engine like Devise, Administrate, or Madmin), use `bundle show <gem>` (or `bundle exec gem which <gem>/<path>`) to find the installed gem's directory, then Read/Grep within it. Never search outside the project root and the bundle path — no `find /` or home-directory-wide globs.
  133. ## Report Output
  134. Always save the audit report to `RAILS_AUDIT_REPORT.md` in the project root and present it to the user.
README.md · README · 192 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Rails Audit Skill (thoughtbot Best Practices)
  2. A [Claude Code][claude-code] skill that performs comprehensive code audits of
  3. Ruby on Rails applications based on [thoughtbot's][thoughtbot] Ruby Science and
  4. Testing Rails best practices.
  5. [claude-code]: https://docs.anthropic.com/en/docs/claude-code
  6. [thoughtbot]: https://thoughtbot.com
  7. ## Quick links
  8. - **[Ruby Science][ruby-science]** - thoughtbot's guide to fixing code smells
  9. - **[Testing Rails][testing-rails]** - thoughtbot's guide to testing Rails applications
  10. - **[Rails Antipatterns][rails-antipatterns]** - Best practices for Ruby on
  11. Rails refactoring (Chad Pytel & Tammer Saleh)
  12. [ruby-science]: https://github.com/thoughtbot/ruby-science
  13. [testing-rails]: https://github.com/thoughtbot/testing-rails
  14. [rails-antipatterns]: https://www.informit.com/store/rails-antipatterns-best-practice-ruby-on-rails-refactoring-9780321604811
  15. ## Table of contents
  16. - [Overview](#overview)
  17. - [Installation](#installation)
  18. - [Usage](#usage)
  19. - [Full application audit](#full-application-audit)
  20. - [Targeted audit](#targeted-audit)
  21. - [Optional data collection](#optional-data-collection)
  22. - [SimpleCov (test coverage)](#simplecov-test-coverage)
  23. - [RubyCritic (code quality)](#rubycritic-code-quality)
  24. - [Reference materials](#reference-materials)
  25. - [Contributing](#contributing)
  26. - [License](#license)
  27. - [About thoughtbot](#about-thoughtbot)
  28. ## Overview
  29. This skill analyses Rails applications and generates detailed audit reports
  30. covering:
  31. - Testing practices (RSpec)
  32. - Test coverage via [SimpleCov](#optional-data-collection) (optional)
  33. - Code quality metrics via [RubyCritic](#optional-data-collection) (optional)
  34. - Security vulnerabilities
  35. - Code design (skinny controllers, domain models, POROs with ActiveModel)
  36. - Rails conventions
  37. - Database optimisation (missing indexes, migrations hygiene)
  38. - External services (timeouts, error handling, background jobs)
  39. - Performance antipatterns (Ruby vs SQL, silent failures)
  40. - Ruby best practices
  41. ## Installation
  42. ### Via Claude Code
  43. Add the [thoughtbot marketplace](https://github.com/thoughtbot/skills) to
  44. Claude Code:
  45. ```
  46. /plugin marketplace add thoughtbot/skills
  47. ```
  48. Install the plugin:
  49. ```
  50. /plugin install rails-audit-thoughtbot@skills
  51. ```
  52. ### Manually
  53. Copy the skill directory to your Claude Code skills folder:
  54. ```bash
  55. cp -r rails-audit-thoughtbot ~/.claude/skills/
  56. ```
  57. Or clone directly:
  58. ```bash
  59. git clone https://github.com/thoughtbot/rails-audit-thoughtbot ~/.claude/skills/rails-audit-thoughtbot
  60. ```
  61. ## Usage
  62. If you are in your terminal and not in a Claude session, you can invoke the
  63. skill directly by using the below. You need to be in the root directory of your
  64. Rails project.
  65. ### Full application audit
  66. ```
  67. claude audit
  68. ```
  69. If you are in a Claude session, you can reference the skill directly:
  70. ```
  71. /rails-audit-thoughtbot
  72. ```
  73. ### Targeted audit
  74. In a Claude session you can also run targeted audits:
  75. ```
  76. /rails-audit-thoughtbot audit controllers
  77. ```
  78. This focuses the audit on specific files or directories.
  79. ## Optional data collection
  80. During the audit, the skill offers to run optional data-collection steps that
  81. enrich the report with tool-measured metrics. Each step is opt-in — you will be
  82. prompted before anything is installed or executed. If the tool is already in your
  83. Gemfile, the skill uses it directly without modifying your project.
  84. ### SimpleCov (test coverage)
  85. Runs your test suite with [SimpleCov](https://github.com/simplecov-ruby/simplecov)
  86. to capture actual line and branch coverage percentages. The report will include
  87. per-directory coverage breakdowns, lowest-coverage files, and zero-coverage files.
  88. - Temporarily adds `simplecov` to the Gemfile (if not already present)
  89. - Runs the full test suite (RSpec or Minitest)
  90. - Restores the original Gemfile after collection
  91. - Cleans up all generated coverage files
  92. ### RubyCritic (code quality)
  93. Runs [RubyCritic](https://github.com/whitesmith/rubycritic) to measure code
  94. complexity, duplication, and code smells using Reek, Flay, and Flog. The report
  95. will include per-file ratings (A-F), worst-rated files, most common smells, and
  96. most complex files.
  97. - Temporarily adds `rubycritic` to the Gemfile (if not already present)
  98. - Analyzes `app/` and `lib/` (or targeted paths)
  99. - Restores the original Gemfile after collection
  100. - Cleans up all generated report files
  101. ## Reference materials
  102. The skill includes reference documentation based on thoughtbot best practices.
  103. All the materials are compacted information from the books mentioned above.
  104. Recommendations of PORO objects are based on different thoughtbot sources and
  105. [Service objects are poorly-named models][service-objects-poro].
  106. [service-objects-poro]: https://dimiterpetrov.com/blog/service-objects-are-poorly-named-models/
  107. | File | Description |
  108. |------|-------------|
  109. | `references/code_smells.md` | Code smell patterns to identify (Ruby Science) |
  110. | `references/testing_guidelines.md` | Testing best practices (Testing Rails) |
  111. | `references/poro_patterns.md` | PORO and ActiveModel patterns |
  112. | `references/security_checklist.md` | Security vulnerability checklist |
  113. | `references/rails_antipatterns.md` | Rails-specific antipatterns: external services, migrations, performance |
  114. | `references/report_template.md` | Audit report structure template |
  115. | `agents/simplecov_agent.md` | Subagent for SimpleCov test coverage collection |
  116. | `agents/rubycritic_agent.md` | Subagent for RubyCritic code quality metrics |
  117. ## Contributing
  118. Contributions are welcome! If you'd like to improve the audit patterns or add
  119. new detection rules:
  120. 1. Fork the repository
  121. 2. Create your feature branch (`git checkout -b my-new-feature`)
  122. 3. Commit your changes (`git commit -am 'Add some feature'`)
  123. 4. Push to the branch (`git push origin my-new-feature`)
  124. 5. Create a new Pull Request
  125. ## License
  126. This skill is open source and available under the [MIT License](LICENSE).
  127. ## About thoughtbot
  128. ![thoughtbot](https://thoughtbot.com/thoughtbot-logo-for-readmes.svg)
  129. This skill is inspired by and based on thoughtbot's excellent guides:
  130. - [Ruby Science](https://github.com/thoughtbot/ruby-science)
  131. - [Testing Rails](https://github.com/thoughtbot/testing-rails)
  132. - [Rails Antipatterns](https://www.informit.com/store/rails-antipatterns-best-practice-ruby-on-rails-refactoring-9780321604811) by Chad Pytel & Tammer Saleh
  133. The names and logos for thoughtbot are trademarks of thoughtbot, inc.
  134. We love open source software!
  135. See [thoughtbot's other projects][community].
  136. [community]: https://thoughtbot.com/community?utm_source=github

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.