palkan/skills/layered-rails

Layered Rails

Design and review Rails applications using layered architecture principles.

Quick Start

Rails applications are organized into four architecture layers with unidirectional data flow:

┌─────────────────────────────────────────┐
│           PRESENTATION LAYER            │
│   Controllers, Views, Channels, Jobs*   │
│ Forms, Filters, Presenters, Serializers │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│           APPLICATION LAYER             │
│ Services, Policies, Mailers, Deliveries │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│             DOMAIN LAYER                │
│  Models, Value Objects, Query Objects   │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│          INFRASTRUCTURE LAYER           │
│  Active Record, API Clients, Storage    │
└─────────────────────────────────────────┘

\* Jobs are internal inbound entry points: design-wise they follow the same rules as controllers, minus authentication and user-input handling.

Core Rule: Lower layers must never depend on higher layers.

See Architecture Layers Reference for the full layer responsibilities and the Four Rules deep-dive.

What this skill is for

Use this skill when:

1. Analyzing a codebase — apply the architecture analysis for a full audit, or zoom in with the service-layer audit, callback analysis, or god-object analysis.
2. Reviewing code changes — run the code review workflow on a diff, file, or branch.
3. Running the specification test — use the spec-test workflow on a single file or directory to evaluate whether code belongs in its current layer.
4. Planning gradual adoption — generate a phased roadmap with the layerification plan workflow, focused on a goal like "introduce authorization" or "decompose god objects."
5. Planning a feature — I'll apply the layered principles below to whichever code you're about to write.
6. Implementing a specific pattern — authorization, notifications, view components, AI integration, etc. — see the Pattern Catalog and Topic References below.

In Claude Code with this skill installed as a plugin (/plugin install layered-rails@layered-rails-skills), each workflow above is also reachable as a slash command — see Slash Commands. Natural-language requests ("review this file with layered-rails", "run the specification test on app/models/order.rb") work in any environment that has the skill loaded.

Workflows

Reusable procedures bundled inside this skill. Read the file and apply it to the target code:

• Architecture analysis — full layered-architecture audit of a Rails codebase
• Code review — review a diff or file set for layer violations
• Specification test — evaluate whether code belongs in its current layer
• Service-layer audit — deep audit of app/services/ and service-like classes (per-cluster proposals, contracts, layer hygiene)
• Callback analysis — score Active Record callbacks and find extraction candidates
• God-object analysis — identify oversized models and recommend decomposition
• Gradual layerification plan — incremental roadmap for adopting layered patterns
• ArchSpec setup — generate and verify a tailored Archspec.rb enforcing the layer boundaries in CI

Core Principles

The Four Rules

1. Unidirectional Data Flow - Data flows top-to-bottom only
2. No Reverse Dependencies - Lower layers never depend on higher layers
3. Abstraction Boundaries - Each abstraction belongs to exactly one layer
4. Minimize Connections - Fewer inter-layer connections = looser coupling

Common Violations

The Specification Test

If the specification of an object describes features beyond the primary responsibility of its abstraction layer, such features should be extracted into lower layers.

How to apply:

1. List responsibilities the code handles
2. Evaluate each against the layer's primary concern
3. Extract misplaced responsibilities to appropriate layers

See Specification Test Reference for detailed guide.

Pattern Catalog

Pattern Selection Guide

"Where should this code go?"

Remember: Services are a "waiting room" for code until proper abstractions emerge. Don't let app/services become a bag of random objects.

Refactoring Scenarios

Canonical before/after transformations for the most common layerification moves. The layerification plan workflow uses these as reference templates when proposing phases.

Slash Commands

These slash commands are available only when this skill is installed as a Claude Code plugin (/plugin install layered-rails@layered-rails-skills). When the skill is installed via skills.sh or any other path that delivers skills/layered-rails/ without the surrounding plugin, the commands won't be present — invoke the corresponding workflow directly (see Workflows) or just ask in plain language.

Topic References

For deep dives on specific topics: