@the-bearded-bear/claude-craft 9.0.0 → 9.1.0-next.fb00201
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Dev/i18n/base/Ruby/checklists/new-feature.md +113 -0
- package/Dev/i18n/base/Ruby/checklists/pre-commit.md +111 -0
- package/Dev/i18n/base/Ruby/checks/all.md +249 -0
- package/Dev/i18n/base/Ruby/checks/architecture.md +180 -0
- package/Dev/i18n/base/Ruby/checks/code-quality.md +179 -0
- package/Dev/i18n/base/Ruby/checks/security.md +183 -0
- package/Dev/i18n/base/Ruby/checks/testing.md +185 -0
- package/Dev/i18n/base/Ruby/commands/check.md +28 -0
- package/Dev/i18n/base/Ruby/rules/00-project-context.md.template +277 -0
- package/Dev/i18n/base/Ruby/templates/model.md +253 -0
- package/Dev/i18n/base/Ruby/templates/request-spec.md +273 -0
- package/Dev/i18n/base/Ruby/templates/service-object.md +212 -0
- package/Dev/i18n/de/Common/rules/12-context-management.md +1 -0
- package/Dev/i18n/de/Ruby/CLAUDE.md.template +92 -0
- package/Dev/i18n/de/Ruby/agents/ruby-reviewer.md +667 -0
- package/Dev/i18n/de/Ruby/checks/all.md +249 -0
- package/Dev/i18n/de/Ruby/commands/check.md +28 -0
- package/Dev/i18n/de/Ruby/rules/02-architecture-ruby.md +547 -0
- package/Dev/i18n/de/Ruby/rules/03-coding-standards.md +451 -0
- package/Dev/i18n/de/Ruby/rules/06-tooling.md +472 -0
- package/Dev/i18n/de/Ruby/rules/07-testing-ruby.md +542 -0
- package/Dev/i18n/de/Ruby/rules/08-quality-tools.md +397 -0
- package/Dev/i18n/de/Ruby/rules/11-security-ruby.md +566 -0
- package/Dev/i18n/en/Common/rules/12-context-management.md +1 -0
- package/Dev/i18n/en/Ruby/CLAUDE.md.template +92 -0
- package/Dev/i18n/en/Ruby/agents/ruby-reviewer.md +667 -0
- package/Dev/i18n/en/Ruby/checks/all.md +249 -0
- package/Dev/i18n/en/Ruby/commands/check.md +28 -0
- package/Dev/i18n/en/Ruby/rules/02-architecture-ruby.md +547 -0
- package/Dev/i18n/en/Ruby/rules/03-coding-standards.md +451 -0
- package/Dev/i18n/en/Ruby/rules/06-tooling.md +472 -0
- package/Dev/i18n/en/Ruby/rules/07-testing-ruby.md +542 -0
- package/Dev/i18n/en/Ruby/rules/08-quality-tools.md +397 -0
- package/Dev/i18n/en/Ruby/rules/11-security-ruby.md +566 -0
- package/Dev/i18n/es/Common/rules/12-context-management.md +1 -0
- package/Dev/i18n/es/Ruby/CLAUDE.md.template +92 -0
- package/Dev/i18n/es/Ruby/agents/ruby-reviewer.md +667 -0
- package/Dev/i18n/es/Ruby/checks/all.md +250 -0
- package/Dev/i18n/es/Ruby/commands/check.md +28 -0
- package/Dev/i18n/es/Ruby/rules/02-architecture-ruby.md +547 -0
- package/Dev/i18n/es/Ruby/rules/03-coding-standards.md +451 -0
- package/Dev/i18n/es/Ruby/rules/06-tooling.md +472 -0
- package/Dev/i18n/es/Ruby/rules/07-testing-ruby.md +542 -0
- package/Dev/i18n/es/Ruby/rules/08-quality-tools.md +397 -0
- package/Dev/i18n/es/Ruby/rules/11-security-ruby.md +566 -0
- package/Dev/i18n/fr/Common/rules/12-context-management.md +1 -0
- package/Dev/i18n/fr/Ruby/CLAUDE.md.template +92 -0
- package/Dev/i18n/fr/Ruby/agents/ruby-reviewer.md +667 -0
- package/Dev/i18n/fr/Ruby/checks/all.md +249 -0
- package/Dev/i18n/fr/Ruby/commands/check.md +28 -0
- package/Dev/i18n/fr/Ruby/rules/02-architecture-ruby.md +547 -0
- package/Dev/i18n/fr/Ruby/rules/03-coding-standards.md +451 -0
- package/Dev/i18n/fr/Ruby/rules/06-tooling.md +472 -0
- package/Dev/i18n/fr/Ruby/rules/07-testing-ruby.md +542 -0
- package/Dev/i18n/fr/Ruby/rules/08-quality-tools.md +397 -0
- package/Dev/i18n/fr/Ruby/rules/11-security-ruby.md +566 -0
- package/Dev/i18n/pt/Common/rules/12-context-management.md +1 -0
- package/Dev/i18n/pt/Ruby/CLAUDE.md.template +92 -0
- package/Dev/i18n/pt/Ruby/agents/ruby-reviewer.md +667 -0
- package/Dev/i18n/pt/Ruby/checks/all.md +249 -0
- package/Dev/i18n/pt/Ruby/commands/check.md +28 -0
- package/Dev/i18n/pt/Ruby/rules/02-architecture-ruby.md +547 -0
- package/Dev/i18n/pt/Ruby/rules/03-coding-standards.md +451 -0
- package/Dev/i18n/pt/Ruby/rules/06-tooling.md +472 -0
- package/Dev/i18n/pt/Ruby/rules/07-testing-ruby.md +542 -0
- package/Dev/i18n/pt/Ruby/rules/08-quality-tools.md +397 -0
- package/Dev/i18n/pt/Ruby/rules/11-security-ruby.md +566 -0
- package/Dev/scripts/check-config.sh +1 -1
- package/Dev/scripts/install-from-config.sh +3 -0
- package/Dev/scripts/install-ruby-rules.sh +155 -0
- package/Dev/stack-profiles/ruby/permissions.txt +4 -0
- package/Dev/stack-profiles/ruby/quality.md +3 -0
- package/Dev/stack-profiles/ruby/stack.txt +2 -0
- package/README.md +8 -3
- package/bundles/cursor/.cursorrules +4 -3
- package/bundles/windsurf/.windsurfrules +4 -3
- package/cli/lib/doctor.js +1 -1
- package/cli/lib/tech-registry.js +10 -0
- package/package.json +1 -1
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# New Feature Development Checklist - Ruby / Rails
|
|
2
|
+
|
|
3
|
+
## Before Starting
|
|
4
|
+
|
|
5
|
+
- [ ] Feature discussed and validated with the team
|
|
6
|
+
- [ ] Acceptance criteria written (Given/When/Then)
|
|
7
|
+
- [ ] Assumptions stated explicitly (inputs, invariants, volume, authorization)
|
|
8
|
+
- [ ] API contract defined if exposed (OpenAPI 3.x, error format RFC 9457)
|
|
9
|
+
- [ ] Database changes identified (tables, columns, indexes, constraints)
|
|
10
|
+
- [ ] Impact analysis done: files touched, breaking changes, rollback plan
|
|
11
|
+
- [ ] Feature flag decided for risky changes (Flipper or equivalent)
|
|
12
|
+
|
|
13
|
+
## Development (TDD: Red, Green, Refactor)
|
|
14
|
+
|
|
15
|
+
### Design (Rails Way first)
|
|
16
|
+
|
|
17
|
+
- [ ] Start with conventional Rails: model, `resources` route, RESTful controller, views
|
|
18
|
+
- [ ] New behavior modeled as a resource (`resources :refunds`) rather than a custom action
|
|
19
|
+
- [ ] Extract a service/form/query object only when a model or controller action grows unwieldy (YAGNI)
|
|
20
|
+
- [ ] No speculative abstractions, options, or parameters
|
|
21
|
+
|
|
22
|
+
### Model Layer
|
|
23
|
+
|
|
24
|
+
- [ ] Validations match database constraints (`null: false`, unique index, check constraint)
|
|
25
|
+
- [ ] Associations declare `dependent:` and `inverse_of` where needed
|
|
26
|
+
- [ ] Scopes are chainable and named for intent
|
|
27
|
+
- [ ] Enums defined with explicit values (`enum :status, { pending: 0, paid: 1 }`)
|
|
28
|
+
- [ ] Callbacks limited to data normalization; side effects in jobs or services
|
|
29
|
+
- [ ] Sensitive attributes encrypted (`encrypts :field`)
|
|
30
|
+
|
|
31
|
+
### Database
|
|
32
|
+
|
|
33
|
+
- [ ] Migration generated with `bin/rails generate migration` and is reversible
|
|
34
|
+
- [ ] Foreign keys and indexes on every reference
|
|
35
|
+
- [ ] Large-table changes done safely (concurrent index, backfill in a separate step)
|
|
36
|
+
- [ ] `db/schema.rb` committed
|
|
37
|
+
|
|
38
|
+
### Controller and Routes
|
|
39
|
+
|
|
40
|
+
- [ ] Only REST actions; thin actions (<= 10 lines)
|
|
41
|
+
- [ ] Strong parameters via `params.expect(...)` (Rails 8) or `require/permit`
|
|
42
|
+
- [ ] Authentication and authorization enforced; records loaded through the current user's scope
|
|
43
|
+
- [ ] `rate_limit` added on sensitive endpoints (login, password reset, expensive operations)
|
|
44
|
+
- [ ] Turbo-friendly responses (`redirect_to` with `status: :see_other` after mutations, `turbo_stream` where useful)
|
|
45
|
+
- [ ] Errors rendered consistently (422 for validation, 404 for missing, 403 for forbidden)
|
|
46
|
+
|
|
47
|
+
### Views and Hotwire
|
|
48
|
+
|
|
49
|
+
- [ ] Partials and components small and reusable; no logic in templates
|
|
50
|
+
- [ ] Turbo Frames/Streams used for partial updates before reaching for custom JavaScript
|
|
51
|
+
- [ ] Stimulus controllers small, one concern each
|
|
52
|
+
- [ ] Output escaped by default; no `html_safe` on user input
|
|
53
|
+
- [ ] Accessibility checked (labels, focus order, contrast)
|
|
54
|
+
- [ ] I18n keys used for user-visible text (`t(".title")`)
|
|
55
|
+
|
|
56
|
+
### Background Work
|
|
57
|
+
|
|
58
|
+
- [ ] Operations > 200 ms moved to Active Job
|
|
59
|
+
- [ ] Jobs idempotent, take GlobalID/IDs, declare `retry_on` / `discard_on`
|
|
60
|
+
- [ ] Queue configured (Solid Queue by default in Rails 8) and monitored
|
|
61
|
+
|
|
62
|
+
### Code Quality
|
|
63
|
+
|
|
64
|
+
- [ ] RuboCop passes (`bin/rubocop`)
|
|
65
|
+
- [ ] `# frozen_string_literal: true` in new files
|
|
66
|
+
- [ ] Naming explicit; comments explain WHY
|
|
67
|
+
- [ ] Types added if the project uses RBS/Steep or Sorbet, and the checker passes
|
|
68
|
+
|
|
69
|
+
## Testing
|
|
70
|
+
|
|
71
|
+
- [ ] Model tests: validations, associations, scopes, domain methods
|
|
72
|
+
- [ ] Service/form/query object tests: success and each failure path
|
|
73
|
+
- [ ] Request (integration) tests for every new endpoint, including unauthenticated and unauthorized cases
|
|
74
|
+
- [ ] System test (Capybara) for the main user journey
|
|
75
|
+
- [ ] Job and mailer tests where added
|
|
76
|
+
- [ ] Factories (or fixtures) added and minimal
|
|
77
|
+
- [ ] Coverage stays >= 80%; time frozen with `travel_to`; external HTTP stubbed
|
|
78
|
+
|
|
79
|
+
## Security
|
|
80
|
+
|
|
81
|
+
- [ ] Brakeman clean; bundler-audit clean
|
|
82
|
+
- [ ] No string interpolation in SQL; no `permit!`
|
|
83
|
+
- [ ] IDOR checked: users cannot reach other users' or tenants' records
|
|
84
|
+
- [ ] Secrets in credentials, not in code
|
|
85
|
+
- [ ] New logs do not contain sensitive data (`filter_parameters` updated)
|
|
86
|
+
|
|
87
|
+
## Performance
|
|
88
|
+
|
|
89
|
+
- [ ] No N+1 (`includes`, `preload`, `strict_loading`)
|
|
90
|
+
- [ ] Pagination on list endpoints (Pagy or Kaminari)
|
|
91
|
+
- [ ] Caching considered for hot reads (fragment cache, `Rails.cache.fetch`)
|
|
92
|
+
- [ ] Query plans checked for new heavy queries (`explain`)
|
|
93
|
+
|
|
94
|
+
## Documentation
|
|
95
|
+
|
|
96
|
+
- [ ] README or docs updated
|
|
97
|
+
- [ ] API documentation updated
|
|
98
|
+
- [ ] ADR written for significant decisions
|
|
99
|
+
- [ ] CHANGELOG entry added
|
|
100
|
+
|
|
101
|
+
## Before Merge
|
|
102
|
+
|
|
103
|
+
- [ ] `bin/ci` passes locally and in CI
|
|
104
|
+
- [ ] Self-review of the diff completed
|
|
105
|
+
- [ ] PR description explains the why, links the ticket, lists risks and rollback
|
|
106
|
+
- [ ] Reviewer approval received; squash merge with Conventional Commit title
|
|
107
|
+
|
|
108
|
+
## Deployment
|
|
109
|
+
|
|
110
|
+
- [ ] Migrations run before the new code starts (Kamal deploy hook or release step)
|
|
111
|
+
- [ ] Feature flag default set; rollback path verified
|
|
112
|
+
- [ ] Monitoring and alerts in place (error tracker, job queue depth)
|
|
113
|
+
- [ ] Smoke test after deploy (`/up` health check and the main flow)
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Pre-Commit Checklist - Ruby / Rails
|
|
2
|
+
|
|
3
|
+
## Quick Validation Before Each Commit
|
|
4
|
+
|
|
5
|
+
All commands run in Docker (`docker compose exec app ...`). The fastest full gate is `bin/ci` (Rails 8.1), which runs the steps defined in `config/ci.rb`.
|
|
6
|
+
|
|
7
|
+
### Code Quality
|
|
8
|
+
|
|
9
|
+
- [ ] RuboCop clean (`bin/rubocop`, or `bundle exec rubocop`)
|
|
10
|
+
- [ ] Auto-correct applied only for safe cops (`rubocop -a`) and the diff reviewed
|
|
11
|
+
- [ ] `# frozen_string_literal: true` present in new Ruby files
|
|
12
|
+
- [ ] No unused `require`, dead code, or commented-out code
|
|
13
|
+
- [ ] No `binding.irb`, `byebug`, `debugger`, `puts`, `pp` left behind
|
|
14
|
+
- [ ] Methods < 10 lines (limit 20), nesting <= 3, parameters <= 4
|
|
15
|
+
|
|
16
|
+
### Tests
|
|
17
|
+
|
|
18
|
+
- [ ] All tests pass (`bundle exec rspec` or `bin/rails test`)
|
|
19
|
+
- [ ] System tests pass for touched user journeys (`bin/rails test:system` or `bundle exec rspec spec/system`)
|
|
20
|
+
- [ ] New behavior has tests written first (Red, Green, Refactor)
|
|
21
|
+
- [ ] Bug fixes include a regression test that failed before the fix
|
|
22
|
+
- [ ] Coverage maintained at 80% or higher (SimpleCov)
|
|
23
|
+
- [ ] No skipped or pending tests added without a ticket
|
|
24
|
+
|
|
25
|
+
### Security
|
|
26
|
+
|
|
27
|
+
- [ ] Brakeman clean (`bin/brakeman --no-pager -q`)
|
|
28
|
+
- [ ] `bundle exec bundler-audit check --update` reports no advisories
|
|
29
|
+
- [ ] No hardcoded secrets; `config/master.key` and `.env` not staged
|
|
30
|
+
- [ ] Strong parameters on new controller actions (no `permit!`)
|
|
31
|
+
- [ ] No string interpolation in `where`, `order`, or raw SQL fragments
|
|
32
|
+
- [ ] No new `html_safe` / `raw` on user-provided data
|
|
33
|
+
- [ ] New actions authorized (and rate limited when they authenticate or send mail)
|
|
34
|
+
|
|
35
|
+
### Database
|
|
36
|
+
|
|
37
|
+
- [ ] Migration is reversible, has indexes and foreign keys, and `db/schema.rb` is updated
|
|
38
|
+
- [ ] No data backfill mixed into the schema migration
|
|
39
|
+
- [ ] `bin/rails db:migrate` then `db:rollback` then `db:migrate` works locally
|
|
40
|
+
- [ ] N+1 checked on new queries (`includes`, `preload`, `strict_loading`, Bullet)
|
|
41
|
+
|
|
42
|
+
### Dependencies
|
|
43
|
+
|
|
44
|
+
- [ ] `Gemfile.lock` committed and consistent (`bundle check`)
|
|
45
|
+
- [ ] New gems justified (maintained, license compatible, no overlap with Rails built-ins)
|
|
46
|
+
|
|
47
|
+
### Documentation and Git
|
|
48
|
+
|
|
49
|
+
- [ ] README / docs updated when behavior or setup changed
|
|
50
|
+
- [ ] CHANGELOG updated if applicable
|
|
51
|
+
- [ ] Commit message follows Conventional Commits (`feat(orders): add refund endpoint`)
|
|
52
|
+
- [ ] Commit is atomic; branch up to date with `main`
|
|
53
|
+
- [ ] No unrelated files staged (`git status`, `git diff --staged`)
|
|
54
|
+
|
|
55
|
+
## Automated Validation
|
|
56
|
+
|
|
57
|
+
### Rails 8.1 `bin/ci`
|
|
58
|
+
|
|
59
|
+
```ruby
|
|
60
|
+
# config/ci.rb
|
|
61
|
+
CI.run do
|
|
62
|
+
step "Setup", "bin/setup --skip-server"
|
|
63
|
+
step "Style: Ruby", "bin/rubocop"
|
|
64
|
+
step "Security: Gem audit", "bin/bundler-audit"
|
|
65
|
+
step "Security: Brakeman", "bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error"
|
|
66
|
+
step "Tests: Rails", "bin/rails test"
|
|
67
|
+
step "Tests: System", "bin/rails test:system"
|
|
68
|
+
end
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Run it in the container:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
docker compose exec app bin/ci
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Git pre-commit hook (Lefthook)
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
# lefthook.yml
|
|
81
|
+
pre-commit:
|
|
82
|
+
parallel: true
|
|
83
|
+
commands:
|
|
84
|
+
rubocop:
|
|
85
|
+
glob: "*.rb"
|
|
86
|
+
run: docker compose exec -T app bundle exec rubocop --force-exclusion {staged_files}
|
|
87
|
+
brakeman:
|
|
88
|
+
glob: "{app,config,lib}/**/*.rb"
|
|
89
|
+
run: docker compose exec -T app bin/brakeman --no-pager -q
|
|
90
|
+
pre-push:
|
|
91
|
+
commands:
|
|
92
|
+
tests:
|
|
93
|
+
run: docker compose exec -T app bin/rails test
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Replace `bin/rails test` with `bundle exec rspec` on RSpec projects. Hooks are requirements, CLAUDE.md is a suggestion.
|
|
97
|
+
|
|
98
|
+
## Quick Commands
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
docker compose exec app bin/rubocop -a
|
|
102
|
+
docker compose exec app bin/brakeman --no-pager -q
|
|
103
|
+
docker compose exec app bundle exec bundler-audit check --update
|
|
104
|
+
docker compose exec app bin/rails test # or: bundle exec rspec
|
|
105
|
+
docker compose exec app bin/rails zeitwerk:check
|
|
106
|
+
docker compose exec app bin/ci
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Final Check
|
|
110
|
+
|
|
111
|
+
If any box is unchecked, do not commit. Fix first, then re-run `bin/ci`.
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# Check Complete Ruby / Rails Compliance
|
|
2
|
+
|
|
3
|
+
## Arguments
|
|
4
|
+
|
|
5
|
+
$ARGUMENTS (optional: path to project to analyze)
|
|
6
|
+
|
|
7
|
+
## Plan Mode
|
|
8
|
+
|
|
9
|
+
> Plan mode is activated automatically when the scope spans multiple modules or requires cross-cutting investigation.
|
|
10
|
+
|
|
11
|
+
## MISSION
|
|
12
|
+
|
|
13
|
+
Perform a complete compliance audit of the Ruby on Rails project by orchestrating the 4 major checks: Architecture, Code Quality, Tests, and Security. Produce a consolidated report with an overall score out of 100 points.
|
|
14
|
+
|
|
15
|
+
### Step 1: Audit Preparation
|
|
16
|
+
|
|
17
|
+
Prepare audit environment:
|
|
18
|
+
- [ ] Identify project path to audit
|
|
19
|
+
- [ ] Verify presence of configuration files (`Gemfile`, `Gemfile.lock`, `.ruby-version`, `.rubocop.yml`, `config/application.rb`)
|
|
20
|
+
- [ ] List main directories (`app/`, `config/`, `db/`, `spec/` or `test/`, `lib/`)
|
|
21
|
+
- [ ] Identify Ruby and Rails versions
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
docker compose exec app ruby -v
|
|
25
|
+
docker compose exec app bin/rails -v
|
|
26
|
+
docker compose exec app bin/rails about
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Note**: If $ARGUMENTS provided, use it as project path, otherwise use current directory.
|
|
30
|
+
|
|
31
|
+
### Step 2: Architecture Audit (25 points)
|
|
32
|
+
|
|
33
|
+
Execute architecture check: `/ruby:check architecture` or follow `.claude/references/ruby/checks/architecture.md`
|
|
34
|
+
|
|
35
|
+
**Evaluated Criteria**:
|
|
36
|
+
- Rails conventions and directory layout (5 pts)
|
|
37
|
+
- Thin controllers (6 pts)
|
|
38
|
+
- Model design and extraction of service/form/query objects (6 pts)
|
|
39
|
+
- Data layer: migrations, constraints, N+1 (4 pts)
|
|
40
|
+
- Background jobs, caching, realtime (Solid Queue/Cache/Cable) (2 pts)
|
|
41
|
+
- Zeitwerk autoloading and dependency direction (2 pts)
|
|
42
|
+
|
|
43
|
+
**Reference**: `.claude/references/ruby/checks/architecture.md`
|
|
44
|
+
|
|
45
|
+
### Step 3: Code Quality Audit (25 points)
|
|
46
|
+
|
|
47
|
+
Execute code quality check: `/ruby:check code-quality` or follow `.claude/references/ruby/checks/code-quality.md`
|
|
48
|
+
|
|
49
|
+
**Evaluated Criteria**:
|
|
50
|
+
- RuboCop (rubocop-rails-omakase or project config) clean (6 pts)
|
|
51
|
+
- Idiomatic Ruby 4.0 (frozen string literals, pattern matching, keyword args) (5 pts)
|
|
52
|
+
- KISS/DRY/YAGNI and complexity (4 pts)
|
|
53
|
+
- Error handling (4 pts)
|
|
54
|
+
- Naming conventions and documentation (3 pts)
|
|
55
|
+
- Typing (RBS/Steep or Sorbet, optional) and dead code (3 pts)
|
|
56
|
+
|
|
57
|
+
**Reference**: `.claude/references/ruby/checks/code-quality.md`
|
|
58
|
+
|
|
59
|
+
### Step 4: Testing Audit (25 points)
|
|
60
|
+
|
|
61
|
+
Execute testing check: `/ruby:check testing` or follow `.claude/references/ruby/checks/testing.md`
|
|
62
|
+
|
|
63
|
+
**Evaluated Criteria**:
|
|
64
|
+
- Code coverage with SimpleCov, 80% minimum (7 pts)
|
|
65
|
+
- Model and object unit tests (6 pts)
|
|
66
|
+
- Request and integration tests (5 pts)
|
|
67
|
+
- System tests (Capybara) (3 pts)
|
|
68
|
+
- Factories/fixtures quality (2 pts)
|
|
69
|
+
- Test isolation and speed (2 pts)
|
|
70
|
+
|
|
71
|
+
**Reference**: `.claude/references/ruby/checks/testing.md`
|
|
72
|
+
|
|
73
|
+
### Step 5: Security Audit (25 points)
|
|
74
|
+
|
|
75
|
+
Execute security check: `/ruby:check security` or follow `.claude/references/ruby/checks/security.md`
|
|
76
|
+
|
|
77
|
+
**Evaluated Criteria**:
|
|
78
|
+
- Brakeman static analysis (6 pts)
|
|
79
|
+
- Dependency vulnerabilities (bundler-audit, Dependabot) (4 pts)
|
|
80
|
+
- Secrets and credentials management (4 pts)
|
|
81
|
+
- Authentication and authorization (4 pts)
|
|
82
|
+
- Injection, XSS and mass assignment prevention (4 pts)
|
|
83
|
+
- Secure configuration, headers, rate limiting (3 pts)
|
|
84
|
+
|
|
85
|
+
**Reference**: `.claude/references/ruby/checks/security.md`
|
|
86
|
+
|
|
87
|
+
### Step 6: Consolidation and Global Scoring
|
|
88
|
+
|
|
89
|
+
- [ ] Sum the 4 scores (max 100 points)
|
|
90
|
+
- [ ] Identify critical categories (<50%)
|
|
91
|
+
- [ ] List all critical cross-cutting issues
|
|
92
|
+
- [ ] Prioritize actions by impact/effort
|
|
93
|
+
- [ ] Produce final consolidated report
|
|
94
|
+
|
|
95
|
+
**Grading Scale**:
|
|
96
|
+
- 90-100: Excellent - Reference project
|
|
97
|
+
- 75-89: Very Good - Some minor improvements
|
|
98
|
+
- 60-74: Acceptable - Requires improvements
|
|
99
|
+
- 40-59: Insufficient - Major refactoring required
|
|
100
|
+
- 0-39: Critical - Complete overhaul necessary
|
|
101
|
+
|
|
102
|
+
### Step 7: Recommendations and Action Plan
|
|
103
|
+
|
|
104
|
+
- [ ] Identify top 3 priority actions across all categories
|
|
105
|
+
- [ ] Estimate effort (Low/Medium/High) and impact (Low/Medium/High) for each
|
|
106
|
+
- [ ] Propose implementation order
|
|
107
|
+
- [ ] Suggest quick wins (high impact/effort ratio)
|
|
108
|
+
|
|
109
|
+
**Version health** (reported in the executive summary, not scored):
|
|
110
|
+
- Ruby 4.0.x is current; Ruby 3.x is accepted but flag a migration plan.
|
|
111
|
+
- Rails 8.1 is supported until 2027-10-10. Rails 8.0 reaches end of life on 2026-11-07: flag it as a high-priority upgrade.
|
|
112
|
+
|
|
113
|
+
## OUTPUT FORMAT
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
RUBY / RAILS COMPLIANCE AUDIT - COMPLETE REPORT
|
|
117
|
+
=============================================
|
|
118
|
+
|
|
119
|
+
OVERALL SCORE: XX/100
|
|
120
|
+
|
|
121
|
+
COMPLIANCE LEVEL: [Excellent/Very Good/Acceptable/Insufficient/Critical]
|
|
122
|
+
|
|
123
|
+
Ruby: X.Y.Z Rails: X.Y.Z Test framework: [RSpec/Minitest]
|
|
124
|
+
|
|
125
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
126
|
+
|
|
127
|
+
SCORES BY CATEGORY:
|
|
128
|
+
|
|
129
|
+
ARCHITECTURE : XX/25 [██████████░░░░░░░░░░] XX%
|
|
130
|
+
CODE QUALITY : XX/25 [██████████░░░░░░░░░░] XX%
|
|
131
|
+
TESTS : XX/25 [██████████░░░░░░░░░░] XX%
|
|
132
|
+
SECURITY : XX/25 [██████████░░░░░░░░░░] XX%
|
|
133
|
+
|
|
134
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
135
|
+
|
|
136
|
+
OVERALL STRENGTHS:
|
|
137
|
+
1. [Strength identified in multiple categories]
|
|
138
|
+
2. [Other major strength]
|
|
139
|
+
3. [Third strength]
|
|
140
|
+
|
|
141
|
+
OVERALL IMPROVEMENTS:
|
|
142
|
+
1. [Cross-cutting improvement]
|
|
143
|
+
2. [Other recommended improvement]
|
|
144
|
+
3. [Third improvement]
|
|
145
|
+
|
|
146
|
+
CRITICAL ISSUES:
|
|
147
|
+
1. [Critical issue #1 - affected category]
|
|
148
|
+
2. [Critical issue #2 - affected category]
|
|
149
|
+
3. [Critical issue #3 - affected category]
|
|
150
|
+
|
|
151
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
152
|
+
|
|
153
|
+
DETAILS BY CATEGORY:
|
|
154
|
+
|
|
155
|
+
┌─────────────────────────────────────────────┐
|
|
156
|
+
│ ARCHITECTURE (XX/25) │
|
|
157
|
+
└─────────────────────────────────────────────┘
|
|
158
|
+
|
|
159
|
+
Sub-scores:
|
|
160
|
+
• Rails conventions / layout : XX/5
|
|
161
|
+
• Thin controllers : XX/6
|
|
162
|
+
• Model design / extraction : XX/6
|
|
163
|
+
• Data layer : XX/4
|
|
164
|
+
• Jobs, cache, realtime : XX/2
|
|
165
|
+
• Autoloading / dependencies : XX/2
|
|
166
|
+
|
|
167
|
+
Strengths:
|
|
168
|
+
- [Architecture strengths]
|
|
169
|
+
|
|
170
|
+
Issues:
|
|
171
|
+
- [Architecture issues]
|
|
172
|
+
|
|
173
|
+
[Similar sections for Code Quality, Tests, and Security...]
|
|
174
|
+
|
|
175
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
176
|
+
|
|
177
|
+
TOP 3 PRIORITY ACTIONS (ALL CATEGORIES):
|
|
178
|
+
|
|
179
|
+
1. CRITICAL - [Action #1]
|
|
180
|
+
Category : [Architecture/Quality/Tests/Security]
|
|
181
|
+
Impact : [High/Medium/Low]
|
|
182
|
+
Effort : [High/Medium/Low]
|
|
183
|
+
Priority : IMMEDIATE
|
|
184
|
+
|
|
185
|
+
Detailed description:
|
|
186
|
+
[Explanation of problem and proposed solution]
|
|
187
|
+
|
|
188
|
+
Affected files:
|
|
189
|
+
- [file:line]
|
|
190
|
+
|
|
191
|
+
Correction example:
|
|
192
|
+
[Code or correction command]
|
|
193
|
+
|
|
194
|
+
2. IMPORTANT - [Action #2]
|
|
195
|
+
[Same format...]
|
|
196
|
+
|
|
197
|
+
3. RECOMMENDED - [Action #3]
|
|
198
|
+
[Same format...]
|
|
199
|
+
|
|
200
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
201
|
+
|
|
202
|
+
QUICK WINS (High Impact / Low Effort):
|
|
203
|
+
|
|
204
|
+
- [Quick win #1] - Category: [X] - Impact: [X] - Effort: [X]
|
|
205
|
+
- [Quick win #2] - Category: [X] - Impact: [X] - Effort: [X]
|
|
206
|
+
- [Quick win #3] - Category: [X] - Impact: [X] - Effort: [X]
|
|
207
|
+
|
|
208
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
209
|
+
|
|
210
|
+
RECOMMENDED ACTION PLAN:
|
|
211
|
+
|
|
212
|
+
WEEK 1 (Immediate):
|
|
213
|
+
- [ ] [Critical action #1]
|
|
214
|
+
- [ ] [Priority quick win]
|
|
215
|
+
|
|
216
|
+
WEEK 2-4 (Short term):
|
|
217
|
+
- [ ] [Important action #2]
|
|
218
|
+
- [ ] [Other quick wins]
|
|
219
|
+
|
|
220
|
+
MONTH 2-3 (Medium term):
|
|
221
|
+
- [ ] [Recommended action #3]
|
|
222
|
+
- [ ] [Progressive improvements]
|
|
223
|
+
|
|
224
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
225
|
+
|
|
226
|
+
EXECUTIVE SUMMARY:
|
|
227
|
+
|
|
228
|
+
[Summary paragraph on overall project state, major strengths,
|
|
229
|
+
major weaknesses, version health (Ruby/Rails support status), and
|
|
230
|
+
recommended trajectory. Say whether the project is production-ready,
|
|
231
|
+
requires corrections, or needs refactoring.]
|
|
232
|
+
|
|
233
|
+
General Recommendation: [Production-ready / Minor corrections /
|
|
234
|
+
Major refactoring / Overhaul necessary]
|
|
235
|
+
|
|
236
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## IMPORTANT NOTES
|
|
240
|
+
|
|
241
|
+
- This command orchestrates the 4 specialized audits
|
|
242
|
+
- Use Docker for all analysis tools (`docker compose exec app ...`)
|
|
243
|
+
- Provide concrete examples with file:line for each problem
|
|
244
|
+
- Prioritize actions based on Impact/Effort matrix
|
|
245
|
+
- Security problems are ALWAYS top priority
|
|
246
|
+
- Rails Way first: do not penalize a project for lacking hexagonal layering
|
|
247
|
+
- Propose automatable corrections (`bin/ci`, pre-commit hooks, GitHub Actions)
|
|
248
|
+
- Report must be actionable, not just descriptive
|
|
249
|
+
- Adapt recommendations to project business context
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Check Ruby / Rails Architecture
|
|
2
|
+
|
|
3
|
+
## Arguments
|
|
4
|
+
|
|
5
|
+
$ARGUMENTS (optional: path to project to analyze)
|
|
6
|
+
|
|
7
|
+
## Plan Mode
|
|
8
|
+
|
|
9
|
+
> Plan mode is activated automatically when the scope spans multiple modules or requires cross-cutting investigation.
|
|
10
|
+
|
|
11
|
+
## MISSION
|
|
12
|
+
|
|
13
|
+
Audit the architecture of the Rails application (Rails 8.1, Ruby 4.0). Stance: **Rails Way first**. Conventions are the default architecture; extract service, form, query or policy objects only when a model or controller grows beyond a readable size ("pragmatic Clean"). Hexagonal layering is NOT required and must not be scored.
|
|
14
|
+
|
|
15
|
+
All commands run in Docker (`docker compose exec app ...`).
|
|
16
|
+
|
|
17
|
+
### Step 1: Project Structure (5 points)
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
docker compose exec app ls app/ config/ db/ lib/
|
|
21
|
+
docker compose exec app bin/rails about
|
|
22
|
+
docker compose exec app bin/rails stats
|
|
23
|
+
docker compose exec app bin/rails routes --unused | head -50
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Checklist:
|
|
27
|
+
- [ ] Standard Rails layout (`app/models`, `app/controllers`, `app/views`, `app/jobs`, `app/mailers`)
|
|
28
|
+
- [ ] Extra objects live under `app/` (for example `app/services`, `app/queries`, `app/forms`, `app/policies`) so Zeitwerk autoloads them
|
|
29
|
+
- [ ] No business code in `lib/` unless it is a genuinely framework-independent library
|
|
30
|
+
- [ ] `config/routes.rb` uses `resources` and shallow nesting (max 1 level)
|
|
31
|
+
- [ ] Rails 8 defaults respected unless a documented ADR says otherwise (Propshaft, importmap or a JS bundler, Solid Queue/Cache/Cable, Kamal)
|
|
32
|
+
|
|
33
|
+
Detect anti-patterns:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
# Non-RESTful custom routes
|
|
37
|
+
docker compose exec app grep -nE "^\s*(get|post|put|patch|delete) " config/routes.rb | head -30
|
|
38
|
+
# Deep nesting
|
|
39
|
+
docker compose exec app grep -nE "resources .* do" config/routes.rb
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**Scoring**: 5 pts, minus 1 per violation (min 0).
|
|
43
|
+
|
|
44
|
+
### Step 2: Thin Controllers (6 points)
|
|
45
|
+
|
|
46
|
+
Controllers coordinate: authenticate, authorize, load, call, respond. No business rules.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
# Largest controllers
|
|
50
|
+
docker compose exec app sh -c 'find app/controllers -name "*.rb" | xargs wc -l | sort -rn | head -10'
|
|
51
|
+
# Query building or business logic in controllers
|
|
52
|
+
docker compose exec app grep -rnE "\.(where|joins|includes|group|order)\(" app/controllers | head -30
|
|
53
|
+
# Transactions or bulk writes in controllers
|
|
54
|
+
docker compose exec app grep -rnE "transaction do|\.update_all|\.delete_all" app/controllers | head
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Checklist:
|
|
58
|
+
- [ ] Actions are <= 10 lines (target 7)
|
|
59
|
+
- [ ] Only the 7 REST actions per controller; extra behavior becomes a new resource controller
|
|
60
|
+
- [ ] Strong parameters (`params.expect` on Rails 8, or `require(...).permit(...)`) in a private method
|
|
61
|
+
- [ ] Authorization on every action (`before_action`, Pundit, CanCanCan or equivalent)
|
|
62
|
+
- [ ] Concerns used for cross-cutting behavior only, not as a dumping ground
|
|
63
|
+
- [ ] `respond_to` / Turbo Stream responses handled explicitly
|
|
64
|
+
|
|
65
|
+
**Scoring**: 6 pts. Deduct 1 per controller with an action > 15 lines or query-building logic, max -6.
|
|
66
|
+
|
|
67
|
+
### Step 3: Model Design and Object Extraction (6 points)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
docker compose exec app sh -c 'find app/models -name "*.rb" | xargs wc -l | sort -rn | head -10'
|
|
71
|
+
docker compose exec app grep -rnE "^\s*(before|after|around)_(save|create|update|destroy|commit)" app/models | wc -l
|
|
72
|
+
docker compose exec app grep -rnE "Net::HTTP|Faraday|HTTParty|deliver_" app/models | head
|
|
73
|
+
docker compose exec app ls app/services app/queries app/forms app/policies
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Checklist:
|
|
77
|
+
- [ ] Models contain associations, validations, scopes, and domain behavior; no HTTP calls or mail delivery in callbacks
|
|
78
|
+
- [ ] Callbacks limited to data normalization; side effects moved to jobs or service objects
|
|
79
|
+
- [ ] Models over 200 lines have extracted concerns (cohesive) or objects
|
|
80
|
+
- [ ] Service objects have a single public method (`call`), return a result, no hidden state
|
|
81
|
+
- [ ] Form objects (`ActiveModel::Model`) for multi-model forms
|
|
82
|
+
- [ ] Query objects or scopes for complex reads; no raw SQL fragments scattered across controllers
|
|
83
|
+
- [ ] Enums and value types declared with `enum` / `attribute` rather than magic strings
|
|
84
|
+
- [ ] No God objects: a class named `Manager`, `Helper` or `Processor` with many unrelated methods is a smell
|
|
85
|
+
|
|
86
|
+
**Scoring**: 6 pts. Deduct 1 per god model (> 400 lines), 1 per side-effect callback pattern, 1 per service with more than one responsibility.
|
|
87
|
+
|
|
88
|
+
### Step 4: Data Layer (4 points)
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
docker compose exec app bin/rails db:migrate:status | tail -20
|
|
92
|
+
docker compose exec app grep -cE "add_foreign_key|add_index|null: false" db/schema.rb
|
|
93
|
+
# N+1 detection tooling
|
|
94
|
+
docker compose exec app grep -nE "bullet|prosopite|strong_migrations" Gemfile
|
|
95
|
+
# Foreign key columns (verify each has an index and a foreign key)
|
|
96
|
+
docker compose exec app grep -nE "_id\"" db/schema.rb | head -30
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Checklist:
|
|
100
|
+
- [ ] Every `_id` column has an index and a database foreign key
|
|
101
|
+
- [ ] `null: false`, unique indexes and check constraints mirror model validations
|
|
102
|
+
- [ ] Migrations are reversible and safe (`strong_migrations` if used); no data backfill inside schema migrations
|
|
103
|
+
- [ ] `schema.rb` (or `structure.sql`) committed and in sync (`bin/rails db:migrate` produces no diff)
|
|
104
|
+
- [ ] N+1 prevented via `includes` / `preload` / `strict_loading`; Bullet or Prosopite in development/test
|
|
105
|
+
- [ ] Multi-row writes wrapped in `transaction`; optimistic locking (`lock_version`) where concurrent edits matter
|
|
106
|
+
- [ ] Rails 8 Solid databases (`queue`, `cache`, `cable`) configured in `config/database.yml` when used
|
|
107
|
+
|
|
108
|
+
**Scoring**: 4 pts, minus 1 per failed group above (integrity, migrations, N+1, transactions).
|
|
109
|
+
|
|
110
|
+
### Step 5: Jobs, Cache, Realtime (2 points)
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
docker compose exec app ls app/jobs
|
|
114
|
+
docker compose exec app grep -rnE "queue_adapter|solid_queue|solid_cache|solid_cable" config
|
|
115
|
+
docker compose exec app grep -rnE "perform_later|deliver_later" app | wc -l
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Checklist:
|
|
119
|
+
- [ ] Anything slower than ~200 ms in a request is moved to Active Job (`perform_later`)
|
|
120
|
+
- [ ] Jobs are idempotent and take IDs or GlobalID, not large serialized objects
|
|
121
|
+
- [ ] Retry policy declared (`retry_on`, `discard_on`); failures are observable
|
|
122
|
+
- [ ] Production queue/cache/cable backend configured (Solid Queue/Cache/Cable by default in Rails 8)
|
|
123
|
+
- [ ] Fragment caching or `Rails.cache.fetch` with explicit keys and expiry on hot paths
|
|
124
|
+
|
|
125
|
+
**Scoring**: 2 pts (1 for jobs hygiene, 1 for caching/realtime config).
|
|
126
|
+
|
|
127
|
+
### Step 6: Autoloading and Dependency Direction (2 points)
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
docker compose exec app bin/rails zeitwerk:check
|
|
131
|
+
docker compose exec app grep -rnE "^\s*(require|require_relative) " app | head
|
|
132
|
+
docker compose exec app grep -rnE "ENV\[" app/models | head
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Checklist:
|
|
136
|
+
- [ ] `bin/rails zeitwerk:check` passes ("All is good!")
|
|
137
|
+
- [ ] No `require` / `require_relative` of application files inside `app/`
|
|
138
|
+
- [ ] Models do not depend on controllers or request state; `Current` attributes used sparingly
|
|
139
|
+
- [ ] Engines or namespaces (`app/models/billing/...`) delimit large domains; cross-domain calls go through public methods
|
|
140
|
+
- [ ] Configuration read through `Rails.configuration` / `config_for` / credentials, not scattered `ENV[]`
|
|
141
|
+
|
|
142
|
+
**Scoring**: 2 pts (1 for Zeitwerk, 1 for dependency direction).
|
|
143
|
+
|
|
144
|
+
## OUTPUT FORMAT
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
RUBY / RAILS ARCHITECTURE AUDIT
|
|
148
|
+
===============================
|
|
149
|
+
|
|
150
|
+
SCORE: XX/25
|
|
151
|
+
|
|
152
|
+
Rails: X.Y.Z Ruby: X.Y.Z Models: N Controllers: N Service objects: N
|
|
153
|
+
|
|
154
|
+
SUB-SCORES:
|
|
155
|
+
Structure and conventions : XX/5
|
|
156
|
+
Thin controllers : XX/6
|
|
157
|
+
Model design / extraction : XX/6
|
|
158
|
+
Data layer : XX/4
|
|
159
|
+
Jobs, cache, realtime : XX/2
|
|
160
|
+
Autoloading / dependencies : XX/2
|
|
161
|
+
|
|
162
|
+
STRENGTHS:
|
|
163
|
+
- [...]
|
|
164
|
+
|
|
165
|
+
ISSUES (by severity):
|
|
166
|
+
- CRITICAL: [file:line] [description] -> [fix]
|
|
167
|
+
- IMPORTANT: ...
|
|
168
|
+
- MINOR: ...
|
|
169
|
+
|
|
170
|
+
RECOMMENDATIONS:
|
|
171
|
+
1. [Action] (effort: Low/Medium/High, impact: Low/Medium/High)
|
|
172
|
+
2. ...
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## IMPORTANT NOTES
|
|
176
|
+
|
|
177
|
+
- Findings must cite `file:line` and propose a concrete refactoring (for example "extract an `Orders::Place` service from `OrdersController#create`")
|
|
178
|
+
- Do not recommend new abstractions when the code is small and readable (YAGNI)
|
|
179
|
+
- Fat models are acceptable when cohesive; split by responsibility, not by line count alone
|
|
180
|
+
- Never run destructive tasks (`db:drop`, `db:reset`) during an audit
|