RailsCTO

Appearance

CLAUDE.md Wiring ​

Every Claude Code project has a CLAUDE.md file at the repo root. It's the durable instructions file — Claude Code loads it at the start of every session, so anything written there shapes the agent's behavior for the rest of the conversation.

RailsCTO relies on a small block in your CLAUDE.md to make its mandatory skills run automatically. The companion gem installs this block for you when you run rails-cto init.

What gets added ​

rails-cto init appends a block like this to your project's CLAUDE.md:

markdown
# Skills

When working on Ruby on Rails projects, always invoke `/rails-cto` at the
start of a session. It handles skill routing, QA gates, and the completion
checklist.

## Mandatory: After Modifying Any `.rb` File

Invoke `/rails-cto-qa` after every code change. A task is NOT done until QA
passes. Do not skip this even if the user doesn't mention it.

## Mandatory: After Modifying Any `.html.erb` File

Invoke `/rails-cto-erb` and `/rails-cto-tailwind` after every ERB change.
A task is NOT done until ERB and Tailwind checks pass. Do not skip this
even if the user doesn't mention it.

## Mandatory: Every Plan Must Include QA

When creating any implementation plan, always include `/rails-cto-qa` as a
final step. No plan is complete without a QA gate.

Why it exists ​

Claude Code skills are invoked by name (/rails-cto-qa, for example). Without instructions in CLAUDE.md, the agent wouldn't know to invoke the QA skill on its own — it would only run when you explicitly asked. The block above turns the implicit expectation ("run QA after Ruby changes") into an explicit, session-wide rule.

Each bullet point in the block is a hard enforcement:

  • /rails-cto at session start — loads the orchestrator, which then routes to the right specialized skill for whatever task comes next.
  • /rails-cto-qa after every .rb change — linting, tests, and code review. The QA gate is non-negotiable.
  • /rails-cto-erb and /rails-cto-tailwind after every .html.erb change — ERB formatting and Tailwind conventions.
  • Every plan must include QA — prevents the agent from drafting implementation plans that skip the quality gate.

Where it lives in the file ​

The block is appended to the end of your existing CLAUDE.md, so it doesn't overwrite anything you've already written. If you want to move it, that's fine — Claude Code reads the whole file regardless of order.

Customizing the block ​

The block is yours to edit once it's been installed. A few things people commonly tweak:

  • Adding project-specific rules — Drop your own instructions above or below the RailsCTO block.
  • Disabling a mandatory skill — If you have a reason to skip one (for example, you don't use Tailwind), you can delete its line. Be aware that the corresponding gate will stop enforcing itself.

Resetting the block ​

If you accidentally delete the block or want to reset it to the bundled template, re-run rails-cto init. It detects the missing block and re-appends it without touching the rest of the file. See rails-cto init for details.