RANA Documentation

Welcome to the RANA (Rapid AI Native Architecture) documentation. RANA is a comprehensive framework that ensures AI coding assistants produce production-quality code.

What is RANA?

RANA is like ESLint for your entire AI-assisted development workflow. It provides:

  • Development principles that guide AI assistants to follow best practices
  • Quality gates that catch common mistakes before they reach production
  • Workflows that ensure features are complete, tested, and deployed
  • Universal standards that work with any tech stack, IDE, or AI assistant
💡 Tip: RANA works with any AI assistant including Claude, ChatGPT, GitHub Copilot, Cursor, and more.

Installation

Install the RANA CLI globally using npm:

npm install -g @rana/cli

Requirements

  • Node.js 16.x or higher
  • npm or yarn package manager
  • Git (for deployment workflows)

Verify Installation

After installation, verify it's working:

rana --version

Quick Start

Get started with RANA in your project in under 60 seconds:

Step 1: Initialize RANA

Navigate to your project directory and run:

cd your-project
rana init

This creates a .rana.yml configuration file with smart defaults for your project.

Step 2: Configure Standards

Edit .rana.yml to match your project's needs. The default configuration includes:

version: 1.0.0

project:
  name: "Your Project"
  type: "fullstack"

standards:
  principles:
    - search_before_create
    - real_data_only
    - test_everything
    - deploy_to_production

quality_gates:
  implementation:
    - no_mock_data
    - error_handling_required
    - loading_states_required

  testing:
    - manual_testing_required
    - e2e_tests_required

  deployment:
    - git_commit_required
    - production_verification

Step 3: Start Building

Use RANA workflows to guide your AI assistant:

rana flow feature "Add user authentication"
📝 Note: Your AI assistant will automatically read and follow the RANA configuration when working in your project.

Configuration Basics

The .rana.yml file is the heart of RANA. It defines your project's standards, quality gates, and workflows.

File Structure

A typical RANA configuration includes:

  • version: RANA spec version (currently 1.0.0)
  • project: Project metadata and settings
  • standards: Development principles and requirements
  • quality_gates: Automated checks and validations
  • deployment: Deployment and verification settings
  • ai_assistant: Instructions for AI assistants

Project Configuration

project:
  name: "My Awesome App"
  type: "fullstack"  # Options: frontend, backend, fullstack, mobile, cli
  description: "Brief description of your project"
  languages:
    - "typescript"
    - "react"
  tech_stack:
    frontend: "React + TypeScript"
    backend: "Node.js + Express"
    database: "PostgreSQL"

Development Principles

RANA enforces five core principles that guide AI assistants to produce production-quality code:

1. Search Before Creating

AI assistants must search for existing implementations before creating new ones. This prevents code duplication and ensures consistency.

standards:
  principles:
    - search_before_create

What it prevents:

  • Duplicate components, utilities, and functions
  • Inconsistent patterns across the codebase
  • Reinventing existing solutions

2. Real Data Only

No mock data, no placeholders. Every implementation must use real APIs, databases, and services.

standards:
  principles:
    - real_data_only

quality_gates:
  implementation:
    - no_mock_data

What it prevents:

  • Mock data arrays in production code
  • Placeholder text and fake user data
  • Commented-out "TODO: connect to real API"

3. Test Everything

Features must be tested both manually and with automated tests before they're considered complete.

standards:
  principles:
    - test_everything
  testing:
    manual_testing_required: true
    unit_tests_required: true
    e2e_tests_required: true
    coverage_threshold: 80

What it ensures:

  • Manual testing steps documented and completed
  • Unit tests for business logic
  • End-to-end tests for critical user flows
  • Code coverage meets threshold

4. Design System Compliance

AI assistants must use existing design system components and follow established patterns.

standards:
  design_system:
    path: "src/components/design-system"
    enforce_usage: true
    document_path: "docs/DESIGN_SYSTEM.md"

What it ensures:

  • Consistent UI/UX across the application
  • Reusable component patterns
  • Brand compliance and accessibility

5. Deploy to Production

Features aren't done until they're deployed, verified, and working in production.

standards:
  principles:
    - deploy_to_production

quality_gates:
  deployment:
    - git_commit_required
    - production_verification
    - smoke_tests_passing

What it ensures:

  • Code is committed to version control
  • Changes are deployed to production
  • Production verification confirms it works
  • Rollback plan is in place

Quality Gates

Quality gates are automated checks that prevent common AI mistakes. They're organized by development phase:

Pre-Implementation Gates

quality_gates:
  pre_implementation:
    - check_existing_code
    - review_documentation
    - understand_requirements
    - plan_architecture

Implementation Gates

quality_gates:
  implementation:
    - no_mock_data
    - error_handling_required
    - loading_states_required
    - typescript_strict_mode
    - meaningful_variable_names
    - dry_principle

Testing Gates

quality_gates:
  testing:
    - manual_testing_complete
    - unit_tests_passing
    - integration_tests_passing
    - e2e_tests_passing
    - coverage_meets_threshold

Deployment Gates

quality_gates:
  deployment:
    - git_commit_required
    - version_bumped
    - changelog_updated
    - production_verification
    - smoke_tests_passing
⚠️ Warning: Quality gates are enforced automatically. If any gate fails, the AI assistant should stop and resolve the issue before proceeding.

Workflows

RANA provides predefined workflows for common development tasks:

Feature Workflow

rana flow feature "Add user dashboard"

This workflow guides AI through:

  1. Planning and architecture
  2. Implementation with quality checks
  3. Testing (manual and automated)
  4. Deployment and verification

Bug Fix Workflow

rana flow bugfix "Fix login error on mobile"

This workflow includes:

  1. Reproducing the bug
  2. Identifying root cause
  3. Implementing fix
  4. Testing across environments
  5. Deploying and verifying

Refactor Workflow

rana flow refactor "Optimize API calls"

Ensures refactoring doesn't break functionality:

  1. Document current behavior
  2. Run existing tests
  3. Make improvements
  4. Verify tests still pass
  5. Performance comparison

CLI Commands

Complete reference for RANA CLI commands:

rana init

Initialize RANA in your project. Creates a .rana.yml configuration file with smart defaults.

rana init
rana init --template react
rana init --template nextjs

rana check

Check compliance with RANA standards. Validates your code against quality gates.

rana check
rana check --verbose
rana check --fix

rana validate

Validate your .rana.yml configuration file for syntax and completeness.

rana validate
rana validate --strict

rana flow

Start a development workflow. Guides AI through complete feature development.

rana flow feature "description"
rana flow bugfix "description"
rana flow refactor "description"

rana deploy

Deploy with verification. Ensures deployment succeeds and production works.

rana deploy
rana deploy --verify
rana deploy --environment staging

rana config

Show current configuration and settings.

rana config
rana config --json
rana config show standards

CLI Options

Global options available for all commands:

Common Options

  • --verbose - Show detailed output and logs
  • --quiet - Suppress non-essential output
  • --config <path> - Use custom config file path
  • --help - Show help for a command
  • --version - Show RANA version

Configuration Options

  • --template <name> - Use a specific template
  • --strict - Enable strict validation mode
  • --fix - Automatically fix issues where possible

Working with AI Assistants

RANA is designed to work seamlessly with any AI coding assistant.

Supported AI Assistants

  • Claude (Anthropic) - Full support via .clauderules or direct instructions
  • ChatGPT (OpenAI) - Full support via custom instructions or project files
  • GitHub Copilot - Supported via workspace settings
  • Cursor - Native support via .cursorrules
  • Replit AI - Supported via project configuration
  • Any LLM-based assistant - Works with any tool that can read project files

How AI Assistants Use RANA

AI assistants automatically detect and follow RANA configuration:

  1. Read .rana.yml configuration at project start
  2. Follow defined principles and quality gates
  3. Execute workflows step by step
  4. Validate compliance before moving to next phase
  5. Report completion with verification evidence
💡 Pro Tip: You can reference specific RANA principles when instructing your AI assistant: "Please follow the search_before_create principle and check for existing authentication components."

Custom AI Instructions

Add custom instructions for your AI assistant:

ai_assistant:
  instructions_path: "docs/AGENT_INSTRUCTIONS.md"
  checklist_path: "docs/DEVELOPMENT_CHECKLIST.md"
  enforce:
    - no_mock_data
    - real_implementations_only
    - existing_patterns_first

Best Practices

1. Start with Smart Defaults

Use rana init to generate a configuration with sensible defaults, then customize as needed.

2. Document Your Design System

Create a DESIGN_SYSTEM.md file documenting your components, patterns, and styles. AI assistants will follow it automatically.

3. Keep Quality Gates Reasonable

Don't enable every possible quality gate. Start with essentials and add more as your team matures.

4. Use Workflows Consistently

Always use rana flow commands for features and bugs. This ensures consistent process across your team.

5. Verify Before Merging

Run rana check before creating pull requests to catch issues early.

6. Update Configuration Regularly

As your project evolves, update .rana.yml to reflect new patterns, requirements, and standards.

📝 Team Tip: Add RANA checks to your CI/CD pipeline to enforce standards automatically.

Troubleshooting

AI Assistant Not Following Standards

Problem: AI creates mock data or ignores design system.

Solution:

  • Verify .rana.yml exists in project root
  • Run rana validate to check configuration
  • Explicitly reference RANA principles in your prompts
  • Check if AI assistant has file reading permissions

Quality Gates Failing

Problem: rana check reports failures.

Solution:

  • Run rana check --verbose for detailed errors
  • Use rana check --fix to auto-fix where possible
  • Review quality_gates configuration for strictness

CLI Command Not Found

Problem: Terminal doesn't recognize rana command.

Solution:

# Reinstall globally
npm install -g @rana/cli

# Verify installation
which rana
rana --version

Configuration Not Loading

Problem: Changes to .rana.yml don't take effect.

Solution:

  • Validate YAML syntax: rana validate
  • Check file location (must be in project root)
  • Restart your AI assistant or IDE
  • Clear any caches: rana config --clear-cache

Need More Help?

If you're still having issues: