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.

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.*