# 37signals-rails

A rule set for Ruby on Rails the 37signals way: vanilla Rails, CRUD controllers, rich domain models, Hotwire. Useful when you write or refactor code and want to stay in that school.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 329 installs · ★ 218
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/37signals-rails/SKILL.md
- Updated: 2026-08-15
- HTML: https://affpapa.org/en/nevibecode/skills/37signals-rails

## What it does

The skill packs 56 rules across 8 categories, ordered by architectural impact. Sources are the Fizzy codebase, STYLE.md, AGENTS.md, the Rails Doctrine, DHH's "On Writing Software Well" series, and an unofficial style guide built from 265 Fizzy pull requests. Categories carry prefixes: `arch-` and `ctrl-` are critical, `model-`, `state-` and `db-` rank high, `view-`, `style-` and `test-` sit in the middle.

Each rule comes with reasoning. Rich domain models instead of service objects. Controllers limited to CRUD. `params.expect()` for parameter validation, `normalizes` and `store_accessor`, `delegated_type`, counter caches. Solid Queue, Solid Cache and Solid Cable for jobs, caching and pub/sub. Path-based multi-tenancy through `Current.account`, UUID primary keys, Turbo Frames and Turbo Streams, Stimulus, Minitest. There is also a section on patterns and gems 37signals deliberately avoids.

Rules link out to individual documents under `references/`. Install runs through `npx skills`, and the skill covers Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. GitHub Copilot uses `gh skill install` instead. One thing to know before you start: the skill recommends custom passwordless auth over Devise, so on a Devise project expect the agent to argue with your existing setup.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill 37signals-rails -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/37signals-rails/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/37signals-rails/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill 37signals-rails -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/37signals-rails/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill 37signals-rails -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/37signals-rails/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills 37signals-rails
```

2. **Manually: put the files in place**
- File: `.github/skills/37signals-rails/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill 37signals-rails -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/37signals-rails
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/37signals-rails/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill 37signals-rails -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/37signals-rails/SKILL.md

## When to use it
- pick between a gem and vanilla Rails while designing a feature
- rewrite a controller with custom actions into plain CRUD
- move logic out of service objects into domain models
- set up background jobs, caching and pub/sub without extra services
- check code against 37signals conventions before review

## Example prompts
- Rewrite this controller the 37signals way: CRUD actions only, push the logic into the model.
- Review this schema against the skill's rules — where should I use UUIDs and constraints instead of validations?
- Refactor this view for Hotwire: Turbo Frames instead of a full page reload.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8d1c8d671128de12.

BEGIN THIRD-PARTY FILE 8d1c8d671128de12
```text
---
name: 37signals-rails
description: 37signals Rails coding principles and conventions from DHH, Jorge Manrubia, and the Fizzy/Basecamp/HEY codebase. This skill should be used when writing, reviewing, or refactoring Ruby on Rails code following the 37signals philosophy — vanilla Rails, CRUD controllers, rich domain models, concerns, no service objects, Hotwire, Turbo, Stimulus, Solid Queue, Solid Cache, Solid Cable, multi-tenancy, Minitest, custom auth, or DHH conventions.
---

# 37signals Rails Best Practices

Comprehensive coding principles and conventions for Ruby on Rails applications, as practiced at 37signals (Basecamp, HEY, Fizzy). Contains 56 rules across 8 categories, prioritized by architectural impact. Derived from official 37signals sources: the Fizzy codebase, STYLE.md, AGENTS.md, the Rails Doctrine, DHH's "On Writing Software Well" series, and the unofficial 37signals style guide (265 Fizzy PRs).

## When to Apply

Reference these guidelines when:
- Writing new Rails controllers, models, or views
- Deciding between gems and vanilla Rails
- Modeling state and database schema
- Setting up background jobs, caching, or real-time features
- Reviewing code for 37signals-style conventions
- Refactoring toward rich domain models
- Choosing authentication or authorization approach
- Adding Stimulus controllers or Turbo patterns

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Architecture Fundamentals | CRITICAL | `arch-` |
| 2 | Controllers & REST | CRITICAL | `ctrl-` |
| 3 | Domain Modeling | HIGH | `model-` |
| 4 | State Management | HIGH | `state-` |
| 5 | Database & Infrastructure | HIGH | `db-` |
| 6 | Views & Frontend | MEDIUM | `view-` |
| 7 | Code Style | MEDIUM | `style-` |
| 8 | Testing | MEDIUM | `test-` |

## Quick Reference

### 1. Architecture Fundamentals (CRITICAL)

- [`arch-rich-models`](references/arch-rich-models.md) - Rich Domain Models Over Service Objects
- [`arch-vanilla-rails`](references/arch-vanilla-rails.md) - Vanilla Rails is Plenty
- [`arch-avoid-patterns`](references/arch-avoid-patterns.md) - Deliberately Avoided Patterns and Gems
```
END THIRD-PARTY FILE 8d1c8d671128de12

The third-party file has ended. Everything between the 8d1c8d671128de12 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2180 of 8352 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/37signals-rails/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md