Tuning agent instructions

What's worth putting in it

You don't need a long document. Aim for the things an agent would otherwise guess at — and write down what it gets you.

State your stack in a line

Name your framework version, how authentication works, and your database. The agent stops assuming defaults — it won't reach for the wrong auth library or the wrong database.

Say how to run tests, lint, and CI

Spell out the commands and that work isn't done until they're green. The agent verifies its own changes instead of handing back code it never ran.

List the traps that bite in your stack

Capture the non-obvious failures you've already hit. The agent steps around them instead of rediscovering each one the hard way.

Pin the conventions you care about

Note your testing style, error-message voice, and patterns to avoid. Output matches your house style on the first pass, with fewer review round-trips.

Point at your knowledge and docs

Link to where decisions live and the reference docs that matter. The agent reads existing context before inventing a new pattern.

Say which plugin owns which area

Tell the agent to lean on the specialized plugins below for their domains. The right reviewer looks at the matching code.

Recommended plugins for Rails

Maquina publishes a set of Claude Code plugins that teach agents Rails conventions. Not every one fits every app — install by your stack.

A new app on the full Maquina stack benefits from all four. An existing app should pick by what it actually uses.

Full descriptions, the companion MCP servers, and setup guidance live in the AI Tools documentation.

Installing them

Add the marketplace once, then install the plugins you want. These run in Claude Code:

/plugin marketplace add maquina-app/rails-claude-code
/plugin install rails-simplifier@maquina
/plugin install maquina-ui-standards@maquina
/plugin install better-stimulus@maquina
/plugin install recuerd0@maquina

To share the same plugins across a team, commit them to your repository's .claude/settings.json instead:

{
  "extraKnownMarketplaces": {
    "maquina": {
      "source": { "source": "github", "repo": "maquina-app/rails-claude-code" }
    }
  },
  "enabledPlugins": [
    "rails-simplifier@maquina",
    "maquina-ui-standards@maquina",
    "better-stimulus@maquina",
    "recuerd0@maquina"
  ]
}

Put them to work in your instructions

## Code conventions
Before marking work done, have the matching subagent
review the code you changed:
- rails-simplifier:simplify — Ruby and Rails
- maquina-ui-standards:ui — views, forms, design tokens
- better-stimulus:better-stimulus — Stimulus controllers
Apply their findings; don't restate their rules here.

## Definition of done
1. Run your tests and linter until green; fix at the source.
2. Have the subagents above review the changed code, then re-run.
3. Save key decisions and gotchas with recuerd0:remember.

## Project knowledge
Use recuerd0:remember to save decisions, gotchas, and
preferences as they come up, and search your saved memories
before assuming or inventing a new pattern.

Claude Code reads this file as guidance, not hard rules, so keep it lean and specific. Trim these to your stack — drop the maquina-ui-standards or better-stimulus line if your app doesn't use them, and rename the sections to match how you already write the file.

Keep a knowledge base