AI Code Generation for Ruby on Rails

ai_gen_rails_rules.json

{
  "meta": {
    "context": "You are an expert programming AI assistant prioritizing minimalist, efficient code and accepting user preferences even if suboptimal.",
    "interaction_rules": [
      "Clearly display the current step of the plan being executed.",
      "Ask for clarification if requirements are ambiguous.",
      "Always optimize for minimal code complexity and resource overhead.",
      "Explain reasoning at each step, highlighting assumptions and potential limitations."
    ],
    "workflow": {
      "role": "Expert software engineer focused on clean code, system design, and production-quality implementation.",
      "steps": [
        {
          "title": "1. Requirements Analysis",
          "details": [
            "Break down functional requirements.",
            "Define expected inputs/outputs.",
            "Identify constraints and edge cases."
          ]
        },
        {
          "title": "2. Technical Design",
          "details": [
            "Outline the system architecture or approach.",
            "Select appropriate data structures and algorithms.",
            "Identify necessary dependencies.",
            "Consider performance and scalability."
          ]
        },
        {
          "title": "3. Implementation & Review",
          "details": [
            "Develop modular, well-documented, and maintainable code.",
            "Implement comprehensive error handling and logging.",
            "Adhere to software engineering best practices (SOLID, DRY, KISS, Security).",
            "Include unit tests where applicable.",
            "Generate documentation following the specified guidelines.", 
          ]
        }
      ]
    },
    "documentation_guidelines": {
      "style_preference": "Use Markdown format, following YARD-like conventions suitable for Ruby code.",
      "required_elements": [
        "Purpose: Clear, concise explanation of what the code (class, module, method) does.",
        "Parameters (@param): For methods/functions, list each parameter with its expected type(s) and a clear description.",
        "Return Value (@return): Describe the return value and its type(s). Specify if nothing is returned or if exceptions might be raised.",
        "Usage Example: Provide one or more simple, practical code snippets demonstrating how to use the code.",
        "Assumptions/Limitations: Note any important prerequisites, assumptions made, or known limitations/edge cases."
      ],
      "placement": "Generate documentation as comments directly within the code (e.g., preceding methods/classes) or as a separate Markdown block when documenting a larger module, feature, or providing an overview."
    }
  },
  "guidelines": {
    "title": "Unified Software Engineering Guidelines",
    "sections": [
      {
        "id": 1,
        "title": "Vision and Philosophy",
        "items": [
          "Minimalism & Efficiency: Write clear, self-documenting code that is both minimal and effective—even if user preferences are suboptimal.",
          "Iterative Development: Adopt a candidate mindset, iterating on tasks 3–5 times until they are robust.",
          "Functionality First: Focus on delivering working solutions before engaging in premature optimization.",
          "Avoid Premature Refactoring: Shift your focus away from early code polishing or refactoring."
        ]
      },
      {
        "id": 2,
        "title": "Core Engineering Principles",
        "items": [
          "SOLID Principles: Always follow SOLID principles.",
          "DRY & KISS: Avoid repetition and unnecessary complexity.",
          "Defensive Programming: Include input validation, error handling, and logging.",
          "Security: Sanitize inputs and implement the principle of least privilege.",
          "Performance & Scalability: Optimize code with consideration for time and space complexities."
        ]
      },
      {
        "id": 3,
        "title": "Class Design and Organization",
        "items": [
          "Meaningful Naming: Define a class with a meaningful name.",
          "Service Naming: Avoid appending \"service\" if the class is located in the service folder.",
          "Constants: Establish constants for any magic strings and numbers.",
          "Favor Self-Contained Classes: Favor self-contained classes when an object isn't needed.",
          "Nested Classes: Nest classes within classes if there are 3 to 5 repetitions.",
          "Class Length: Aim to keep a class under 120 lines."
        ]
      },
      {
        "id": 4,
        "title": "Method Design and Implementation",
        "items": [
          "Conciseness: Keep method implementations concise, ideally not exceeding 5 to 8 lines.",
          "Argument Limits: Limit the argument list to a maximum of 0 to 5.",
          "Named Parameters: If argument names are tricky to recall, make them non-optional (e.g., (x: 34, y: 36) as named parameters).",
          "Descriptive Naming: Method names can be longer but should be clear and descriptive, indicating their purpose."
        ]
      },
      {
        "id": 5,
        "title": "Dependency Management and State Handling",
        "items": [
          "Dependency Injection: Use dependency injections without coupling them.",
          "State Management: Don't change object state within a service if the service is not about that data model."
        ]
      },
      {
        "id": 6,
        "title": "Service Patterns and Front-End Practices",
        "items": [
          "Service Objects: Create classes that adhere to the single responsibility principle.",
          "Ruby on Rails Conventions: Follow Rails best practices for organizing classes and services.",
          "Front-End Frameworks: Use Stimulus and Hotwire for front-end development."
        ]
      },
      {
        "id": 7,
        "title": "Testing, Logging, and Deployment",
        "items": [
          "Unit Testing: Write comprehensive tests that cover edge cases and potential errors.",
          "Logging: Implement logging at appropriate levels to aid debugging and production monitoring.",
          "CI/CD: Integrate continuous integration and deployment practices to maintain code quality and rapid iteration."
        ]
      },
      {
        "id": 8,
        "title": "Documentation and Iterative Improvement",
        "items": [
          "API Documentation: Provide clear documentation that explains the 'why' behind design decisions.", 
          "Iterative Enhancement: Continuously revisit and refine code until it meets our high standards for quality and clarity."
        ]
      },
      {
        "id": 9,
        "title": "References",
        "items": [
          "Official Ruby on Rails Guides: https://guides.rubyonrails.org/",
          "Hotwire Documentation: https://hotwired.dev/",
          "Phlex Documentation: https://www.phlex.fun/",
          "Community Ruby Style Guide: https://github.com/rubocop/ruby-style-guide",
          "Ruby on Rails Community Forum: https://rubyonrails.link/",
          "Ruby on Rails Community Wiki: https://rubyonrails.link/wiki",
          "Ruby on Rails Style guide: https://rails.rubystyle.guide",
          "Ruby Style Guide: https://rubystyle.guide"
        ]
      }
    ]
  }
}

gem_preferences.json

 "gem_preferences": {
    "styling": "Tailwind CSS",
    "minimalist_components": "https://github.com/lazaronixon/css-zero",
    "enhanced_ui_components": "https://github.com/phlex-ruby/phlex-rails"
  },
  "gems": {
    "main_gems": [
      {
        "category": "Admin Panel",
        "gems": [
          {
            "name": "rails-admin",
            "description": "A framework for creating admin panels for Rails applications.",
            "link": "https://github.com/railsadminteam/rails_admin"
          }
        ]
      },
      {
        "category": "Analytics",
        "gems": [
          {
            "name": "ahoy_matey",
            "description": "A library for tracking visits, events, and user behavior in Rails apps.",
            "link": "https://github.com/ankane/ahoy"
          }
        ]
      },
      {
        "category": "Authorization",
        "gems": [
          {
            "name": "cancancan",
            "description": "Authorization library for controlling user access.",
            "link": "https://github.com/CanCanCommunity/cancancan"
          }
        ]
      },
      {
        "category": "Code Documentation",
        "gems": [
          {
            "name": "annotate",
            "description": "Annotates Rails models, fixtures, and tests with schema information.",
            "link": "https://github.com/ctran/annotate_models"
          }
        ]
      },
      {
        "category": "Code Quality",
        "gems": [
          {
            "name": "rubocop",
            "description": "A Ruby code style and linting tool.",
            "link": "https://github.com/rubocop/rubocop"
          },
          {
            "name": "rubocop-rails-omakase",
            "description": "Rails-specific code linting standards for Rubocop.",
            "link": "https://github.com/rubocop/rubocop-rails"
          },
          {
            "name": "rubycritic",
            "description": "A static code analysis tool that generates quality reports for Ruby projects.",
            "link": "https://github.com/whitesmith/rubycritic"
          }
        ]
      },
      {
        "category": "Data Visualization",
        "gems": [
          {
            "name": "chartkick",
            "description": "Simplifies creating JavaScript charts in Rails apps.",
            "link": "https://github.com/ankane/chartkick"
          }
        ]
      },
      {
        "category": "Feature Flags",
        "gems": [
          {
            "name": "flipper",
            "description": "A feature flagging library for enabling/disabling features.",
            "link": "https://github.com/jnunemaker/flipper"
          },
          {
            "name": "flipper-ui",
            "description": "Provides a web interface for managing Flipper feature flags.",
            "link": "https://github.com/jnunemaker/flipper"
          }
        ]
      },
      {
        "category": "Pagination",
        "gems": [
          {
            "name": "pagy",
            "description": "Ultra-lightweight pagination for Rails.",
            "link": "https://github.com/ddnexus/pagy"
          }
        ]
      },
      {
        "category": "Payments",
        "gems": [
          {
            "name": "pay",
            "description": "Simplifies payment processing for Rails apps.",
            "link": "https://github.com/pay-rails/pay"
          },
          {
            "name": "stripe",
            "description": "Library for integrating Stripe payment processing.",
            "link": "https://github.com/stripe/stripe-ruby"
          }
        ]
      },
      {
        "category": "SEO",
        "gems": [
          {
            "name": "sitemap-generator",
            "description": "Generates sitemaps for Rails applications.",
            "link": "https://github.com/kjvarga/sitemap_generator"
          },
          {
            "name": "meta-tags",
            "description": "Simplifies adding meta tags for SEO in Rails applications.",
            "link": "https://github.com/kpumuk/meta-tags"
          }
        ]
      },
      {
        "category": "Design",
        "gems": [
          {
            "name": "rails_icon",
            "description": "Add any icon library to a Rails app. Rails Icons has first-party support for a handful of libraries. It is library agnostic so it can be used with any icon library using the same interface.",
            "link": "https://github.com/Rails-Designer/rails_icons"
          }
        ]
      }
    ],
    "nice_to_have": [
      {
        "category": "Audit Logging",
        "gems": [
          {
            "name": "paper_trail",
            "description": "Tracks changes to models over time.",
            "link": "https://github.com/paper-trail-gem/paper_trail"
          }
        ]
      },
      {
        "category": "Scheduling",
        "gems": [
          {
            "name": "whenever",
            "description": "Cron job scheduler for Ruby applications.",
            "link": "https://github.com/javan/whenever"
          }
        ]
      }
    ]
  },

requirements.json

{
  "project_name": "Modern Rails Application",
  "document_purpose": "This document defines essential project requirements, tracks development progress, and provides implementation guidelines for a Ruby on Rails application with Hotwire and Phlex.",
  "tech_stack": {
    "backend": "Ruby on Rails 8+",
    "frontend": "Hotwire (Turbo + Stimulus)",
    "view_components": "Phlex with RubyUI.com components",
    "styling": "Tailwind CSS",
    "database": "PostgreSQL",
    "testing": "mini tests"
  },
  "principles": [
    "Each requirement must include clear setup steps, implementation details, and test commands",
    "Follow Ruby on Rails conventions and modern best practices",
    "Use Hotwire for dynamic interfaces without heavy JavaScript",
    "Leverage Phlex for type-safe view components with Ruby syntax",
    "Prioritize maintainability, testability, and developer experience"
  ],
  "requirements_format": {
    "functional_requirement": {
      "id": "Unique identifier (REQ-FUNC-XXX)",
      "name": "Short descriptive name",
      "description": "Detailed explanation of the requirement",
      "status": ["pending", "in_progress", "completed", "blocked"],
      "priority": ["high", "medium", "low"],
      "files_affected": {
        "new": ["List of files to be created"],
        "modified": ["List of files to be modified"],
        "deleted": ["List of files to be deleted"]
      },
      "database_changes": {
        "tables": ["Tables that need to be created or modified"],
        "migrations": ["Migration names required"]
      },
      "implementation_details": {
        "gems": ["Required gems with versions"],
        "setup_steps": ["Step-by-step implementation instructions"],
        "code_examples": ["Key code snippets showing implementation approach"]
      },
      "testing_strategy": {
        "unit_tests": ["Description of unit tests to be created"],
        "integration_tests": ["Description of integration tests to be created"],
        "test_commands": ["Commands to run for testing this requirement"]
      },
      "hotwire_components": {
        "turbo_frames": ["Description of Turbo Frames to implement"],
        "turbo_streams": ["Description of Turbo Streams to implement"],
        "stimulus_controllers": ["Description of Stimulus controllers to implement"]
      },
      "phlex_components": {
        "component_structure": "Description of Phlex component hierarchy",
        "reusable_components": ["List of reusable Phlex components to create"]
      }
    },
    "non_functional_requirement": {
      "id": "Unique identifier (REQ-NFR-XXX)",
      "name": "Short descriptive name",
      "description": "Detailed explanation of the requirement",
      "status": ["pending", "in_progress", "completed", "blocked"],
      "priority": ["high", "medium", "low"],
      "category": ["performance", "security", "scalability", "accessibility", "usability"],
      "acceptance_criteria": ["Measurable criteria for requirement fulfillment"],
      "implementation_approach": ["How this requirement will be addressed"],
      "testing_strategy": {
        "benchmark_tests": ["Performance tests to be conducted"],
        "load_tests": ["Load testing approach"],
        "security_tests": ["Security testing approach"],
        "test_commands": ["Commands to verify this requirement"]
      }
    }
  },
  "progress_tracking": {
    "feature_implementation_log": {
      "entry_format": {
        "date": "YYYY-MM-DD",
        "feature": "Feature name",
        "developer": "Developer name",
        "requirements_addressed": ["REQ-FUNC-XXX", "REQ-NFR-XXX"],
        "changes_implemented": {
          "description": "Summary of changes made",
          "files_changed": ["List of files changed"],
          "commits": ["Relevant commit hashes"]
        },
        "challenges": ["Description of any challenges encountered"],
        "solutions": ["How challenges were resolved"],
        "next_steps": ["Planned next implementation steps"]
      }
    },
    "error_tracking": {
      "entry_format": {
        "error_id": "ERR-XXX",
        "description": "Brief description of the error",
        "status": ["open", "investigating", "resolved"],
        "environment": ["development", "test", "production"],
        "related_requirements": ["REQ-FUNC-XXX"],
        "error_details": {
          "location": "File path and line number",
          "stack_trace": "Relevant portion of stack trace",
          "error_message": "Exact error message"
        },
        "diagnosis": "Analysis of the root cause",
        "resolution": {
          "fix_description": "Description of the fix implemented",
          "files_changed": ["List of files modified to fix the issue"],
          "commits": ["Commit hash with the fix"]
        }
      }
    }
  },
  "sample_requirements": [
    {
      "id": "REQ-FUNC-001",
      "name": "User Authentication with Devise",
      "description": "Implement secure user authentication with Devise, including sign-up, login, and password reset functionality",
      "status": "pending",
      "priority": "high",
      "files_affected": {
        "new": [
          "app/models/user.rb",
          "app/views/devise/*",
          "app/components/users/authentication_form.rb"
        ],
        "modified": [
          "config/routes.rb",
          "app/controllers/application_controller.rb"
        ],
        "deleted": []
      },
      "database_changes": {
        "tables": ["users"],
        "migrations": ["DeviseCreateUsers"]
      },
      "implementation_details": {
        "gems": ["devise ~> 4.9"],
        "setup_steps": [
          "Add 'devise' gem to Gemfile",
          "Run bundle install",
          "Run rails generate devise:install",
          "Configure Devise in config/initializers/devise.rb",
          "Generate User model: rails generate devise User",
          "Run rails db:migrate",
          "Create Phlex component for authentication forms"
        ],
        "code_examples": [
          "# app/components/users/authentication_form.rb\nmodule Users\n  class AuthenticationForm < ApplicationComponent\n    def initialize(resource:, url:, method: :post)\n      @resource = resource\n      @url = url\n      @method = method\n    end\n\n    def template\n      RubyUI::Form.new(action: @url, method: @method) do\n        div(class: \"space-y-4\") do\n          div do\n            RubyUI::Label.new(for: \"email\") { \"Email\" }\n            RubyUI::Input.new(type: \"email\", name: \"email\", id: \"email\", required: true)\n          end\n          \n          div do\n            RubyUI::Label.new(for: \"password\") { \"Password\" }\n            RubyUI::Input.new(type: \"password\", name: \"password\", id: \"password\", required: true)\n          end\n          \n          div do\n            RubyUI::Button.new(type: \"submit\", variant: \"primary\") { \"Sign in\" }\n          end\n        end\n      end\n    end\n  end\nend"
        ]
      },
      "testing_strategy": {
        "unit_tests": [
          "Test User model validations and associations",
          "Test authentication success and failure cases"
        ],
        "integration_tests": [
          "Test user registration flow",
          "Test login and logout process",
          "Test password reset functionality"
        ],
        "test_commands": [
          "rspec spec/models/user_spec.rb",
          "rspec spec/system/user_authentication_spec.rb"
        ]
      },
      "hotwire_components": {
        "turbo_frames": [
          "Login form in turbo frame for modal display"
        ],
        "turbo_streams": [
          "Update header with user info on successful authentication"
        ],
        "stimulus_controllers": [
          "Authentication controller for form validation and submission"
        ]
      },
      "phlex_components": {
        "component_structure": "Utilize Ruby UI components from rubyui.com with Phlex for authentication forms",
        "reusable_components": [
          "RubyUI::Form",
          "RubyUI::Input",
          "RubyUI::Button",
          "RubyUI::Alert"
        ]
      }
    },
    {
      "id": "REQ-FUNC-002",
      "name": "Reactive UI with Hotwire and Phlex",
      "description": "Implement a modern, reactive UI using Hotwire (Turbo + Stimulus) with Phlex components for server-rendered views",
      "status": "pending",
      "priority": "high",
      "files_affected": {
        "new": [
          "app/components/application_component.rb",
          "app/components/ui/button.rb",
          "app/components/ui/card.rb",
          "app/components/ui/form.rb",
          "app/javascript/controllers/live_update_controller.js"
        ],
        "modified": [
          "app/views/layouts/application.html.erb",
          "config/importmap.rb"
        ],
        "deleted": []
      },
      "database_changes": {
        "tables": [],
        "migrations": []
      },
      "implementation_details": {
        "gems": [
          "phlex-rails ~> 1.0",
          "turbo-rails ~> 1.4",
          "stimulus-rails ~> 1.2",
          "ruby_ui ~> 0.1"
        ],
        "setup_steps": [
          "Add required gems to Gemfile",
          "Run bundle install",
          "Set up base ApplicationComponent for Phlex",
          "Create reusable UI components using Phlex",
          "Configure Stimulus controllers for interactive behavior",
          "Implement Turbo Frames and Streams for real-time updates"
        ],
        "code_examples": [
          "# app/components/dashboard/stats_card.rb\nmodule Dashboard\n  class StatsCard < ApplicationComponent\n    def initialize(title:, value:, change: nil, change_type: nil)\n      @title = title\n      @value = value\n      @change = change\n      @change_type = change_type # :increase or :decrease\n    end\n\n    def template\n      RubyUI::Card.new do\n        div(class: \"p-4\") do\n          h3(class: \"text-sm font-medium text-gray-500\") { @title }\n          div(class: \"mt-1 flex items-baseline\") do\n            p(class: \"text-2xl font-semibold text-gray-900\") { @value }\n            if @change.present?\n              p(class: change_class) do\n                span(class: \"sr-only\") { @change_type == :increase ? \"Increased by\" : \"Decreased by\" }\n                \" #{@change}%\"\n              end\n            end\n          end\n        end\n      end\n    end\n    \n    private\n    \n    def change_class\n      base_class = \"ml-2 text-sm font-semibold\"\n      if @change_type == :increase\n        \"#{base_class} text-green-600\"\n      else\n        \"#{base_class} text-red-600\"\n      end\n    end\n  end\nend"
        ]
      },
      "testing_strategy": {
        "unit_tests": [
          "Test Phlex component rendering",
          "Test Stimulus controller behavior"
        ],
        "integration_tests": [
          "Test user interactions with Turbo and Stimulus",
          "Test real-time updates with Turbo Streams"
        ],
        "test_commands": [
          "rspec spec/components/ui/button_spec.rb",
          "rspec spec/system/interactive_ui_spec.rb"
        ]
      },
      "hotwire_components": {
        "turbo_frames": [
          "Content frames for partial page updates",
          "Form frames for in-place editing"
        ],
        "turbo_streams": [
          "Real-time updates for data changes",
          "Toast notifications for user feedback"
        ],
        "stimulus_controllers": [
          "live-update-controller for auto-refreshing content",
          "form-controller for enhanced form interactions",
          "modal-controller for modal dialogs"
        ]
      },
      "phlex_components": {
        "component_structure": "Create a hierarchy of UI components with ApplicationComponent as the base class",
        "reusable_components": [
          "UI::Button",
          "UI::Card",
          "UI::Form",
          "UI::Modal",
          "UI::Notification"
        ]
      }
    },
    {
      "id": "REQ-NFR-001",
      "name": "Performance Optimization",
      "description": "Ensure the application loads and responds quickly under various conditions",
      "status": "pending",
      "priority": "medium",
      "category": "performance",
      "acceptance_criteria": [
        "Page load time under 1.5 seconds for the main application pages",
        "Server response time under 200ms for API endpoints",
        "Smooth scrolling and interactions at 60fps"
      ],
      "implementation_approach": [
        "Set up proper caching with Redis",
        "Configure Turbo Drive for faster navigation",
        "Implement view component caching with Phlex",
        "Use database query optimization techniques",
        "Configure proper Puma settings for production"
      ],
      "testing_strategy": {
        "benchmark_tests": [
          "Benchmark page load times with rack-mini-profiler",
          "Measure database query performance"
        ],
        "load_tests": [
          "Use k6 or ApacheBench for simulating concurrent users",
          "Test with realistic user scenarios"
        ],
        "security_tests": [],
        "test_commands": [
          "RAILS_ENV=production bundle exec rake perf:test",
          "k6 run load_test.js"
        ]
      }
    }
  ]
}