Project Setup

Project Initialization

Step 1: Create the application

rails new myapp

cd myapp

Rails 8 defaults give you everything you need:

Step 2: Verify the Solid Stack

Rails 8 includes Solid Queue, Solid Cache, and Solid Cable by default. Verify they're configured:

# Check Gemfile includes solid gems
grep -E "solid_queue|solid_cache|solid_cable" Gemfile

# Install and configure if missing
bin/rails solid_queue:install
bin/rails solid_cache:install
bin/rails solid_cable:install

Verify config/queue.yml, config/cache.yml, and config/cable.yml reference the solid adapters.

Step 3: Add recommended development gems

# Gemfile additions

group :development do
  gem "annotate"        # Schema annotations on models
  gem "letter_opener"   # Preview emails in browser
end

group :development, :test do
  gem "bullet"          # N+1 query detection
end

bundle install

# Generate annotate config
bin/rails generate annotate:install

# Configure bullet in config/environments/development.rb
# (add inside the configure block)

Bullet configuration:

# config/environments/development.rb
config.after_initialize do
  Bullet.enable = true
  Bullet.rails_logger = true
  Bullet.add_footer = true
end

Step 4: Initialize git

git init
git add -A
git commit -m "Initial Rails 8 application"

Rails generates a comprehensive .gitignore. Verify it excludes:

# These should already be present:
/config/master.key
/config/credentials/*.key
/tmp/*
/log/*
/storage/*
*.sqlite3

Living Documentation

Living documentation files grow with your project. Create them early so both humans and AI agents always have up-to-date context.

AGENTS.md — AI agent context

Create AGENTS.md in the project root. This is the first file an AI agent reads:

# AGENTS.md

## Project Overview
[App name] is a [one-sentence description].

## Tech Stack
- Rails 8+ with SQLite, SolidQueue, SolidCache, SolidCable
- Hotwire (Turbo + Stimulus) for frontend interactivity
- Propshaft for asset pipeline
- Tailwind CSS for styling

## Conventions
- Minitest for testing (no RSpec)
- RESTful routes only
- Fat models, thin controllers
- Background jobs via SolidQueue
- Encrypted credentials for secrets

## Directory Structure

app/ ├── controllers/ # RESTful controllers ├── models/ # ActiveRecord models ├── views/ # ERB templates ├── jobs/ # SolidQueue background jobs └── mailers/ # Action Mailer classes

## Development
```bash
bin/setup          # First-time setup
bin/dev            # Start development server
bin/rails test     # Run tests

Key Domain Concepts

[List 3-5 core domain objects and their relationships]

Update AGENTS.md when you add major features, change conventions, or introduce new architectural patterns.

### SCHEMA.md — Database documentation

Create `SCHEMA.md` to document the intent behind your database design:

```markdown
# SCHEMA.md

Database schema documentation. Updated alongside migrations.

## Tables

### users
Core user model. Authenticates via `has_secure_password`.

| Column | Type | Notes |
|--------|------|-------|
| email | string | Unique, indexed, used for login |
| password_digest | string | bcrypt hash |
| role | string | "member" or "admin", default "member" |

### [next table...]

Keeping it alive: After running bin/rails db:migrate, update SCHEMA.md with the new table or column and a one-line explanation of why it exists. The schema itself shows what; this file explains why.

BUSINESS_RULES.md — Domain rules

Create BUSINESS_RULES.md to capture rules that aren't obvious from code alone:

# BUSINESS_RULES.md

Domain rules and invariants. Updated when business logic changes.

## Pricing
- Free tier: 3 projects, 1 user per project
- Pro tier: unlimited projects, 10 users per project
- Billing is monthly, prorated on upgrade

## Permissions
- Admins can invite/remove members
- Members can create/edit their own resources
- Resources are soft-deleted (archived), never hard-deleted

## Notifications
- Email on invitation accepted
- Email on project shared with user
- No email notifications between 10pm-8am user-local-time

Keeping it alive: When you implement a business rule, add it here. When a rule changes, update it here first, then update the code. This file is the source of truth for "how the business works."

Development Environment

bin/setup

Rails 8 generates a bin/setup script. Verify it handles:

#!/usr/bin/env ruby
# bin/setup

system("bundle install")
system("bin/rails db:prepare")
system("bin/rails tmp:clear")
system("bin/rails restart")

A new developer should clone the repo and run bin/setup — nothing else.

bin/dev

Rails 8 uses Procfile.dev with foreman (via bin/dev):

# Procfile.dev