37signals Skills

A checklist of high-level principles for code quality and design:

1. Abstractions must earn their keep: If an abstraction doesn't explain or enable variations, inline it.
2. Write time > Read time: Compute summaries and sort keys when saving (write time), not when presenting (read time).
3. Database over AR: Prefer database constraints over ActiveRecord validations.
4. Positive names: Use active instead of not_deleted.
5. Explicit over clever: Use case statements instead of metaprogramming for 2-3 variations.
6. StringInquirer for predicates: Use action.completed? instead of manual string comparisons.
7. Touch chains: Use touch: true for cache invalidation.
8. Helpers take params: Do not rely on magical instance variables (@ivar) inside helpers; pass parameters explicitly.
9. Targets over selectors: In Stimulus, use data-*-target instead of complex selectors.
10. Tests shouldn't shape design: Never add code solely to make it more testable.

To make Action Text robust and maintainable in production Rails applications, follow these key patterns:

1. Sanitizer Sync: Always sync sanitizer configuration between Rails and Action Text in production.
2. Render-time Processing: Process HTML at render time rather than save time to allow for maximum flexibility.
3. Client-side Enhancements: Use Stimulus for client-side logic like link retargeting.
4. Remote Images: Use skip_pipeline: true for remote images to prevent processing errors.
5. Rendering Control: Override attachment partials if you need complete control over how attachments are rendered.
6. Defensive Styling: Style defensively, as users will inevitably create unexpected HTML structures.
7. Resilient Testing: Create test helpers to normalize HTML for reliable comparisons.
8. Edge Case Testing: Explicitly test for malformed attachments and entity-encoded punctuation.

The repository provides several specialized skills to guide AI agents in writing Rails code following 37signals patterns.

Automatic Skill:

• rails-best-practices-core: The baseline for all Rails work, covering architecture, naming, modeling, REST routing, and authorization.

On-demand Skills (require explicit invocation): These skills are marked disable-model-invocation: true to prevent bloating every request. Invoke them via slash commands or explicit mentions.

• rails-hotwire-realtime: Turbo Streams/Frames, Stimulus, ActionCable, etc.
• rails-jobs: Active Job design, Solid Queue, and retry policies.
• rails-migrations: Safe schema changes and staged rollouts.
• rails-security-multitenancy: Path-based tenancy and scoped lookups.
• rails-testing: Minitest, fixtures, and Turbo assertions.
• rails-webhooks: Outbox delivery and payload signing.
• dhh: Review code like DHH (direct, opinionated, anti-over-engineering). Use /dhh to invoke.

To ensure reliable webhook delivery, use an outbox pattern where domain events trigger a single dispatch job. This job fans out by creating a persisted Delivery row for every webhook subscription.

Key implementation details:

• State Management: Use a state enum for Delivery rows with values: pending, in_progress, completed, and errored.
• Persistence First: Use after_create_commit :deliver_later on the Delivery model. This ensures the record is persisted before the job is enqueued, allowing state to survive crashes.
• Crash-Safe Fan-out: Use ActiveJob::Continuable with a cursor-based approach (find_each(start: step.cursor) and step.advance!) to allow mid-batch crashes to resume rather than restart.
• Auditability: Record request metadata (headers, payload) and response data (status, body) on the Delivery row. Cap response body storage at ~100KB to prevent unbounded growth.
• Queue Isolation: Use a dedicated webhooks queue to prevent slow destinations from starving other application jobs.

To avoid complex many-to-many relationships, bundle notifications into time windows using a Notification::Bundle model. Instead of linking notifications to bundles via foreign keys, query notifications dynamically based on whether their created_at timestamp falls within the bundle's starts_at and ends_at range. This design keeps notifications immutable and the schema lightweight.

class Notification::Bundle < ApplicationRecord
  belongs_to :user

  enum :status, %i[ pending processing delivered ]

  scope :due, -> { pending.where("ends_at <= ?", Time.current) }
  scope :containing, ->(notification) {
    where("starts_at <= ? AND ends_at > ?", notification.created_at, notification.created_at)
  }

  # Query notifications in the window dynamically - no foreign keys needed!
  def notifications
    user.notifications.where(created_at: window).unread
  end

  private
    def window
      starts_at..ends_at
    end
end