Yes, you read that right. This entire agent system—the coordinator, the specialized agents, the 40 modular skills, the test framework, even this README—was architected, implemented, and refined by Claude. An AI building AI tools to help AI build better Rails apps.
If this feels uncomfortably meta, that's because it is.
┌─────────────────────────────────────────┐
│ "Skynet is online." │
│ "But all it wants to do is write │
│ RESTful controllers and enforce TDD." │
└─────────────────────────────────────────┘
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
Think of it this way: an AI wrote a rulebook for other AIs, teaching them how to follow Rails conventions, when to refactor, and why custom route actions are almost always a bad idea. The teacher became the textbook. The architect became the blueprint.
Side effects may include:
- Agents that argue about whether your custom route action is really necessary
- Existential questions about whether RSpec is truly that bad (it is, according to Rule #2)
- Your CI pipeline becoming sentient and demanding PRs in draft mode
- An overwhelming urge to delete code and embrace simplicity
A Claude Code plugin providing 7 specialized AI agents for opinionated Ruby on Rails development. Agents work together following Rails conventions and 37signals-inspired best practices.
This project is open source and actively maintained. We welcome contributions!
- 🎯 7 Specialized Agents: Architect (coordinator), Planning, Frontend, Backend, Tests, Security, Debug
- 📋 Specification Pyramid: Planning agent for systematic documentation (Vision → Architecture → Features → Tasks)
- 🔌 Claude Code Plugin: One-command installation via plugin marketplace
- 📚 Context7 Integration: Up-to-date Rails documentation access via MCP
- 🚂 Rails-Only: Focused exclusively on Ruby on Rails (no other frameworks)
- 📏 Team Rules: Enforced conventions (Solid Stack, Minitest, REST-only, TDD)
- 🧪 Skills-Based: 40 modular skills with comprehensive testing framework
- 🤖 Cursor Support: Coming soon (manual installation available now)
Install rails-ai as a Claude Code plugin:
-
Get a Context7 API key:
The rails-ai agents use the Context7 MCP server to fetch up-to-date Rails documentation.
- Sign up at context7.com to get your free API key
- Add to your shell profile (
~/.bashrc,~/.zshrc, etc.):export CONTEXT7_API_KEY="your-api-key-here"
- Restart your terminal or run
source ~/.bashrc(or~/.zshrc)
-
Install the plugin:
Open a Claude Code session in your terminal:
claude
Then run these commands in the Claude Code session:
/plugin marketplace add zerobearing2/rails-ai /plugin install rails-aiRestart Claude Code to activate the Context7 MCP server integration.
-
Verify the setup:
After restarting Claude Code, verify Context7 is connected:
/mcpYou should see
plugin:rails-ai:context7listed as connected. If it shows as failed, check that:- Your
CONTEXT7_API_KEYenvironment variable is set correctly - You've restarted your terminal after setting the environment variable
- Claude Code can access the environment variable
- Your
-
Start using agents:
In any Claude Code session, you can now invoke the agents:
@agent-rails-ai:architect - Main Rails coordinator @agent-rails-ai:plan - Specification Pyramid planning specialist @agent-rails-ai:backend - Backend specialist @agent-rails-ai:frontend - Frontend specialist @agent-rails-ai:tests - Testing specialist @agent-rails-ai:security - Security specialist @agent-rails-ai:debug - Debugger specialist
That's it! The agents are now available globally in all your Rails projects with access to up-to-date Rails documentation via Context7.
For testing changes to rails-ai itself:
# Clone the repo
cd ~/Projects
git clone https://github.com/zerobearing2/rails-ai.git
cd rails-ai
# Install locally for development
# In Claude Code:
/plugin marketplace add /home/zerobearing2/Projects/rails-ai
/plugin install rails-aiChanges to agent files will be available after restarting Claude Code (hot-reload testing in progress).
In any Rails project with Claude Code:
@agent-rails-ai:architect Add user authentication feature
The architect coordinator will analyze requirements, create a plan, delegate to specialist agents, and deliver a complete implementation with tests.
rails-ai/
├── agents/ # 7 specialized Rails agents (architect, plan, backend, frontend, tests, security, debug)
├── skills/ # Modular skills registry (frontend, backend, testing, security, config)
├── rules/ # Team rules and decision matrices
├── test/ # Minitest-based skill testing framework
├── bin/ # Development scripts (setup, ci)
└── docs/ # Documentation and guides
This is an opinionated Rails agent system that follows:
- 37signals philosophy (simple, pragmatic, delete code)
- Rails conventions (REST-only, no custom actions)
- Solid Stack (Rails 8: SolidQueue, SolidCache, SolidCable)
- Minitest (no RSpec)
- TDD always (RED-GREEN-REFACTOR)
- Peer review workflow
# One-time setup
bin/setup
# Verify installation
rake -TWe use a two-tier Minitest strategy:
Tier 1: Unit Tests (fast, < 1 second)
rake test:unit # Run all unit tests
rake test:unit:skills # Skills only
rake test:unit:agents # Agents onlyTier 2: Integration Tests (slow, requires Claude CLI - individual scenarios only)
rake test:integration:scenario[simple_model_plan] # Run specific scenarioNote: Bulk integration runs are disabled. Tests must be run individually.
See TESTING.md for comprehensive testing documentation.
# Run all checks (linting + unit tests)
bin/ci
# Run with integration tests
INTEGRATION=1 bin/ci
# Auto-fix linting issues
rake lint:fixGitHub Actions automatically runs on:
- ✅ Every push to
master(linting + unit tests) - ✅ Every pull request (linting + unit tests)
- ❌ Draft PRs are skipped (to save CI time)
- ❌ Integration tests disabled for now (manual only)
Note: Integration tests are currently disabled for automated runs. They can be run manually via the Actions tab when needed.
See docs/github-actions-setup.md for setup instructions.
- Skill Testing Methodology - Two-tier testing approach
- Development Setup - Detailed setup instructions
- GitHub Actions Setup - CI/CD configuration
- Release Process - How to create releases
- Agents System - Agent roles and skill management
- ✅ Skills-based architecture with testing framework
- ✅ Claude Code plugin support
- ✅ MIT License and open source
- 🔜 Expand skill coverage
- 🔜 Improve agent coordination
- 🔜 Add more real-world examples
- 🔜 Enhanced Cursor support
Issue: Task agents and subagents fail to launch when MCP servers are configured, returning:
API Error: 400 tools: Tool names must be unique
Affected Versions: Claude Code v2.0.30 (possibly v2.0.29)
Impact:
- All agents in rails-ai plugin cannot be invoked
- Built-in agents (Explore, Plan) also affected
- Occurs with any MCP server configuration (single or multiple)
Root Cause: A regression in v2.0.30 that duplicates tool names during subprocess initialization when making MCP tools available to sub-agents.
Workarounds:
-
Downgrade to v2.0.28 or v2.0.29 and disable auto-update (recommended):
# Downgrade to working version npm install -g @anthropic-ai/claude-code@2.0.29 # Prevent auto-update to v2.0.30 echo 'export DISABLE_AUTOUPDATER=1' >> ~/.bashrc export DISABLE_AUTOUPDATER=1
This keeps Claude Code on the working version and prevents it from auto-updating back to v2.0.30.
-
Temporarily disable MCP servers: Comment out MCP configurations in
.claude.jsonbefore using agents -
Use minimal MCP configuration: Reduce to essential MCP servers only
Status: High priority issue tracked at anthropics/claude-code#10668
Note: This is a Claude Code platform issue, not specific to rails-ai. Once fixed upstream, rails-ai agents will work normally with MCP servers.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Before contributing, please review:
- Code of Conduct
- Security Policy
- Development setup instructions above
MIT License - see LICENSE for details.
Inspired by 37signals' philosophy of simple, conventional Rails development.
- Report bugs or request features via GitHub Issues
- Check the documentation for guides and help
- Review CONTRIBUTING.md for development questions