rails_api_base: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

Rootstrap's Rails API template — a Rails 8.1 / Ruby 4.0 boilerplate for JSON APIs. It is meant to be cloned and renamed via bin/bootstrap.sh --name=<project>, which seds rails_api_base to your project name across the codebase. The template ships with two parallel surfaces:

• A JSON API under /api/v1/* (devise_token_auth, Pundit, Jbuilder, OpenAPI docs).
• An admin web surface built on ActiveAdmin at /admin/*, with sub-mounts for Flipper (/admin/feature-flags) and GoodJob (/admin/background-jobs).

Common commands

The bin/* wrappers transparently dispatch to Docker (docker compose) when DOCKER_ENABLED=true in .env, otherwise run locally. Use them rather than calling bundle/rails/rspec directly so the same invocation works in both modes.

• bin/dev — start Rails + JS/CSS bundling watchers (foreman / Procfile.dev). Defaults to port 3000.
• bin/rspec [path] — run specs. bin/rspec . runs everything. bin/rspec spec/path/to_spec.rb:42 runs a single example. Pass -rm / --remove-containers to tear down docker test services after the run.
• bin/rails … — any Rails command (bin/rails console, bin/rails db:migrate, …).
• bin/bundle … — bundler commands.
• bin/web <cmd> — arbitrary shell command inside the app container/environment.
• bundle exec rails code:analysis — runs the full lint suite: Brakeman, RuboCop, Reek, rails_best_practices, i18n-tasks (see lib/tasks/code_analysis.rake). Use this before opening a PR.
• bundle exec annotaterb models — refresh schema annotations on models (config in .annotaterb.yml).
• yarn build:js --watch / yarn build:css --watch — JS/CSS bundling for ActiveAdmin assets (already wired into bin/dev).

Testing notes

• Specs require a running Postgres (see docker-compose.yml / docker-compose.test.yml). .env.test provides test DB config.
• bin/rspec headed by default; set HEADLESS=true for headless feature specs.
• spec/rails_helper.rb wires several behaviors that affect how to write specs:
  • Prosopite scans every example for N+1 queries — fix the query, don't silence it.
  • rspec-retry retries failed examples (2x in CI via ENV['CI'], 1x locally). Don't paper over flakes by adding retries.
  • SimpleCov is started before Rails loads; coverage lands in coverage/.
  • Flipper resets to a memory adapter before each test, so feature-flag state is per-example. Enable in a before block.
  • Files under spec/forms/ are auto-tagged type: :form and get Shoulda matchers.
  • Files under spec/requests/api/ are picked up by rspec-openapi for API doc generation; other request specs are tagged openapi: false.
• OpenAPI doc generation is triggered by OPENAPI=1 (CI only on main / changes to spec/requests/api/**). Docs are served at /api-docs (basic auth: SWAGGER_USERNAME / SWAGGER_PASSWORD).