ruby_llm-agents: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

RubyLLM::Agents is a Rails engine gem for building, managing, and monitoring LLM-powered AI agents. It provides a DSL for agent configuration, a middleware pipeline for execution, automatic tracking with cost analytics, and a mountable dashboard UI.

Requirements: Ruby >= 3.1, Rails >= 7.0, RubyLLM >= 1.16.0

Common Commands

bundle exec rspec                          # Run full test suite (~3700+ specs)
bundle exec rspec spec/agents/routing_spec.rb  # Run a single spec file
bundle exec rspec spec/agents/ -e "parses"     # Run specs matching description
bundle exec standardrb                     # Lint (StandardRB, targets Ruby 3.1)
bundle exec standardrb --fix              # Auto-fix lint issues
bundle exec rake                           # Run both specs and linter (default task)
RUN_INTEGRATION=1 bundle exec rspec        # Include integration tests (skipped by default)

Pre-commit hook: A git pre-commit hook runs standardrb --no-fix and blocks commits on lint failures. Fix with bundle exec standardrb --fix before committing.

CI: Runs lint on Ruby 3.4, tests on Ruby 3.2/3.3/3.4.

---

Core Design Principles

Deep Modules Philosophy

From John Ousterhout's A Philosophy of Software Design: The best modules are deep — they hide significant complexity behind a simple interface.

Module Depth = (Complexity Hidden) / (Interface Exposed)

A deep module has a small public API that hides substantial logic. A shallow module exposes an interface almost as complex as its implementation. Do not create shallow modules.

Decision Framework: When to Create a New Abstraction

Before creating a new class, module, concern, or middleware, answer:

1. What complexity does it hide? If "not much" or "it just delegates," don't create it.
2. Is the interface simpler than the implementation? If the public API has as many concepts as the internals, it's shallow.
3. Does it have a reason to change independently? If it always changes in lockstep with another module, merge them.
4. Can I name it with a specific noun/verb? Vague names (Manager, Handler, Processor, Utils) usually signal shallow design.