rails-conventions

Files (27)

• LICENSE.txt
• README.md
• SKILL.md
• STYLE.md
• openai.yaml · agents/
• 01-baseline-rails-8.md · references/
• 02-naming-and-structure.md · references/
• 03-models-and-data.md · references/
• 03a-active-record-postgresql.md · references/
• 04-controllers-and-params.md · references/
• 05-routes-rest-and-resources.md · references/
• 06-hotwire-turbo-stimulus.md · references/
• 07-background-jobs-overview.md · references/
• 07a-background-jobs-good_job.md · references/
• 07b-background-jobs-solid_queue.md · references/
• 08-performance-caching-and-db.md · references/
• 09-security-checklist.md · references/
• 10-testing-strategy.md · references/
• 11-api-mode-and-serialization.md · references/
• 12-37signals-inspired-profile.md · references/
• 13-code-quality-gates.md · references/
• 14-webhooks.md · references/
• 15-maintenance-and-documentation.md · references/
• 16-mailers.md · references/
• 17-debugging-and-verification.md · references/
• 18-skill-evaluation.md · references/
• validate_skill.rb · scripts/

SKILL.md (first lines)

# Rails Convention Engineer

Follow this workflow and load only the references needed for the task.

## Execution Workflow

1. Inspect the codebase before proposing changes. For application code changes,
   including tests, always load `STYLE.md` before editing.
2. Preserve existing contracts and formatting; use verified native APIs for new
   code rather than copying deprecated patterns from nearby examples.
3. Check existing app, Ruby, Rails, and installed gem APIs before adding custom
   code. Follow the native API discovery gate below.
4. Define the observable result and cheapest adequate check before changing
   behavior. For bugs, follow `references/17-debugging-and-verification.md`.
5. Work in small, reversible units. Verify each coherent unit before building
   on it; reuse existing generators and automation before writing a new tool.
6. Report tradeoffs explicitly when choosing architecture.
7. Verify version-sensitive APIs against official Ruby, Rails, or gem docs before
   changing guidance or introducing new APIs.
8. Create generator-owned files only by running the generator — never invent them.
9. Before handoff, perform the Final Diff Review below on the code actually
   changed, then run the relevant checks on the final candidate.

Proceed with authorized, reversible work using facts discoverable from the repo
and runtime. Ask for unresolved product decisions or required approval; keep
independent work moving while those decisions are pending. Classify failed
checks before changing code, and report unavailable or inconclusive evidence
explicitly. Repository deployment and other approval boundaries remain binding.

## Final Diff Review

For every application code change, re-read the final diff, including staged and
unstaged changes and new files. Review the full task patch against its actual
base, not only the last edit or commit. Follow relevant callers and contracts;
keep unrelated pre-existing code outside cleanup scope.

Apply `STYLE.md`'s generated-code review criteria:

- Remove forwarding-only wrappers, redundant layers, and unnecessary `*Service`
  names; a rename alone does not justify an abstraction.
- Remove defensive fallbacks that conceal broken internal contracts, broad
  exception swallowing, and compatibility branches for unsupported runtimes.
- Remove comments that narrate the code; preserve contracts, invariants,
  security assumptions, and non-obvious reasons.
- Use the canonical term consistently across the changed call chain, and remove
  obsolete internal paths once all supported callers have migrated.
- Verify generator provenance for new generator-owned files and review tests
  for stubbing the operation or asserting implementation details.

Resolve violations before declaring the work ready. A legitimate exception
needs a concrete supported contract or framework requirement in the handoff,
not an inline suppression or blanket claim that a search found no hits. These
are contextual review criteria, not a universal regex ban. The packaging
validator cannot establish that this pass happened or that the code is correct.

## Runtime Baseline And Native API Discovery

Ruby 4.0 and Rails 8.1 are the minimum baseline for new applications and upgrade
work. Select current stable releases at or above that baseline from official
release pages; exclude previews, release candidates, and unreleased main-branch
APIs. Keep exact versions in the project's runtime configuration and lockfile.
Load `references/01-baseline-rails-8.md` for runtime or compatibility decisions.

For existing applications, establish the pinned Ruby, Rails, and relevant gem
versions before implementation. Use modern supported APIs available in those
versions. If below the baseline, report the gap and keep runtime upgrades a
separate explicit scope; do not silently upgrade or introduce unsupported APIs.

Before adding a helper, wrapper, concern, utility, extension, dependency, or
compatibility implementation:

1. Search the app and installed libraries for an existing owner of the behavior.
2. Check Ruby core/stdlib, Active Support, and the relevant Rails/gem APIs for
   the required behavior, including APIs introduced before the current release.
   Inspect installed source or version-matched official docs; do not rely on
   memory or unversioned documentation alone.
3. Reuse the native API directly when its contract fits. Local examples guide
   composition and formatting; they do not justify duplicating a supported API
   or copying deprecated framework patterns into new code.
4. Add custom code only for a demonstrated contract gap. Explain that gap and
   the API considered in the review handoff. Do not wrap a native call merely
   to rename it, and do not add feature-detection fallbacks for versions the
   project does not support.

During review, search for equivalent native APIs before accepting newly added
infrastructure code. Verify behavior and relevant edge cases, not just matching
method names. Newer APIs are preferred when they simplify the implementation and
preserve its contract; novelty alone is not a reason to rewrite working code.

## Non-Negotiable Rails Defaults

Rails applications should look like Rails applications. Prefer the framework's
native resource, model, controller, job, mailer, and view boundaries before
introducing extra architectural layers. Avoid architecture borrowed from other
ecosystems when Rails already has a direct convention for the problem.

Official Rails guides, official gem documentation, and established local app
conventions outrank style profiles. Follow the repository's configured formatter
and linter for layout; do not add suppression comments or change lint rules
solely to satisfy this skill's style examples. Use 37signals-inspired guidance as taste
guidance, not as authority over the current app or current Rails APIs.

Classes and modules must earn their place. Choose the fewest concepts, files,
and lines of code that keep the behavior clear. Do not add wrappers, aliases,
facades, or parallel abstractions whose main purpose is naming, indirection, or
making tests easier.

Keep one owner per behavior and one owner per definition. Prompts, schemas,
enums, constants, validation rules, normalization logic, and domain terminology
must each have a canonical home.

Identifier names must state ownership. `id` and `uuid` are owned by the local
application. `eid` means an identifier owned by another application or provider
and stored locally. Never alias a local `id` or `uuid` as `eid`. Use a qualified
name such as `place_eid`, `listing_eid`, or `review_eid` when a record can carry
identifiers from more than one external owner. A local identifier becomes an
`*_eid` only in the consuming system, never in its owning system.

Every Rails project should maintain a domain terminology document, usually

From ethos-link/rails-conventions, MIT.