Skip to content

docs: add layered-rails guidance to README and AGENTS.md #2709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mroderick merged 1 commit into from
Jul 15, 2026
+28 −0
Merged

docs: add layered-rails guidance to README and AGENTS.md #2709

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,14 @@ end
```


### For planning agents

When planning new features or architectural changes, use the `layered-rails` skill for analysis:
- `/layered-rails:plan` — plan incremental adoption of layered patterns
- `/layered-rails:analyze` — full codebase architecture analysis
- `/layered-rails:review` — review code from a layered architecture perspective
- `/layered-rails:spec-test` — apply the specification test to evaluate layer placement

## Important Patterns

### Controllers
Expand Down
20 changes: 20 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,26 @@ If you prefer Docker, see the commands in `bin/d*`:

We use Bootstrap 5. Documentation: https://getbootstrap.com/docs/5.2/getting-started/introduction/

## Architectural approach

This project follows layered architecture principles as described in *[Layered Design for Ruby on Rails Applications](https://www.packtpub.com/en-us/product/layered-design-for-ruby-on-rails-applications-9781806114221)* by Vladimir Dementyev. The goal is to organise code into four layers with strict unidirectional dependencies:

| Layer | Responsibility | Key directories |
|-------|---------------|-----------------|
| **Presentation** | HTTP/WebSocket concerns | `app/controllers/`, `app/views/`, `app/mailers/` |
| **Application** | Orchestration, coordination | `app/services/`, `app/form_models/`, `app/policies/` |
| **Domain** | Business logic, rules | `app/models/`, `app/models/concerns/` |
| **Infrastructure** | Persistence, external APIs | Active Record models, external service clients |

**Guidelines for contributors:**
- Keep controllers thin — they should only handle HTTP concerns (params, session, response format)
- Put business logic in domain models, not services (services orchestrate, they don't own logic)
- Don't reference `Current` attributes from models — pass values explicitly
- Extract reusable queries into query objects, complex view logic into presenters
- Use form objects for multi-model forms or complex validation

AGENTS.md also references these patterns in its *For planning agents* section.

## Finding something to work on

You can pick one of the open [issues](https://github.com/codebar/planner/issues), fix a bug, improve the interface, refactor the code or improve test coverage!
Expand Down