Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: add Rails 8 application CLAUDE.md example (#2258)

Rockwell Windsor Ricec5cec96c5864
diff --git a/examples/rails-app-CLAUDE.md b/examples/rails-app-CLAUDE.md
new file mode 100644
index 000000000..f67ecbe6b
--- /dev/null
+++ b/examples/rails-app-CLAUDE.md
@@ -0,0 +1,387 @@
+# Rails Application: Project CLAUDE.md
+
+> Real-world example for a Rails 8 monolithic web application with Hotwire, ViewComponent, and the Solid stack.
+> Copy this to your project root and customize for your service.
+
+## Project Overview
+
+**Stack:** Ruby 3.3+, Rails 8.x, PostgreSQL 16, SolidQueue, SolidCache, SolidCable, Hotwire (Turbo + Stimulus), ViewComponent, Tailwind CSS, RSpec, FactoryBot, Capybara, Kamal
+
+**Architecture:** Full-stack Rails monolith. Server-rendered with Hotwire for interactivity rather than an SPA. Database-backed Solid stack replaces Redis for background jobs, cache, and WebSockets. ViewComponent for testable view logic. Service objects for business operations. Deployed via Kamal to self-managed Linux hosts.
+
+## Critical Rules
+
+### Ruby Conventions
+
+- `# frozen_string_literal: true` at the top of every Ruby file
+- Modern hash syntax (`key:`) over hash rockets (`:key =>`) unless the key is not a symbol
+- Double quotes by default; single quotes only when the string contains a double quote
+- Two-space indentation, no tabs
+- Use `bin/` wrappers (`bin/rails`, `bin/rspec`, `bin/rubocop`) instead of `bundle exec` directly
+- RuboCop is authoritative; either fix the code or update the config in a PR that explains why
+- No `puts`, `pp`, `debugger`, or `binding.pry` in committed code; use `Rails.logger.<level>` for logging
+
+### Database
+
+- Eager load associations by default to prevent N+1 queries
+- Avoid `default_scope`; use named scopes that callers opt into
+- Use `.includes`, `.preload`, or `.eager_load` depending on need to avoid N+1 queries
+- Counter caches on any `has_many` where the count is displayed in lists
+- Callbacks for data normalization only (`before_validation :normalize_email`); anything with side effects belongs in a service
+- Migrations are reversible by default; document any one-way migration explicitly
+
+```ruby
+# BAD: N+1 query
+posts = Post.published
+posts.each { |post| post.author.name } # one query per post
+
+# GOOD: Single query with eager load
+posts = Post.published.includes(:author)
+posts.each { |post| post.author.name }
+```
+
+### Authentication and Authorization
+
+- Authentication via the Rails 8 generated authentication system (`bin/rails generate authentication`) or Devise for more complex flows
+- Session-based auth for full-stack pages, token-based for any embedded API endpoints
+- Authorization via Pundit; every controller action has an `authorize` call or an explicit `skip_authorization` with a documented reason
+- Strong parameters always; never `params.permit!`
+- CSRF protection enabled by default; only disable per action with explicit justification
+
+### Background Jobs
+
+- SolidQueue is the default in Rails 8; Sidekiq remains acceptable for high-throughput cases
+- Pass IDs to jobs, not records; this avoids `ActiveJob::DeserializationError` when records are deleted between enqueue and execute
+- `perform` methods must be idempotent; assume they will run more than once
+- Declare retry behavior explicitly with `retry_on` and `discard_on`
+- Name jobs by action (`SendInvoiceJob`, `ExportAccountingJob`), not by noun
+- For jobs touching external systems, pair the local idempotency check with an API-level idempotency token, and consider row-level locking (`with_lock`) for high-concurrency scenarios
+
+### Views and Hotwire
+
+- Hotwire (Turbo + Stimulus) before reaching for a JavaScript framework
+- ViewComponent for any view logic that has conditionals, accepts multiple parameters, or appears in more than three places
+- ERB partials for simple presentation; no business logic in views
+- Tailwind utility classes for styling; avoid custom CSS unless utilities cannot express the design
+- Turbo Frames for partial page updates; Turbo Streams for server-driven multi-update responses
+
+### Real-time and ActionCable
+
+- SolidCable is the Rails 8 default pub/sub backend; no Redis required
+- Authenticate connections in `ApplicationCable::Connection#connect`; never trust the client to identify itself
+- Authorize subscriptions in each channel's `subscribed` method before calling `stream_from`
+- Prefer Turbo Stream broadcasts (`broadcasts_to`, `broadcast_replace_later_to`) for view updates over hand-written channels
+- Treat ActionCable broadcasts as public; never include sensitive data the subscriber should not see
+
+### Deployment Setup
+
+Production deploys via Kamal:
+
+- `config/deploy.yml` is the source of truth for servers, registry, and environment config
+- `.kamal/secrets` references secrets from the host environment; the file is committed, the secrets are not
+- Production hosts are Docker-capable machines (typically Linux) with SSH access from the deploying machine
+- Migrations run as part of the deploy lifecycle; no manual migration step
+
+### Error Handling
+
+- Service objects return Result objects on success and failure; do not raise across service boundaries
+- Rescue expected errors inside the service and capture them on the result
+- Custom domain errors live in a dedicated location (`app/errors/` or `lib/errors/`, autoloaded as configured); one error class per failure mode
+- Never expose internal error details to clients; user-facing errors come from explicit messages, not exception strings
+- Use `rescue_from` sparingly in controllers; let the default Rails error handling do its job
+
+### Code Style
+
+- No emojis in code or comments
+- Max line length 120 characters (RuboCop default)
+- Classes PascalCase, methods and variables snake_case, constants UPPER_SNAKE_CASE
+- Controllers stay under 80 lines; models stay under 200 lines; anything longer needs extraction
+- Service objects under `app/services/`, namespaced by domain (`Invoices::Create`, not `InvoiceCreator`)
+
+## File Structure
+
+```
+app/
+ models/ # ActiveRecord models. Persistence and domain logic close to the data.
+ controllers/ # HTTP request handling. Thin orchestration only.
+ views/ # ERB templates. No business logic.
+ components/ # ViewComponent classes. View logic that needs tests.
+ services/ # Service objects under domain namespaces.
+ forms/ # Form objects for multi-model forms.
+ queries/ # Query objects for reusable, composable ActiveRecord queries.
+ jobs/ # Background jobs. SolidQueue or Sidekiq.
+ mailers/ # ActionMailer classes.
+ channels/ # ActionCable channels. Real-time WebSocket connections.
+ policies/ # Pundit authorization policies, one per resource.
+ errors/ # Custom domain error classes.
+config/
+ routes.rb
+ database.yml
+ credentials/
+ production.yml.enc # Encrypted production credentials.
+ deploy.yml # Kamal deploy configuration.
+db/
+ migrate/ # Migrations, committed and reversible.
+ seeds.rb
+spec/
+ models/
+ services/
+ components/
+ system/ # Capybara system tests.
+ factories/ # FactoryBot definitions.
+ support/ # Shared spec helpers.
+```
+
+## Key Patterns
+
+### Service Object Pattern
+
+```ruby
+# app/services/invoices/create.rb
+module Invoices
+ class Create
+ Result = Data.define(:success?, :invoice, :errors)
+
+ def self.call(...) = new(...).call
+
+ def initialize(params:, user:)
+ @params = params
+ @user = user
+ end
+
+ def call
+ invoice = build_invoice
+
+ ApplicationRecord.transaction do
+ invoice.save!
+ end
+
+ begin
+ send_notifications(invoice)
+ rescue StandardError => e
+ Rails.logger.error("Notification dispatch failed for invoice #{invoice.id}: #{e.message}")
+ end
+
+ Result.new(success?: true, invoice: invoice, errors: nil)
+ rescue ActiveRecord::RecordInvalid => e
+ Result.new(success?: false, invoice: e.record, errors: e.record.errors)
+ end
+
+ private
+
+ attr_reader :params, :user
+
+ def build_invoice
+ invoice = user.invoices.new(params.except(:line_items))
+ invoice.line_items.build(params[:line_items])
+ invoice.total = invoice.line_items.sum(&:amount)
+ invoice
+ end
+
+ def send_notifications(invoice)
+ InvoiceMailer.created(invoice).deliver_later
+ ExportAccountingJob.perform_later(invoice.id)
+ end
+ end
+end
+```
+
+### Skinny Controller Pattern
+
+```ruby
+# app/controllers/invoices_controller.rb
+class InvoicesController < ApplicationController
+ before_action :require_authentication # Rails 8 generator default; use authenticate_user! with Devise
+
+ def create
+ authorize Invoice
+
+ result = Invoices::Create.call(params: invoice_params, user: current_user)
+
+ if result.success?
+ redirect_to result.invoice, notice: "Invoice created"
+ else
+ @invoice = result.invoice
+ render :new, status: :unprocessable_entity
+ end
+ end
+
+ private
+
+ def invoice_params
+ params.require(:invoice).permit(:customer_id, line_items: %i[description amount])
+ end
+end
+```
+
+### Query Object Pattern
+
+```ruby
+# app/queries/invoices/overdue.rb
+module Invoices
+ class Overdue
+ def self.call(...) = new(...).call
+
+ def initialize(scope: Invoice.all, as_of: Time.current)
+ @scope = scope
+ @as_of = as_of
+ end
+
+ def call
+ scope
+ .where(status: :sent)
+ .where(due_date: ..as_of)
+ .where.not(id: paid_invoice_ids)
+ .includes(:customer, :line_items)
+ end
+
+ private
+
+ attr_reader :scope, :as_of
+
+ def paid_invoice_ids
+ Payment.where(created_at: ..as_of).pluck(:invoice_id)
+ end
+ end
+end
+```
+
+### Background Job Pattern
+
+```ruby
+# app/jobs/export_accounting_job.rb
+class ExportAccountingJob < ApplicationJob
+ queue_as :exports
+
+ retry_on AccountingApi::TransientError, wait: :polynomially_longer, attempts: 5
+ discard_on AccountingApi::PermanentError
+
+ def perform(invoice_id)
+ invoice = Invoice.find(invoice_id)
+ return if invoice.exported_at.present? # local idempotency check
+
+ idempotency_key = "invoice-export-#{invoice.id}"
+ AccountingApi.export(invoice, idempotency_key: idempotency_key)
+ invoice.update!(exported_at: Time.current)
+ end
+end
+```
+
+### Test Pattern (RSpec)
+
+```ruby
+# spec/services/invoices/create_spec.rb
+require "rails_helper"
+
+RSpec.describe Invoices::Create do
+ let(:user) { create(:user) }
+ let(:customer) { create(:customer, user: user) }
+ let(:params) do
+ {
+ customer_id: customer.id,
+ line_items: [{ description: "Consulting", amount: 100_000 }] # $1,000.00 in cents
+ }
+ end
+
+ describe ".call" do
+ it "creates an invoice with the expected total" do
+ result = described_class.call(params: params, user: user)
+
+ expect(result).to be_success
+ expect(result.invoice).to be_persisted
+ expect(result.invoice.total).to eq(100_000)
+ end
+
+ it "enqueues a notification email" do
+ expect {
+ described_class.call(params: params, user: user)
+ }.to have_enqueued_mail(InvoiceMailer, :created)
+ end
+
+ it "returns errors when validation fails" do
+ result = described_class.call(params: params.merge(customer_id: nil), user: user)
+
+ expect(result).not_to be_success
+ expect(result.errors[:customer]).to include("must exist")
+ end
+ end
+end
+```
+
+## Environment Variables
+
+```bash
+# Rails
+RAILS_ENV=production
+RAILS_MASTER_KEY= # decrypts config/credentials/production.yml.enc
+SECRET_KEY_BASE= # auto-generated; never commit
+
+# Database
+DATABASE_URL=postgres://user:pass@host:5432/myapp_production
+
+# SolidQueue, SolidCache, SolidCable
+# These default to the primary database; configure a separate one for higher load:
+QUEUE_DATABASE_URL=postgres://user:pass@host:5432/myapp_queue
+CACHE_DATABASE_URL=postgres://user:pass@host:5432/myapp_cache
+
+# Kamal deploy
+KAMAL_REGISTRY_PASSWORD=
+KAMAL_DEPLOY_USER=
+
+# Application secrets (also storable in Rails encrypted credentials)
+STRIPE_API_KEY=
+SENTRY_DSN=
+```
+
+For most secrets, prefer Rails encrypted credentials (`bin/rails credentials:edit -e production`) over environment variables. ENV vars are appropriate for infrastructure config that varies per host; credentials are appropriate for application secrets that travel with the codebase.
+
+## Testing Strategy
+
+```bash
+# Run the full suite
+bin/rspec
+
+# Run a single file or directory
+bin/rspec spec/services/invoices/
+bin/rspec spec/services/invoices/create_spec.rb
+
+# Run only the last failures
+bin/rspec --only-failures
+
+# Run with random ordering (default) seeded for reproducibility
+bin/rspec --seed 12345
+
+# Run system tests
+bin/rspec spec/system/
+
+# Coverage report (SimpleCov)
+COVERAGE=true bin/rspec
+```
+
+Coverage target is 90% line coverage as a floor, not a goal. Sharp tests with 85% beat exhaustive tests with 100%. System tests use Capybara with the rack_test driver by default and switch to headless Chrome only when JavaScript is required.
+
+## ECC Workflow
+
+```bash
+# Planning
+/plan "Add invoice PDF export with line item subtotals"
+
+# Test-first development
+/tdd # RSpec-based TDD workflow
+
+# Review
+/code-review # General quality check
+/security-scan # Brakeman + dependency audit
+
+# Verification
+/verify # Lint, type-check, test, security scan in one pass
+```
+
+## Git Workflow
+
+- Branch from `main`, named `<type>/<short-description>` (e.g., `feat/invoice-pdf-export`, `fix/n-plus-one-on-dashboard`)
+- Conventional commits style: `feat:` new features, `fix:` bug fixes, `refactor:` code changes
+- Pull requests required for changes to `main`; review according to your team's policy and CI must be green to merge
+- Squash on merge; the merged commit message must be coherent and well-formed
+- Never force-push to `main`; force-pushing feature branches is fine
+- CI runs RuboCop, Brakeman, RSpec, and bundle audit on every PR