import { Cards, Card } from 'fumadocs-ui/components/card'; import { Callout } from 'fumadocs-ui/components/callout'; import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; import { Steps, Step } from 'fumadocs-ui/components/steps'; import { Files, Folder, File } from 'fumadocs-ui/components/files';

AI Development Guides Setup Guide

This guide will help you install and configure Motia's AI Development Guides in your project. These guides are designed to work with any AI tool or IDE—including Cursor, VS Code, Claude, ChatGPT, and more.

Motia's guides are universal and work with any AI tool or IDE—not just Cursor!

Prerequisites

Latest Node.js runtime for CLI tools Create one with npx motia@latest create Any AI-powered code editor or AI assistant

Installation Methods

<Tabs items={["CLI (Recommended)", "Manual Setup", "Git Submodule"]}> ### Create a new Motia project bash npx motia@latest create my-motia-app cd my-motia-app ### Pull AI development guides bash npx motia@latest rules pull This will create the following in your project root: - AGENTS.md – Universal AI guide for ANY AI tool or IDE - CLAUDE.md – Claude-specific guide with advanced techniques - .cursor/rules/ – IDE-specific patterns for Cursor - .claude/ – Claude IDE configurations and commands ### Create the Cursor rules directory bash mkdir -p .cursor/rules ### Copy from local installation ```bash # If you have Motia installed locally or globally mkdir -p .cursor/rules

    # Copy Cursor IDE rules
    cp -r node_modules/motia/dist/dot-files/.cursor/rules/* .cursor/rules/

    # Copy AI development guides to project root
    cp node_modules/motia/dist/dot-files/AGENTS.md ./AGENTS.md
    cp node_modules/motia/dist/dot-files/CLAUDE.md ./CLAUDE.md

    # Copy Claude IDE configurations
    cp -r node_modules/motia/dist/dot-files/.claude ./.claude
    ```
    > **Important:** Only copy `.mdc` rule files into `.cursor/rules/`.
    > **CLAUDE.md** should be in your project root, **not** inside `.cursor/rules/`.
  </Step>
  <Step>
    ### Or download from GitHub
    ```bash
    # Download and extract Motia repository
    curl -L https://github.com/MotiaDev/motia/archive/main.zip -o motia.zip
    unzip motia.zip

    # Create directories
    mkdir -p .cursor/rules

    # Copy Cursor IDE rules
    cp -r motia-main/packages/snap/dist/dot-files/.cursor/rules/* .cursor/rules/

    # Copy AI development guides to project root
    cp motia-main/packages/snap/dist/dot-files/AGENTS.md ./AGENTS.md
    cp motia-main/packages/snap/dist/dot-files/CLAUDE.md ./CLAUDE.md

    # Copy Claude IDE configurations
    cp -r motia-main/packages/snap/dist/dot-files/.claude ./.claude

    # Clean up
    rm -rf motia.zip motia-main
    ```
    > **Critical:** Do **not** place AGENTS.md or CLAUDE.md inside `.cursor/rules/`. They belong in project root.
    > The `.claude` folder contains Claude IDE-specific configurations and should be in your project root.
  </Step>
</Steps>

Perfect for teams wanting to stay synchronized with updates ### Add as submodule ```bash git submodule add https://github.com/MotiaDev/motia.git .motia-source ``` ### Create symlinks for AI guides and rules ```bash # Create directories mkdir -p .cursor/rules

    # Symlink Cursor IDE rules
    ln -s ../.motia-source/packages/snap/dist/dot-files/.cursor/rules/* .cursor/rules/

    # Copy AI development guides to project root
    cp .motia-source/packages/snap/dist/dot-files/CLAUDE.md ./CLAUDE.md
    cp .motia-source/packages/snap/dist/dot-files/AGENTS.md ./AGENTS.md
    ```
    > **Important:** Do **not** symlink or copy AGENTS.md or CLAUDE.md into `.cursor/rules/`.
    > These files should always be in your project root.
  </Step>
  <Step>
    ### Update AI guides and rules (when needed)
    ```bash
    # Update submodule to latest version
    git submodule update --remote

    # Re-copy AI guides if they were updated
    cp .motia-source/packages/snap/dist/dot-files/CLAUDE.md ./CLAUDE.md
    cp .motia-source/packages/snap/dist/dot-files/AGENTS.md ./AGENTS.md
    ```
  </Step>
</Steps>

Project Structure After Setup

After installation, your project should look like this:

Universal AI guide for ANY AI tool or IDE (project root) Claude-specific guide with advanced techniques (project root) Complete app patterns Backend generator JS/TS/Python/Ruby API patterns Event processing Auth patterns Background jobs Real-time features AI agents Business workflows DevOps patterns REST API best practices Data persistence patterns Testing strategies TypeScript patterns Step modifications System architecture Scheduled tasks Workflow connections Custom UI components Claude-specific guide Command templates and patterns AI agent configurations Pre/post-deployment scripts Claude IDE settings Your Motia workflow steps Project dependencies Motia configuration

Important:

AGENTS.md and CLAUDE.md should be in your project root, not inside .cursor/rules/.

The .claude folder should be in your project root and contains Claude IDE configurations.

Only .mdc rule files go inside .cursor/rules/.

Configuration for Different AI Tools

Cursor IDE Setup

Open your project in Cursor.
Cursor will automatically detect the .cursor/rules/ directory and use the .mdc rule files for suggestions.
Reference AGENTS.md (in your project root) for universal patterns and guidance.
Use CLAUDE.md for Claude-specific advanced techniques.

VS Code with GitHub Copilot

Install the GitHub Copilot extension.
Open AGENTS.md in VS Code to understand available patterns.
Reference specific guides in your prompts to Copilot.
Use CLAUDE.md patterns when working with Claude.

Claude AI Assistant

Open CLAUDE.md (from your project root)—this is specifically designed for Claude.
Copy relevant sections into your Claude conversations.
Reference AGENTS.md for broader architectural guidance.
Use the structured templates provided in CLAUDE.md.

ChatGPT or Other AI Tools

Start with AGENTS.md—it's universal for all AI tools.
Copy relevant patterns into your AI conversations.
Reference specific Cursor rules (.mdc files) as needed.
Adapt the patterns to your AI tool's prompt format.

Once AI guides are set up in your project, sharing them with team members is straightforward.

<Tabs items={["Git Commit", "Shared Drive", "NPM Package"]}> ### Commit to Your Repository ```bash # Add AI guides to your repository git add AGENTS.md CLAUDE.md .cursor/

# Commit with descriptive message
git commit -m "feat: add Motia AI development guides and Cursor rules

- AGENTS.md: Universal AI guide for all AI tools and IDEs
- CLAUDE.md: Claude-specific advanced techniques
- .cursor/rules/: IDE-specific patterns for Cursor

These guides enable one-shot complete backend development
using proven Motia architectural patterns."

# Push to your repository
git push origin main
```

**Benefits:**
- Automatic distribution to all team members
- Version control with your project
- No additional setup required for new developers

### Share via Company Drive ```bash # Create a shared package mkdir motia-ai-development-guide-v1.0.0 cp AGENTS.md motia-ai-development-guide-v1.0.0/ cp CLAUDE.md motia-ai-development-guide-v1.0.0/ cp -r .cursor motia-ai-development-guide-v1.0.0/

# Create setup script
cat > motia-ai-development-guide-v1.0.0/setup.sh << 'EOF'
#!/bin/bash
echo "Setting up Motia AI Development Guides..."

# Copy to current directory
cp AGENTS.md ./AGENTS.md
cp CLAUDE.md ./CLAUDE.md
cp -r .cursor ./ 2>/dev/null || mkdir -p .cursor && cp -r .cursor/rules .cursor/

echo "✅ AI guides installed successfully!"
echo "📖 Open AGENTS.md to get started"
EOF

chmod +x motia-ai-development-guide-v1.0.0/setup.sh
```

### Create Team NPM Package ```json // team-motia-guides/package.json { "name": "@yourcompany/motia-ai-development-guide", "version": "1.0.0", "description": "Motia AI Development Guides and Cursor Rules", "main": "index.js", "scripts": { "install": "node setup.js" }, "files": [ "AGENTS.md", "CLAUDE.md", ".cursor/" ] } ```

```javascript
// team-motia-guides/setup.js
const fs = require('fs');
const path = require('path');

console.log('🚀 Installing Motia AI Development Guides...');

// Copy AGENTS.md
if (fs.existsSync(path.join(__dirname, 'AGENTS.md'))) {
  fs.copyFileSync(path.join(__dirname, 'AGENTS.md'), './AGENTS.md');
  console.log('✅ AGENTS.md installed');
}

// Copy CLAUDE.md
if (fs.existsSync(path.join(__dirname, 'CLAUDE.md'))) {
  fs.copyFileSync(path.join(__dirname, 'CLAUDE.md'), './CLAUDE.md');
  console.log('✅ CLAUDE.md installed');
}

// Copy .cursor rules
const cursorSrc = path.join(__dirname, '.cursor');
if (fs.existsSync(cursorSrc)) {
  const cursorDest = './.cursor';
  if (!fs.existsSync(cursorDest)) {
    fs.mkdirSync(cursorDest, { recursive: true });
  }
  fs.cpSync(cursorSrc, cursorDest, { recursive: true });
  console.log('✅ Cursor rules installed');
}

console.log('');
console.log('🎉 Installation complete!');
console.log('📖 Open AGENTS.md to start building with AI');
```

Verification

Test that AI guides are set up correctly:

### Verify AI development guides ```bash # Check if guides exist in project root ls -la AGENTS.md CLAUDE.md

# Verify content (should not be empty)
wc -l AGENTS.md CLAUDE.md
```

### Verify Cursor rules ```bash # Check Cursor rules directory ls -la .cursor/rules/

# Count number of rule files
ls .cursor/rules/*.mdc | wc -l
```

### Test CLI commands ```bash # Test rules list command npx motia@latest rules list

# Test showing guides
npx motia@latest rules show agents
npx motia@latest rules show claude

# Test showing a specific rule
npx motia@latest rules show api-steps
```

### Verify file integrity ```bash # Check file sizes (should be > 0) ls -lh AGENTS.md CLAUDE.md .cursor/rules/*.mdc

# Verify no empty files
find .cursor/rules/ -name "*.mdc" -size 0
```

### Test in your IDE ```bash # Open your project in Cursor/VS Code # The .cursor/rules/ should be automatically detected # Try creating a new step file and see if patterns appear ``` If all verification steps pass, you're ready to start building with AI-powered development!

Prerequisites​

Installation Methods​

Project Structure After Setup​

Configuration for Different AI Tools​

Cursor IDE Setup​

VS Code with GitHub Copilot​

Claude AI Assistant​

ChatGPT or Other AI Tools​

Sharing AI Guides with Team Members​

Verification​