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:

# 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.