rails-ai-agents

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Rails AI Agents

A production-ready Claude Code setup for Ruby on Rails development: **19 specialized agents**, **26 slash commands** (including the [SDD kit](#spec-driven-development-sdd-kit)), **18 skills**, **14 rules** (11 path-scoped + 3 always-on), **1 MCP**, and **6 lifecycle hooks**. Drop it into your project and your AI assistant instantly knows Rails conventions, TDD workflows, and production patterns.

Also includes:
- [Spec Driven Development (SDD) kit](#spec-driven-development-sdd-kit) — a full specification-to-implementation pipeline + lightweight mode for bug fixes.
- a separate 37signals-style conventions pack (`.claude_37signals/`) for teams that prefer rich models + Minitest over the default layered setup.
- Claude Code Extensibility Guide
- and more!


## Latest Updates

- Add caveman rule with full intensity level (token reduction)
- Add plan, review, and PR artifact commands.
- Add tmux session launcher script for Rails development.

## Quick Start

```bash
# Most projects: copy the default .claude/ directory into your Rails project
cp -r .claude/ /path/to/your-rails-app/.claude/
```

| If you want... | Copy |
|---|---|
| Default setup (layered architecture, RSpec, Pundit, PostgreSQL) | `.claude/` |
| 37signals-style conventions (rich models, concerns, Minitest) | `.claude_37signals/` **instead of** `.claude/` |
| Spec Driven Development commands (`/sdd:*`, `/sdd-change:*`) | `.specify/` in addition to your chosen `.claude*` pack |
| Statusline | `statusline/` |
| Sentry integration | `mcp/sentry_monitor/` |

`.specify/` is optional unless you want the SDD workflow. `.claude_37signals/` is currently a conventions pack (instructions, agents, skills, rules, settings), while the slash-command set documented below lives under `.claude/commands/`.

## OpenAI Codex and GitHub Copilot Support

This repo includes a practical setup for both OpenAI Codex and GitHub Copilot (including different Copilot-backed models such as GPT, Claude, and Gemini), while keeping `.claude/` as the canonical source.

- `AGENTS.md` is the shared high-level project instruction file.
- `.agents/skills/` is the mirrored skills directory used by Codex and reusable from Copilot.
- `.claude/skills/` remains the canonical source for shared skills.
- `.github/copilot-instructions.md` is the Copilot entrypoint.
- `.github/instructions/claude-rules/` contains generated path-scoped bridge files that point back to `.claude/rules/`.

Because Codex skill discovery is currently unreliable with symlinks, this repo includes a local sync script that copies Claude skills into real directories:

```bash
scripts/sync_claude_skills_to_codex.sh
scripts/sync_claude_rules_to_copilot.sh
```

Run these scripts after adding, removing, or renaming any skill or rule. If Codex or Copilot is already running, restart or reload the chat session to pick up updates.

## What's Inside

### Agents (`.claude/agents/`)

19 specialist agents, each with `permissionMode: acceptEdits`, `memory: project`, `maxTurns` limits, and WHEN/WHEN NOT descriptions for auto-delegation.

| Agent | Domain | Model |
|---|---|---|
| `model-agent` | ActiveRecord models, validations, associations, scopes | sonnet |
| `controller-agent` | Thin RESTful controllers, strong params, Pundit | sonnet |
| `service-agent` | Service objects, Result pattern, SOLID | sonnet |
| `migration-agent` | Safe, reversible database migrations | haiku |
| `policy-agent` | Pundit authorization policies | sonnet |
| `form-agent` | Multi-model forms, wizard forms | sonnet |
| `query-agent` | Complex queries, N+1 prevention | sonnet |
| `presenter-agent` | View logic separation with SimpleDelegator | sonnet |
| `viewcomponent-agent` | Reusable, tested UI components | sonnet |
| `job-agent` | Background jobs with Solid Queue | sonnet |
| `mailer-agent` | ActionMailer with previews and templates | sonnet |
| `turbo-agent` | Turbo Frames, Streams, Drive | sonnet |
| `stimulus-agent` | Stimulus controllers | sonnet |
| `tailwind-agent` | Tailwind CSS styling | sonnet |
| `rspec-agent` | RSpec tests | sonnet |
| `implementation-agent` | TDD GREEN phase orchestrator (worktree isolation) | sonnet |
| `tdd-refactoring-agent` | TDD REFACTOR phase | sonnet |
| `lint-agent` | RuboCop linting and auto-correction | haiku |
| `database-reviewer` | PostgreSQL query optimization, schema design, performance | sonnet |

### Commands (`.claude/commands/`)

26 slash commands across 4 namespaces. See also [SDD commands](#sdd-commands-claudecommandssdd) below.

#### Standalone (7)

| Command | Purpose |
|---|---|
| `/feature-spec` | Structured interview to write a complete spec with Gherkin scenarios |
| `/feature-spec-review` | Scores specs, identifies gaps, generates missing scenarios |
| `/feature-plan` | Converts spec into TDD implementation plan with PR breakdown |
| `/feature-tdd-implementation` | Guides full Red-Green-Refactor TDD workflow |
| `/frame-problem` | Reframes vague requests into clear problems |
| `/prompt-improver` | Scores and rewrites vague prompts into specific, actionable ones |
| `/catchup` | "Welcome back" report on a feature branch — commits, authors, themes, and risks since the dev's last contribution |

#### Sentry Commands (`.claude/commands/sentry/`)

| Command | Purpose |
|---|---|
| `/sentry:monitor` | Check for new production errors and propose fixes |
| `/sentry:fix-error` | Launch a background agent in an isolated worktree to fix a Sentry error |
| `/sentry:fix-status` | List all active Sentry fix branches and their status |
| `/sentry:report` | Generate a markdown summary of Sentry error status for standups or PRs |
| `/sentry:resolve` | Resolve, ignore, or reopen a Sentry issue after a fix is deployed |

### Skills (`.claude/skills/`)

18 skills with reference docs. Two patterns: **task skills** (user-invocable workflows) and **knowledge skills** (auto-loaded conventions).

| Skill | Type | Purpose |
|---|---|---|
| `code-review` | Task | SOLID analysis, N+1 detection, anti-patterns (read-only) |
| `security-audit` | Task | OWASP Top 10 audit with Brakeman (runs with opus) |
| `accessibility-review` | Task | WCAG 2.2 AA audit with axe-core / Lighthouse / Pa11y, progressive-disclosure references for ARIA patterns and Rails snippets (runs with opus) |
| `codex-review` | Task | Independent second opinion from OpenAI Codex CLI on plans, diffs, or specs |
| `dependabot-review` | Task | Reviews Dependabot gem upgrade PRs for breaking changes and merge readiness |
| `behavioral-guidelines` | Knowledge | Guidelines to reduce common LLM coding mistakes (auto-loaded) |
| `rails-architecture` | Knowledge | Layered architecture decisions (runs with opus) |
| `postgres-patterns` | Knowledge | PostgreSQL query optimization, schema design, indexing, and security |
| `authentication-flow` | Knowledge | Rails 8 built-in authentication |
| `caching-strategies` | Knowledge | Fragment, Russian doll, low-level caching |
| `performance-optimization` | Knowledge | N+1 detection, query optimization |
| `extraction-timing` | Knowledge | When and how to extract services, queries, concerns |
| `action-cable-patterns` | Knowledge | WebSocket real-time features |
| `active-storage-setup` | Knowledge | File uploads and variants |
| `api-versioning` | Knowledge | RESTful API design |
| `i18n-patterns` | Knowledge | Internationalization |
| `solid-queue-setup` | Knowledge | Background job configuration |
| `rails-concern` | Knowledge | Shared behavior with concerns |

### Rules (`.claude/rules/`)

14 rules: 11 path-scoped (auto-load when Claude works on matching files) and 3 always-on.

#### Path-scoped (11)

| Rule | Scoped to |
|---|---|
| `models.md` | `app/models/**`, `spec/models/**`, `spec/factories/**` |
| `controllers.md` | `app/controllers/**`, `spec/requests/**` |
| `services.md` | `app/services/**`, `spec/services/**` |
| `queries.md` | `app/queries/**`, `spec/queries/**` |
| `policies.md` | `app/policies/**`, `spec/policies/**` |
| `jobs.md` | `app/jobs/**`, `spec/jobs/**` |
| `mailers.md` | `app/mailers/**`, `spec/mailers/**` |
| `migrations.md` | `db/migrate/**`, `db/schema.rb` |
| `views.md` | `app/views/**`, `app/components/**`, `app/presenters/**` |
| `testing.md` | `spec/**` |
| `anti-patterns.md` | `app/**/*.rb`, `spec/**/*.rb` |

#### Always-on (3)

| Rule | Purpose |
|---|---|
| `principles.md` | KISS, DRY, YAGNI, SRP, and Rails architecture principles |
| `cli.md` | Rails CLI commands reference (dev server, tests, db, generators) |
| `cli-tools.md` | Preferred CLI tools: `rg` over `grep`, `fd` over `find` |

### Hooks (`.claude/settings.json`)

| Hook | Event | What it does |
|---|---|---|
| **SessionStart** | Session begins | Injects project context (branch, Ruby/Rails version, pending migrations) |
| **PostToolUse** | After Edit/Write | Auto-formats Ruby files with RuboCop |
| **PreToolUse** | Before Bash | Blocks destructive commands (rm -rf, DROP TABLE, force push to main) |
| **TaskCompleted** | Task marked done | Quality gate: reminds to run tests and linting |
| **Stop** | Response ends | Desktop notification |

### Settings

- **Agent Teams** enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`)
- **JSON Schema** for editor autocomplete
- **Smart model routing**: opus for architecture/security, sonnet for coding, haiku for linting

### Statusline (`statusline/`)

A two-line statusline that surfaces the signals you actually need while working: git state, model, and usage budgets.

![Statusline](https://github.com/thibautbaissac/rails_ai_agents/raw/HEAD/statusline/screenshot.png)

- **Line 1** — current branch (with a `✗` marker when the working tree is dirty), model name, and reasoning effort level
- **Line 2** — context window usage, 5-hour rate-limit usage with reset countdown, 7-day rate-limit usage with reset countdown
- **Color-coded thresholds** — green under 50%, yellow 50–79%, red at 80%+ so you can see budget pressure at a glance

Wire it up in `~/.claude/settings.json`:

```json
{
  "statusLine": {
    "type": "command",
    "command": "bash /absolute/path/to/statusline/statusline.sh"
  }
}
```

## Spec Driven Development (SDD) Kit

A structured specification-to-implementation pipeline powered by 11 slash commands. SDD enforces a disciplined workflow: define what you're building before writing code, validate requirements quality, then implement from a task plan.

### SDD Commands (`.claude/commands/sdd/`)

| Command | Purpose |
|---|---|
| `/sdd:constitution` | Create or update the project constitution — core principles and governance rules |
| `/sdd:specify` | Generate a feature specification from a natural language description |
| `/sdd:clarify` | Ask up to 5 targeted questions to reduce ambiguity in the spec |
| `/sdd:spec-review` | Adversarial review of the spec from security, performance, edge-case, scalability, and compliance perspectives |
| `/sdd:checklist` | Generate a requirements quality checklist |
| `/sdd:plan` | Create a technical implementation plan with research, data model, and contracts |
| `/sdd:tasks` | Break the plan into dependency-ordered, executable tasks organized by user story |
| `/sdd:analyze` | Read-only consistency analysis across spec, plan, and tasks |
| `/sdd:implement` | Execute the task plan phase-by-phase with progress tracking |
| `/sdd:implement-subagents` | Same as implement, but spawns a fresh-context subagent per task to prevent context rot on large features |
| `/sdd:validate` | Post-implementation drift detection — verifies code implements what the spec promises (4-layer hybrid, no annotations needed) |

### SDD Workflow

```
/sdd:constitution                  # 1. Define project principles (once)
/sdd:specify user authentication   # 2. Write the feature spec
/sdd:clarify                       # 3. Resolve ambiguities (optional)
/sdd:spec-review                   # 4. Adversarial review from 5 perspectives (optional)
/sdd:checklist security            # 5. Validate requirements quality (optional)
/sdd:plan                          # 6. Generate technical plan + data model
/sdd:tasks                         # 7. Break into ordered tasks
/sdd:analyze                       # 8. Cross-artifact consistency check
/sdd:implement                     # 9. Execute tasks with verification
# Or for large features:
/sdd:implement-subagents           # 9. Fresh-context subagent per task (prevents context rot)
/sdd:validate                      # 10. Verify implementation matches spec (post-implementation)
```

Each command hands off to the next via suggested prompts. The pipeline creates a `specs/<branch-name>/` directory with all artifacts:

```
specs/001-user-auth/
├── spec.md           # Feature specification (/sdd:specify)
├── plan.md           # Implementation plan (/sdd:plan)
├── research.md       # Technical research & decisions (/sdd:plan)
├── data-model.md     # Entity definitions (/sdd:plan)
├── quickstart.md     # Integration scenarios (/sdd:plan)
├── contracts/        # Route and API contracts (/sdd:plan)
├── tasks.md          # Executable task list (/sdd:tasks)
├── checklists/       # Requirements quality checklists (/sdd:checklist)
└── validation-report.md  # Post-implementation drift report (/sdd:validate)
```

### SDD Infrastructure (`.specify/`)

The `.specify/` directory contains the scaffolding that powers SDD commands. It is optional for normal prompting; you only need it for the `/sdd:*` and `/sdd-change:*` workflows:

- **`templates/`** — Markdown templates for specs, plans, tasks, checklists, constitutions, and agent context files
- **`scripts/bash/`** — Shell scripts for branch creation, prerequisite checking, plan setup, and agent context updates
- **`memory/`** — Persistent project state (constitution, lessons learned across features)
- **`init-options.json`** — Configuration (branch numbering mode, AI agent type)

SDD supports extensibility via `.specify/extensions.yml` for before/after hooks on any command, template overrides in `.specify/templates/overrides/`, and presets in `.specify/presets/`.

### Key SDD Concepts

- **Constitution** — Non-negotiable project principles validated at every planning gate
- **Lessons Learned** — Cross-feature learnings accumulate in `.specify/memory/lessons-learned.md` and feed into future planning and implementation
- **Adversarial Spec Review** — `/sdd:spec-review` challenges the spec from security, performance, edge-case, scalability, and compliance perspectives before planning begins
- **Specs are stakeholder-facing** — No implementation details; focus on WHAT and WHY
- **Checklists are "unit tests for English"** — They validate requirements quality, not implementation correctness
- **Tasks organized by user story** — Each story is independently implementable and testable (MVP-first)
- **Fresh-context implementation** — `/sdd:implement-subagents` spawns a clean subagent per task, preventing context rot on large features
- **Post-implementation validation** — `/sdd:validate` uses a 4-layer hybrid approach (structural scan, test mapping, AI semantic analysis, acceptance test generation) to verify the code matches the spec — works on day one, no code annotations needed

### SDD Small-Change (Lightweight Mode)

For bug fixes and small features that don't need the full SDD ceremony. Three commands, no plan, no checklists, no analysis — just specify, task, implement.

#### Commands (`.claude/commands/sdd-change/`)

| Command | Purpose |
|---|---|
| `/sdd-change:specify` | Create a minimal change spec (problem, fix, acceptance criteria, files affected) |
| `/sdd-change:tasks` | Generate a flat 3-8 task list from the change spec |
| `/sdd-change:implement` | Execute tasks sequentially with validation |

#### Workflow

```
/sdd-change:specify Fix login timeout — sessions expire after 5min instead of 30
/sdd-change:tasks
/sdd-change:implement
```

#### When to Use Which

| Situation | Use |
|---|---|
| Bug fix, patch, tweak | `/sdd-change:specify` |
| New feature, multi-story epic | `/sdd:specify` |
| Refactor touching 1-3 files | `/sdd-change:specify` |
| Refactor touching 6+ files | `/sdd:specify` |

The lightweight pipeline warns you if your change looks too complex (>3 acceptance criteria or >6 files affected) and suggests switching to the full pipeline.

## Scripts (`scripts/`)

| Script | Purpose |
|---|---|
| `start_rails_tmux.sh` | Open (or reuse) a tmux session with a three-pane main-vertical layout: editor on the left, `bin/dev` (or `bin/rails server`) top-right, `bin/rails console` bottom-right. Idempotent — re-running attaches to the existing session and auto-restarts any pane that has dropped back to a shell prompt. |
| `sync_claude_skills_to_codex.sh` | Mirror `.claude/skills/` into `.agents/skills/` for OpenAI Codex compatibility |
| `sync_claude_rules_to_copilot.sh` | Generate `.github/instructions/claude-rules/` bridge files from `.claude/rules/` for GitHub Copilot |

## MCP Servers (`mcp/`)

Custom MCP servers that extend Claude Code with external integrations.

| Server | Purpose | Docs |
|--------|---------|------|
| [`sentry_monitor`](https://github.com/thibautbaissac/rails_ai_agents/tree/HEAD/mcp/sentry_monitor/) | Exposes Sentry production errors as Claude Code tools — query issues, map stack traces to local files, detect new errors with persistent state tracking, PII redaction by default | [README](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/mcp/sentry_monitor/README.md) |

## Documentation

| Document | Purpose |
|---|---|
| [Your First SDD Feature](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/your-first-sdd-feature.md) | Step-by-step onboarding walkthrough for new developers using the SDD kit |
| [SDD Team Scalability Analysis](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/sdd-team-scalability-analysis.md) | Risks, gaps, and roadmap for scaling SDD to a 30-developer team |
| [Rails Development Principles](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/rails-development-principles.md) | Universal software principles, Rails doctrine, modern Rails 8 architecture, testing, security, and performance |
| [Prompt Engineering for Claude Code](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/prompt-engineering-for-claude-code.md) | Writing effective prompts for Claude Code in web development, with Rails-specific patterns |
| [Claude Code Extensibility Guide](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/claude-code-extensibility-guide.md) | All extension mechanisms: CLAUDE.md, skills, hooks, subagents, Agent Teams, MCP servers, and plugins |
| [Claude Code Frontmatter Reference](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/claude-code-frontmatter-reference.md) | YAML frontmatter syntax for configuring agents, skills, and commands in `.claude/` files |
| [MCP Servers for Rails](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/mcp-servers-rails-guide.md) | Extending Claude Code with Model Context Protocol servers for Rails, databases, and APIs |
| [PRD Best Practices](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/prd-best-practices.md) | Writing effective Product Requirements Documents in agile, AI-in-the-loop environments |
| [Technical Design Documents](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/technical-design-document.md) | TDDs, ADRs, and Engineering RFCs for agentic SDLC teams |
| [Design Specifications](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/design-specification.md) | UI/UX design specs and API specifications (OpenAPI) for frontend/backend contracts |
| [Specification Document Hierarchy](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/specification-document-hierarchy.md) | Reference map showing which documents answer which core questions |
| [AI Terminology Glossary](https://github.com/thibautbaissac/rails_ai_agents/blob/HEAD/docs/ai-glossary.md) | 289 AI/ML terms across 25 categories — also available as a [browsable HTML version](https://thibautbaissac.github.io/ai/glossary.html) |

## License

MIT

Rails AI Agents

A production-ready Claude Code setup for Ruby on Rails development: 19 specialized agents, 26 slash commands (including the SDD kit), 18 skills, 14 rules (11 path-scoped + 3 always-on), 1 MCP, and 6 lifecycle hooks. Drop it into your project and your AI assistant instantly knows Rails conventions, TDD workflows, and production patterns.

Also includes:

Spec Driven Development (SDD) kit — a full specification-to-implementation pipeline + lightweight mode for bug fixes.
a separate 37signals-style conventions pack (.claude_37signals/) for teams that prefer rich models + Minitest over the default layered setup.
Claude Code Extensibility Guide
and more!

Latest Updates

Add caveman rule with full intensity level (token reduction)
Add plan, review, and PR artifact commands.
Add tmux session launcher script for Rails development.

Quick Start

# Most projects: copy the default .claude/ directory into your Rails project
cp -r .claude/ /path/to/your-rails-app/.claude/

If you want...	Copy
Default setup (layered architecture, RSpec, Pundit, PostgreSQL)	`.claude/`
37signals-style conventions (rich models, concerns, Minitest)	`.claude_37signals/` instead of `.claude/`
Spec Driven Development commands (`/sdd:`, `/sdd-change:`)	`.specify/` in addition to your chosen `.claude*` pack
Statusline	`statusline/`
Sentry integration	`mcp/sentry_monitor/`

.specify/ is optional unless you want the SDD workflow. .claude_37signals/ is currently a conventions pack (instructions, agents, skills, rules, settings), while the slash-command set documented below lives under .claude/commands/.

OpenAI Codex and GitHub Copilot Support

This repo includes a practical setup for both OpenAI Codex and GitHub Copilot (including different Copilot-backed models such as GPT, Claude, and Gemini), while keeping .claude/ as the canonical source.

AGENTS.md is the shared high-level project instruction file.
.agents/skills/ is the mirrored skills directory used by Codex and reusable from Copilot.
.claude/skills/ remains the canonical source for shared skills.
.github/copilot-instructions.md is the Copilot entrypoint.
.github/instructions/claude-rules/ contains generated path-scoped bridge files that point back to .claude/rules/.

Because Codex skill discovery is currently unreliable with symlinks, this repo includes a local sync script that copies Claude skills into real directories:

scripts/sync_claude_skills_to_codex.sh
scripts/sync_claude_rules_to_copilot.sh

Run these scripts after adding, removing, or renaming any skill or rule. If Codex or Copilot is already running, restart or reload the chat session to pick up updates.

What's Inside

Agents (`.claude/agents/`)

19 specialist agents, each with permissionMode: acceptEdits, memory: project, maxTurns limits, and WHEN/WHEN NOT descriptions for auto-delegation.

Agent	Domain	Model
`model-agent`	ActiveRecord models, validations, associations, scopes	sonnet
`controller-agent`	Thin RESTful controllers, strong params, Pundit	sonnet
`service-agent`	Service objects, Result pattern, SOLID	sonnet
`migration-agent`	Safe, reversible database migrations	haiku
`policy-agent`	Pundit authorization policies	sonnet
`form-agent`	Multi-model forms, wizard forms	sonnet
`query-agent`	Complex queries, N+1 prevention	sonnet
`presenter-agent`	View logic separation with SimpleDelegator	sonnet
`viewcomponent-agent`	Reusable, tested UI components	sonnet
`job-agent`	Background jobs with Solid Queue	sonnet
`mailer-agent`	ActionMailer with previews and templates	sonnet
`turbo-agent`	Turbo Frames, Streams, Drive	sonnet
`stimulus-agent`	Stimulus controllers	sonnet
`tailwind-agent`	Tailwind CSS styling	sonnet
`rspec-agent`	RSpec tests	sonnet
`implementation-agent`	TDD GREEN phase orchestrator (worktree isolation)	sonnet
`tdd-refactoring-agent`	TDD REFACTOR phase	sonnet
`lint-agent`	RuboCop linting and auto-correction	haiku
`database-reviewer`	PostgreSQL query optimization, schema design, performance	sonnet

Commands (`.claude/commands/`)

26 slash commands across 4 namespaces. See also SDD commands below.

Standalone (7)

Command	Purpose
`/feature-spec`	Structured interview to write a complete spec with Gherkin scenarios
`/feature-spec-review`	Scores specs, identifies gaps, generates missing scenarios
`/feature-plan`	Converts spec into TDD implementation plan with PR breakdown
`/feature-tdd-implementation`	Guides full Red-Green-Refactor TDD workflow
`/frame-problem`	Reframes vague requests into clear problems
`/prompt-improver`	Scores and rewrites vague prompts into specific, actionable ones
`/catchup`	"Welcome back" report on a feature branch — commits, authors, themes, and risks since the dev's last contribution

Sentry Commands (`.claude/commands/sentry/`)

Command	Purpose
`/sentry:monitor`	Check for new production errors and propose fixes
`/sentry:fix-error`	Launch a background agent in an isolated worktree to fix a Sentry error
`/sentry:fix-status`	List all active Sentry fix branches and their status
`/sentry:report`	Generate a markdown summary of Sentry error status for standups or PRs
`/sentry:resolve`	Resolve, ignore, or reopen a Sentry issue after a fix is deployed

Skills (`.claude/skills/`)

18 skills with reference docs. Two patterns: task skills (user-invocable workflows) and knowledge skills (auto-loaded conventions).

Skill	Type	Purpose
`code-review`	Task	SOLID analysis, N+1 detection, anti-patterns (read-only)
`security-audit`	Task	OWASP Top 10 audit with Brakeman (runs with opus)
`accessibility-review`	Task	WCAG 2.2 AA audit with axe-core / Lighthouse / Pa11y, progressive-disclosure references for ARIA patterns and Rails snippets (runs with opus)
`codex-review`	Task	Independent second opinion from OpenAI Codex CLI on plans, diffs, or specs
`dependabot-review`	Task	Reviews Dependabot gem upgrade PRs for breaking changes and merge readiness
`behavioral-guidelines`	Knowledge	Guidelines to reduce common LLM coding mistakes (auto-loaded)
`rails-architecture`	Knowledge	Layered architecture decisions (runs with opus)
`postgres-patterns`	Knowledge	PostgreSQL query optimization, schema design, indexing, and security
`authentication-flow`	Knowledge	Rails 8 built-in authentication
`caching-strategies`	Knowledge	Fragment, Russian doll, low-level caching
`performance-optimization`	Knowledge	N+1 detection, query optimization
`extraction-timing`	Knowledge	When and how to extract services, queries, concerns
`action-cable-patterns`	Knowledge	WebSocket real-time features
`active-storage-setup`	Knowledge	File uploads and variants
`api-versioning`	Knowledge	RESTful API design
`i18n-patterns`	Knowledge	Internationalization
`solid-queue-setup`	Knowledge	Background job configuration
`rails-concern`	Knowledge	Shared behavior with concerns

Rules (`.claude/rules/`)

14 rules: 11 path-scoped (auto-load when Claude works on matching files) and 3 always-on.

Path-scoped (11)

Rule	Scoped to
`models.md`	`app/models/`, `spec/models/`, `spec/factories/**`
`controllers.md`	`app/controllers/`, `spec/requests/`
`services.md`	`app/services/`, `spec/services/`
`queries.md`	`app/queries/`, `spec/queries/`
`policies.md`	`app/policies/`, `spec/policies/`
`jobs.md`	`app/jobs/`, `spec/jobs/`
`mailers.md`	`app/mailers/`, `spec/mailers/`
`migrations.md`	`db/migrate/**`, `db/schema.rb`
`views.md`	`app/views/`, `app/components/`, `app/presenters/**`
`testing.md`	`spec/**`
`anti-patterns.md`	`app/*/.rb`, `spec/*/.rb`

Always-on (3)

Rule	Purpose
`principles.md`	KISS, DRY, YAGNI, SRP, and Rails architecture principles
`cli.md`	Rails CLI commands reference (dev server, tests, db, generators)
`cli-tools.md`	Preferred CLI tools: `rg` over `grep`, `fd` over `find`

Hooks (`.claude/settings.json`)

Hook	Event	What it does
SessionStart	Session begins	Injects project context (branch, Ruby/Rails version, pending migrations)
PostToolUse	After Edit/Write	Auto-formats Ruby files with RuboCop
PreToolUse	Before Bash	Blocks destructive commands (rm -rf, DROP TABLE, force push to main)
TaskCompleted	Task marked done	Quality gate: reminds to run tests and linting
Stop	Response ends	Desktop notification

Settings

Agent Teams enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS)
JSON Schema for editor autocomplete
Smart model routing: opus for architecture/security, sonnet for coding, haiku for linting

Statusline (`statusline/`)

A two-line statusline that surfaces the signals you actually need while working: git state, model, and usage budgets.

Statusline

Line 1 — current branch (with a ✗ marker when the working tree is dirty), model name, and reasoning effort level
Line 2 — context window usage, 5-hour rate-limit usage with reset countdown, 7-day rate-limit usage with reset countdown
Color-coded thresholds — green under 50%, yellow 50–79%, red at 80%+ so you can see budget pressure at a glance

Wire it up in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash /absolute/path/to/statusline/statusline.sh"
  }
}

Spec Driven Development (SDD) Kit

A structured specification-to-implementation pipeline powered by 11 slash commands. SDD enforces a disciplined workflow: define what you're building before writing code, validate requirements quality, then implement from a task plan.

SDD Commands (`.claude/commands/sdd/`)

Command	Purpose
`/sdd:constitution`	Create or update the project constitution — core principles and governance rules
`/sdd:specify`	Generate a feature specification from a natural language description
`/sdd:clarify`	Ask up to 5 targeted questions to reduce ambiguity in the spec
`/sdd:spec-review`	Adversarial review of the spec from security, performance, edge-case, scalability, and compliance perspectives
`/sdd:checklist`	Generate a requirements quality checklist
`/sdd:plan`	Create a technical implementation plan with research, data model, and contracts
`/sdd:tasks`	Break the plan into dependency-ordered, executable tasks organized by user story
`/sdd:analyze`	Read-only consistency analysis across spec, plan, and tasks
`/sdd:implement`	Execute the task plan phase-by-phase with progress tracking
`/sdd:implement-subagents`	Same as implement, but spawns a fresh-context subagent per task to prevent context rot on large features
`/sdd:validate`	Post-implementation drift detection — verifies code implements what the spec promises (4-layer hybrid, no annotations needed)

SDD Workflow

/sdd:constitution                  # 1. Define project principles (once)
/sdd:specify user authentication   # 2. Write the feature spec
/sdd:clarify                       # 3. Resolve ambiguities (optional)
/sdd:spec-review                   # 4. Adversarial review from 5 perspectives (optional)
/sdd:checklist security            # 5. Validate requirements quality (optional)
/sdd:plan                          # 6. Generate technical plan + data model
/sdd:tasks                         # 7. Break into ordered tasks
/sdd:analyze                       # 8. Cross-artifact consistency check
/sdd:implement                     # 9. Execute tasks with verification
# Or for large features:
/sdd:implement-subagents           # 9. Fresh-context subagent per task (prevents context rot)
/sdd:validate                      # 10. Verify implementation matches spec (post-implementation)

Each command hands off to the next via suggested prompts. The pipeline creates a specs/<branch-name>/ directory with all artifacts:

specs/001-user-auth/
├── spec.md           # Feature specification (/sdd:specify)
├── plan.md           # Implementation plan (/sdd:plan)
├── research.md       # Technical research & decisions (/sdd:plan)
├── data-model.md     # Entity definitions (/sdd:plan)
├── quickstart.md     # Integration scenarios (/sdd:plan)
├── contracts/        # Route and API contracts (/sdd:plan)
├── tasks.md          # Executable task list (/sdd:tasks)
├── checklists/       # Requirements quality checklists (/sdd:checklist)
└── validation-report.md  # Post-implementation drift report (/sdd:validate)

SDD Infrastructure (`.specify/`)

The .specify/ directory contains the scaffolding that powers SDD commands. It is optional for normal prompting; you only need it for the /sdd:* and /sdd-change:* workflows:

templates/ — Markdown templates for specs, plans, tasks, checklists, constitutions, and agent context files
scripts/bash/ — Shell scripts for branch creation, prerequisite checking, plan setup, and agent context updates
memory/ — Persistent project state (constitution, lessons learned across features)
init-options.json — Configuration (branch numbering mode, AI agent type)

SDD supports extensibility via .specify/extensions.yml for before/after hooks on any command, template overrides in .specify/templates/overrides/, and presets in .specify/presets/.

Key SDD Concepts

Constitution — Non-negotiable project principles validated at every planning gate
Lessons Learned — Cross-feature learnings accumulate in .specify/memory/lessons-learned.md and feed into future planning and implementation
Adversarial Spec Review — /sdd:spec-review challenges the spec from security, performance, edge-case, scalability, and compliance perspectives before planning begins
Specs are stakeholder-facing — No implementation details; focus on WHAT and WHY
Checklists are "unit tests for English" — They validate requirements quality, not implementation correctness
Tasks organized by user story — Each story is independently implementable and testable (MVP-first)
Fresh-context implementation — /sdd:implement-subagents spawns a clean subagent per task, preventing context rot on large features
Post-implementation validation — /sdd:validate uses a 4-layer hybrid approach (structural scan, test mapping, AI semantic analysis, acceptance test generation) to verify the code matches the spec — works on day one, no code annotations needed

SDD Small-Change (Lightweight Mode)

For bug fixes and small features that don't need the full SDD ceremony. Three commands, no plan, no checklists, no analysis — just specify, task, implement.

Commands (`.claude/commands/sdd-change/`)

Command	Purpose
`/sdd-change:specify`	Create a minimal change spec (problem, fix, acceptance criteria, files affected)
`/sdd-change:tasks`	Generate a flat 3-8 task list from the change spec
`/sdd-change:implement`	Execute tasks sequentially with validation

Workflow

/sdd-change:specify Fix login timeout — sessions expire after 5min instead of 30
/sdd-change:tasks
/sdd-change:implement

When to Use Which

Situation	Use
Bug fix, patch, tweak	`/sdd-change:specify`
New feature, multi-story epic	`/sdd:specify`
Refactor touching 1-3 files	`/sdd-change:specify`
Refactor touching 6+ files	`/sdd:specify`

The lightweight pipeline warns you if your change looks too complex (>3 acceptance criteria or >6 files affected) and suggests switching to the full pipeline.

Scripts (`scripts/`)

Script	Purpose
`start_rails_tmux.sh`	Open (or reuse) a tmux session with a three-pane main-vertical layout: editor on the left, `bin/dev` (or `bin/rails server`) top-right, `bin/rails console` bottom-right. Idempotent — re-running attaches to the existing session and auto-restarts any pane that has dropped back to a shell prompt.
`sync_claude_skills_to_codex.sh`	Mirror `.claude/skills/` into `.agents/skills/` for OpenAI Codex compatibility
`sync_claude_rules_to_copilot.sh`	Generate `.github/instructions/claude-rules/` bridge files from `.claude/rules/` for GitHub Copilot

MCP Servers (`mcp/`)

Custom MCP servers that extend Claude Code with external integrations.

Server	Purpose	Docs
`sentry_monitor`	Exposes Sentry production errors as Claude Code tools — query issues, map stack traces to local files, detect new errors with persistent state tracking, PII redaction by default	README

Documentation

Document	Purpose
Your First SDD Feature	Step-by-step onboarding walkthrough for new developers using the SDD kit
SDD Team Scalability Analysis	Risks, gaps, and roadmap for scaling SDD to a 30-developer team
Rails Development Principles	Universal software principles, Rails doctrine, modern Rails 8 architecture, testing, security, and performance
Prompt Engineering for Claude Code	Writing effective prompts for Claude Code in web development, with Rails-specific patterns
Claude Code Extensibility Guide	All extension mechanisms: CLAUDE.md, skills, hooks, subagents, Agent Teams, MCP servers, and plugins
Claude Code Frontmatter Reference	YAML frontmatter syntax for configuring agents, skills, and commands in `.claude/` files
MCP Servers for Rails	Extending Claude Code with Model Context Protocol servers for Rails, databases, and APIs
PRD Best Practices	Writing effective Product Requirements Documents in agile, AI-in-the-loop environments
Technical Design Documents	TDDs, ADRs, and Engineering RFCs for agentic SDLC teams
Design Specifications	UI/UX design specs and API specifications (OpenAPI) for frontend/backend contracts
Specification Document Hierarchy	Reference map showing which documents answer which core questions
AI Terminology Glossary	289 AI/ML terms across 25 categories — also available as a browsable HTML version

License

MIT