🤖 ruby-ai-gem-context

Make AI coding assistants actually understand your Ruby project.

Stop explaining your codebase over and over. This gem generates context files that AI assistants read before they help you — so they already know your architecture, conventions, and patterns.

---

The Problem

Every time you start a conversation with an AI coding assistant, you waste time explaining:

• "We use service objects, not fat models"
• "Authentication is handled by Devise with custom strategies"
• "Don't suggest RSpec — we use Minitest"

The solution: Context files that AI assistants read automatically.

Supported Platforms

Platform	File	Description
Claude Code	CLAUDE.md	Project context for Claude AI
Cursor	.cursorrules	Rules and context for Cursor IDE
Windsurf	.windsurfrules	Rules for Windsurf IDE
OpenAI Codex/ChatGPT	AGENTS.md	Documentation for AI agents
llm.txt	llm.txt	Universal LLM context (like robots.txt for AI)

Installation

Add to your Gemfile:

gem 'ruby-ai-gem-context'

Or install directly:

gem install ruby-ai-gem-context

⚡ Quick Start

# 1. Setup: Create boilerplate files for your chosen platforms
rake ai_context:setup

# 2. Generate: Fill files with AI-generated content from your code
rake ai_context:generate

# 3. Review and edit the generated files!

That's it. Your AI assistant now understands your project before you ask your first question.

🛠️ Rake Tasks

rake ai_context:setup

Interactive wizard to create boilerplate context files:

$ rake ai_context:setup

══════════════════════════════════════════════════
 AI Context Setup
══════════════════════════════════════════════════

Which platforms do you want to generate context files for?
  ◉ Claude Code (CLAUDE.md)
  ◯ Cursor (.cursorrules)
  ◉ Windsurf (.windsurfrules)
  ◯ OpenAI Codex / ChatGPT (AGENTS.md)
  ◯ llm.txt (llm.txt)

✓ Created CLAUDE.md
✓ Created .windsurfrules

If a file already exists, you'll be asked whether to skip, backup, or overwrite it.

rake ai_context:generate

Fill your context files with AI-generated content:

$ rake ai_context:generate

Where should we read source files from?
› Project root (scan everything)
  Specific folders (you'll provide a list)

Will scan 47 files (23.5 KB)
File types: .rb: 35, .rake: 5, .md: 7

Using model: claude-sonnet-4-20250514

⠋ Generating Claude Code context...
✓ Generated CLAUDE.md

⚠ IMPORTANT: Review the generated files carefully!
  AI-generated context is a first draft. The quality of your future
  AI interactions depends on the accuracy of these files.

rake ai_context:generate_for_gem[gem_name]

Generate context for a third-party gem:

rake ai_context:generate_for_gem[devise]

This reads the installed gem's source and generates context files saved to .ai_context/gems/devise/.

Other Tasks

rake ai_context:list   # List generated context files
rake ai_context:clear  # Remove generated files

⚙️ Configuration

Configure via Ruby:

RubyAiGemContext.configure do |config|
  # AI model to use (see "Choosing a Model" below)
  config.model = "claude-sonnet-4-20250514"

  # Generation parameters
  config.temperature = 0.3
  config.max_tokens = 4000

  # File patterns to scan
  config.include_patterns = %w[**/*.rb README* CHANGELOG*]
  config.exclude_patterns = %w[vendor/** spec/** test/**]
end

Or in Rails (config/application.rb):

config.ruby_ai_gem_context.model = "gpt-4o"

🧠 Choosing a Model

The model you choose directly affects the quality of generated context:

Model	Quality	Speed	Cost	Best For
claude-sonnet-4-20250514	High	Fast	Medium	Recommended - good balance
claude-opus-4-20250514	Highest	Slow	High	Complex codebases
claude-haiku-4-20250514	Good	Fastest	Low	Quick iterations
gpt-4o	High	Fast	Medium	OpenAI preference
gpt-4o-mini	Good	Fastest	Low	Budget-conscious

Important: Quality matters! The context files help AI understand your codebase. Poor context leads to poor AI assistance. Consider using a higher-quality model and reviewing the output carefully.

Setting Your API Key

The gem uses RubyLLM which auto-detects your API key from environment variables:

# For Anthropic Claude models
export ANTHROPIC_API_KEY=sk-ant-...

# For OpenAI models
export OPENAI_API_KEY=sk-...

⚠️ Review Your Generated Files

This is important: AI-generated context is a first draft, not a finished product.

The quality of your future AI interactions depends on accurate context files. Take time to:

1. Read through each generated file — Does it accurately describe your project?
2. Fix inaccuracies — Remove wrong assumptions, correct misunderstandings
3. Add project-specific details — Coding conventions, architecture decisions, gotchas
4. Remove generic content — Replace boilerplate with specifics
5. Keep it updated — Regenerate or manually update as your project evolves

💡 Think of it as an investment: 30 minutes reviewing context now saves hours of correcting AI mistakes later.

🏗️ Architecture

lib/ruby_ai_gem_context/
├── configuration.rb     # Global settings
├── platform.rb          # Base class for platforms
├── platforms/
│   ├── claude.rb        # CLAUDE.md
│   ├── cursor.rb        # .cursorrules
│   ├── windsurf.rb      # .windsurfrules
│   ├── codex.rb         # AGENTS.md
│   └── llm_txt.rb       # llm.txt
├── config_file.rb       # Track generated files in .ai_context/config.yml
├── file_collector.rb    # Scan and read project files
├── generator.rb         # AI generation via RubyLLM
├── interactive.rb       # Terminal UI with tty-prompt
├── railtie.rb           # Rails integration
└── tasks/
    └── ruby_ai_gem_context.rake

📋 Requirements

• Ruby 3.0+
• Rails 7.0+ (optional, for Railtie integration)

🧑‍💻 Development

git clone https://github.com/AAlvAAro/ruby-ai-gem-context
cd ruby-ai-gem-context
bundle install
rake spec

🤝 Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a Pull Request

📄 License

This gem is available as open source under the terms of the MIT License.