Source: https://jessewaites.com/blog/post/a-sample-claude-md-file-for-ruby-on-rails-apps

# A sample Claude.md file for Ruby on Rails apps

*July 21, 2025*

Claude.md files are special Markdown files used by Claude Code, an AI-powered coding assistant by Anthropic. A Claude.md file serves as a "control panel" or "pre-flight briefing" for Claude, providing project-specific context and instructions to guide its behavior. Most projects that utilize claude code or other agentic AI tools use a version of this claude.md file. If you are looking for a starter Claude.md file that can modify for use in your specific Ruby on Rails projects, friend, you have come to the right place.

Simply create a blank file at the root of your rails project in the prompt like below. Name it `CLAUDE.md` and check it into git so that you can share it across sessions and with your team, or name it `CLAUDE.local.md` and `.gitignore` it.

**$ touch CLAUDE.md**

Next, paste the text below into this new CLAUDE.md file you just created. After that, modify it to your own liking. You can also run it through [Anthropic's Prompt Improver tool](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prompt-improver).

Let me know how you like it!

```
# CLAUDE.md

## Purpose
This document outlines the expectations, coding standards, and general conventions for contributing to modern Ruby on Rails projects in this organization. It serves as a guide for agentic ai developers to produce clean, maintainable, and idiomatic Rails code.

---

## General Principles
- Use **Rails 8** defaults unless otherwise specified.
- Follow **Convention Over Configuration** wherever possible.
- Keep controllers slim, models focused, and favor service objects or POROs for business logic.
- Use Hotwire (Turbo + Stimulus) as the primary frontend stack.
- Prioritize readability and simplicity over "clever" code.

---

## Code Style
- Follow [Ruby Style Guide](https://rubystyle.guide/).
- Use `rubocop` for automated linting.
- Use `standardrb` if specified in project.

**Naming Conventions:**
- Use descriptive names (avoid abbreviations).
- Scopes, services, and helpers should be named by function, not technology.

**SQL Queries:**
- Prefer ActiveRecord querying methods.
- If using `.pluck`, `.select`, or `.find_by_sql`, document why.

---

## Folder Structure and Patterns
- Place service objects in `/app/services/`.
- Use `/app/queries/` for complex database query objects.
- Place form objects in `/app/forms/` when needed.
- Use `/app/components/` for ViewComponent classes if used.

---

## Controllers
- Keep controllers RESTful.
- Do not embed business logic in controllers.
- Respond with JSON or Turbo Streams depending on frontend needs.

---

## Views and Frontend
- Use Turbo Frames and Turbo Streams where possible.
- Avoid JavaScript unless required. Use Stimulus controllers instead.
- Keep ERB templates clean — minimize logic in views.

---

## Testing
- Use `rspec` for tests unless otherwise specified.
- Focus on:
  - Model specs
  - Request specs (not controller specs)
  - System specs (if testing UI interactions)
- Aim for high test coverage of business logic.

---

## ActiveRecord Best Practices
- Default scopes are discouraged.
- Use `readonly` where applicable for reporting queries.
- Use `enum` cautiously — prefer plain constants if behavior is complex.

---

## Background Jobs
- Use `Sidekiq` for background jobs.
- Place jobs in `/app/jobs/`.
- Keep jobs idempotent.

---

## Security
- Never trust params directly — use strong parameters.
- Avoid inline SQL to prevent SQL injection.
- Sanitize user input in views.
- Regularly check for gem vulnerabilities (`bundle audit`).

---

## Dependencies
- Avoid adding gems unless necessary.
- If adding a gem, document why in the Pull Request.
- Favor gems that follow Rails 7+ conventions and are actively maintained.

---

## Git and Code Review
- Use feature branches.
- Write clear, concise commit messages.
- Squash commits before merging unless history is meaningful.
- All PRs must:
  - Be peer-reviewed.
  - Pass all CI checks.
  - Include tests for new/modified behavior.

---

## Communication Style
- Write comments and documentation in plain, professional language.
- Explain *why* something exists, not *what* it does (code should explain itself).

---

## Tools & CI
- Ensure:
  - `rubocop` or `standardrb` passes.
  - RSpec suite runs green.
  - Any linting/CI tools configured per project pass before merge.

---

*This document is intended to guide, not restrict. If a situation requires breaking a rule, document your reasoning clearly in the PR.*
```