🤖 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.

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.

Add to your Gemfile:

gem 'ruby-ai-gem-context'

Or install directly:

gem install ruby-ai-gem-context

# 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.

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.

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.

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/.

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

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"

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

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.

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-...

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.

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

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

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

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

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