90%的程序员还不知道！Ruler一键同步所有AI编码助手规则，告别重复配置！

# 通过npm全局安装
npm install -g @intellectronica/ruler
# 确认安装
ruler --version

# 无需安装直接使用
npx @intellectronica/ruler --help

# 在项目根目录初始化Ruler
cd your-project
ruler init
# 生成的文件结构
.ruler/
├── instructions.md          # 基本编码规则
├── ruler.toml              # Ruler配置文件
└── mcp.json               # MCP服务器设置（可选）

# Coding Guidelines

## General Principles
- Write clean, readable code
- Follow language-specific conventions
- Add meaningful comments where necessary
- Prioritize maintainability

## Error Handling
- Always handle potential errors gracefully
- Provide meaningful error messages
- Log errors appropriately

## Testing
- Write unit tests for new functionality
- Ensure tests are readable and maintainable

# 默认启用的代理
default_agents = ["cursor", "copilot", "claude", "aider"]
# 全局MCP设置
[mcp]
enabled = true
merge_strategy = "merge"
# 自动管理.gitignore
[gitignore]
enabled = true
# 代理特定设置
[agents.copilot]
enabled = true
output_path = ".github/copilot-instructions.md"
[agents.cursor]
enabled = true
output_path = ".cursor/rules/ruler_cursor_instructions.mdc"
[agents.claude]
enabled = true
output_path = "CLAUDE.md"
[agents.aider]
enabled = true
output_path_instructions = "ruler_aider_instructions.md"
output_path_config = ".aider.conf.yml"

# 将规则应用到所有启用的代理
ruler apply
# 仅应用到特定代理
ruler apply --agents cursor,copilot
# 带详细日志执行
ruler apply --verbose
# 排除.gitignore更新
ruler apply --no-gitignore

# 检查当前配置
ruler status
# 可用代理列表
ruler list-agents
# 帮助
ruler --help

.ruler/
├── coding_standards.md     # 编码标准
├── api_guidelines.md       # API使用指南
├── project_context.md      # 项目上下文
├── security_rules.md       # 安全规则
└── team_conventions.md     # 团队约定

# TypeScript Coding Standards

## Type Definitions
- Always use explicit type annotations for function parameters
- Prefer interfaces over type aliases for object types
- Use readonly for immutable data structures

## React Components
- Use functional components with hooks
- Implement proper prop validation with TypeScript interfaces
- Follow the container/presentation component pattern

## Error Handling
- Use Result<T, E> pattern for operations that can fail
- Avoid throwing exceptions in business logic
- Implement proper error boundaries in React

# Project Architecture Overview

## Tech Stack
- Frontend: React 18 + TypeScript + Vite
- Backend: Node.js + Express + Prisma
- Database: PostgreSQL
- Authentication: JWT + Passport.js

## Key Directories
- `/src/components/` - Reusable UI components
- `/src/pages/` - Route-level components
- `/src/services/` - API service layer
- `/src/utils/` - Utility functions
- `/src/types/` - TypeScript type definitions

## Database Schema
- Users: authentication and profile data
- Posts: content management
- Comments: user interactions
- Categories: content organization

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project"
      ]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

# 全局设置
default_agents = ["cursor", "copilot", "claude"]
# GitHub Copilot特定设置
[agents.copilot]
enabled = true
output_path = ".github/copilot-instructions.md"
# Cursor特定设置
[agents.cursor]
enabled = true
output_path = ".cursor/rules/ruler_cursor_instructions.mdc"
[agents.cursor.mcp]
enabled = true
merge_strategy = "overwrite"
# Claude设置
[agents.claude]
enabled = true
output_path = "CLAUDE.md"
# Aider设置（双重输出）
[agents.aider]
enabled = true
output_path_instructions = "ruler_aider_instructions.md"
output_path_config = ".aider.conf.yml"
# 禁用的代理
[agents.windsurf]
enabled = false
[agents.kilocode]
enabled = true
output_path = ".kilocode/rules/ruler_kilocode_instructions.md"

# Team Development Standards

## Code Review Guidelines
- All PRs must have at least 2 approvals
- Include unit tests for new features
- Update documentation for API changes
- Follow conventional commit format

## React Component Standards
- Use TypeScript with strict mode
- Implement error boundaries
- Use React.memo for performance optimization
- Follow atomic design principles

## API Development
- Use OpenAPI 3.0 for documentation
- Implement rate limiting
- Include request/response validation
- Follow REST principles

## Testing Requirements
- Minimum 80% code coverage
- Integration tests for critical paths
- E2E tests for user workflows
- Mock external dependencies

# E-commerce Platform Context

## Business Logic
- Order processing workflow
- Payment integration with Stripe
- Inventory management system
- User authentication and authorization

## Key Models
- User: customer and admin roles
- Product: variants, pricing, inventory
- Order: status tracking, payment processing
- Cart: session management, persistence

## External Integrations
- Payment: Stripe API
- Shipping: UPS/FedEx APIs
- Email: SendGrid
- Analytics: Google Analytics 4

## Performance Requirements
- Page load time < 2 seconds
- API response time < 500ms
- 99.9% uptime requirement
- Support 1000+ concurrent users

# 确保所有团队成员获得相同的AI体验
ruler apply
# 集成到CI/CD管道
npm run ruler:apply
# 提交更改
git add .ruler/ .github/ .cursor/ CLAUDE.md
git commit -m "feat: update AI coding assistant rules"
git push origin main

name: Ruler Configuration Check
on:
  pull_request:
    paths: ['.ruler/**']
  push:
    branches: [main]

jobs:
  ruler-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install Ruler
        run: npm install -g @intellectronica/ruler

      - name: Apply Ruler configuration
        run: ruler apply --no-gitignore --verbose

      - name: Check for uncommitted changes
        run: |
          if [[ -n $(git status --porcelain) ]]; then
            echo "::error::Ruler configuration is out of sync!"
            echo "Please run 'ruler apply' locally and commit the changes."
            git status
            git diff
            exit 1
          fi          

      - name: Validate configuration
        run: ruler status

{
  "scripts": {
    "ruler:apply": "ruler apply",
    "ruler:check": "ruler apply --no-gitignore && git diff --exit-code",
    "dev": "npm run ruler:apply && next dev",
    "precommit": "npm run ruler:apply",
    "postinstall": "ruler apply --no-gitignore"
  }
}

# React + TypeScript Guidelines

## Component Structure
```typescript
interface ComponentProps {
  title: string;
  items: readonly Item[];
  onItemClick?: (item: Item) => void;
}

export const Component: React.FC<ComponentProps> = ({
  title,
  items,
  onItemClick
}) => {
  return (
    <div className="component">
      <h2>{title}</h2>
      {items.map(item => (
        <ItemCard 
          key={item.id} 
          item={item} 
          onClick={onItemClick}
        />
      ))}
    </div>
  );
};

# Node.js API Development Guidelines

## Route Structure
```typescript
// controllers/userController.ts
export const createUser = async (req: Request, res: Response) => {
  try {
    const userData = validateUserInput(req.body);
    const user = await userService.createUser(userData);
    res.status(201).json({ success: true, data: user });
  } catch (error) {
    next(error);
  }
};

#!/bin/bash
# test-ruler-setup.sh

echo "🚀 Starting Ruler test environment setup"
echo "===================================="

# Check system requirements
echo "[INFO] Checking system requirements..."

# Check Node.js
if command -v node &> /dev/null; then
    NODE_VERSION=$(node --version)
    echo "[SUCCESS] Node.js installed: $NODE_VERSION"
else
    echo "[ERROR] Node.js is not installed. Need to run brew install node"
    exit 1
fi

# Check npm
if command -v npm &> /dev/null; then
    NPM_VERSION=$(npm --version)
    echo "[SUCCESS] npm installed: $NPM_VERSION"
else
    echo "[ERROR] npm is not installed"
    exit 1
fi

# Create test directory
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
TEST_DIR="$HOME/ruler-test-$TIMESTAMP"
mkdir -p "$TEST_DIR"
cd "$TEST_DIR"

echo "[INFO] Created test directory: $TEST_DIR"

# Install Ruler
echo "[INFO] Installing Ruler..."
npm install -g @intellectronica/ruler

# Verify installation
if command -v ruler &> /dev/null; then
    RULER_VERSION=$(ruler --version)
    echo "[SUCCESS] Ruler installed: $RULER_VERSION"
else
    echo "[ERROR] Ruler installation failed"
    exit 1
fi

# Initialize sample project
echo "[INFO] Initializing sample project..."
npm init -y
npm install express typescript @types/node @types/express

# Initialize Ruler
ruler init

# Create custom rule files
cat > .ruler/typescript_rules.md << 'EOF'
# TypeScript Development Rules

## Type Safety
- Always use strict TypeScript configuration
- Prefer explicit type annotations over 'any'
- Use union types for complex data structures
- Implement proper error handling with Result<T, E> pattern

## Code Organization
- Use barrel exports in index.ts files
- Group related functionality in modules
- Implement dependency injection for testability
- Follow single responsibility principle

## Performance
- Use readonly for immutable data
- Implement proper caching strategies
- Minimize bundle size with tree shaking
- Use lazy loading for large components
EOF

cat > .ruler/express_api_rules.md << 'EOF'
# Express.js API Development Rules

## Route Structure
- Use express.Router() for modular routing
- Implement middleware for common functionality
- Validate request parameters with joi or zod
- Use async/await for asynchronous operations

## Security
- Implement rate limiting with express-rate-limit
- Use helmet.js for security headers
- Validate and sanitize all user inputs
- Implement proper CORS configuration

## Error Handling
- Use centralized error handling middleware
- Return consistent error response format
- Log errors with structured logging
- Implement graceful shutdown handling
EOF

# Apply rules
echo "[INFO] Applying rules..."
ruler apply --verbose

# Check created files
echo ""
echo "📁 Created files:"
find . -name "*.md" -o -name "*.yml" -o -name "*.mdc" -o -name "*.toml" | grep -E '\.(md|yml|mdc|toml)$' | sort

# Preview content of each AI tool's configuration file
echo ""
echo "📋 Preview of created configuration files:"

if [ -f ".github/copilot-instructions.md" ]; then
    echo "--- GitHub Copilot Configuration ---"
    head -n 10 .github/copilot-instructions.md
    echo ""
fi

if [ -f "CLAUDE.md" ]; then
    echo "--- Claude Configuration ---"
    head -n 10 CLAUDE.md
    echo ""
fi

if [ -f ".cursor/rules/ruler_cursor_instructions.mdc" ]; then
    echo "--- Cursor Configuration ---"
    head -n 10 .cursor/rules/ruler_cursor_instructions.mdc
    echo ""
fi

# Generate test commands
cat > test-commands.txt << EOF
# Ruler Test Commands

# Basic commands
ruler --version
ruler status
ruler list-agents

# Apply rules
ruler apply
ruler apply --verbose
ruler apply --agents cursor,copilot

# Activate only specific agents
ruler apply --agents cursor
ruler apply --agents copilot,claude

# Exclude .gitignore update
ruler apply --no-gitignore

# Check configuration
cat .ruler/ruler.toml
ls -la .ruler/
EOF

cat > run-ruler-tests.sh << 'EOF'
#!/bin/bash
echo "🧪 Running Ruler Functionality Tests"
echo "=========================="

echo "1. Check current status"
ruler status

echo ""
echo "2. Check available agents"
ruler list-agents

echo ""
echo "3. Reapply rules (detailed log)"
ruler apply --verbose

echo ""
echo "4. Test applying only Cursor"
ruler apply --agents cursor

echo ""
echo "5. Reapply all agents"
ruler apply

echo ""
echo "✅ Tests completed!"
EOF

chmod +x run-ruler-tests.sh

# Save environment information
cat > environment-info.txt << EOF
Ruler Test Environment Information
=====================

Test time: $(date)
Node.js: $(node --version)
npm: $(npm --version)
Ruler: $(ruler --version)
Operating System: $(uname -a)
Test Directory: $TEST_DIR

Created files:
$(find . -type f -name "*.md" -o -name "*.yml" -o -name "*.mdc" -o -name "*.toml" | sort)
EOF

echo ""
echo "🎉 Ruler test environment setup completed!"
echo "================================"
echo ""
echo "📁 Test directory: $TEST_DIR"
echo ""
echo "🚀 Next steps:"
echo "1. cd $TEST_DIR"
echo "2. Run ./run-ruler-tests.sh to perform functionality tests"
echo "3. Use commands in test-commands.txt for additional testing"
echo ""
echo "📋 Created files:"
echo "- run-ruler-tests.sh: Automated test script"
echo "- test-commands.txt: Manual test command list"
echo "- environment-info.txt: Test environment information"
echo ""
echo "💡 Tip: Use ruler apply --verbose to view detailed execution process!"

# Ask user if they want to run tests now
echo ""
read -p "Would you like to run Ruler functionality tests now? (y/n): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
    echo "Running tests..."
    ./run-ruler-tests.sh
else
    echo "[SUCCESS] Test environment ready. Start anytime with ./run-ruler-tests.sh!"
fi

# 添加到~/.zshrc的Ruler相关别名

# Ruler basic command shortcuts
alias ruler-apply="ruler apply"
alias ruler-status="ruler status"
alias ruler-verbose="ruler apply --verbose"

# Apply to specific agent groups
alias ruler-cursor="ruler apply --agents cursor"
alias ruler-copilot="ruler apply --agents copilot"
alias ruler-claude="ruler apply --agents claude"
alias ruler-aider="ruler apply --agents aider"

# Development workflow integration
alias ruler-dev="ruler apply && echo '✅ AI rules applied successfully'"
alias ruler-ci="ruler apply --no-gitignore"

# Rule file editing shortcuts
alias edit-ruler="code .ruler/"
alias edit-ruler-config="code .ruler/ruler.toml"
alias edit-ruler-instructions="code .ruler/instructions.md"

# Project setup shortcuts
alias ruler-init-project="ruler init && ruler apply"
alias ruler-clean="rm -rf .github/copilot-instructions.md CLAUDE.md .cursor/rules/ ruler_aider_instructions.md .aider.conf.yml"

# Debugging and troubleshooting
alias ruler-debug="ruler apply --verbose --no-gitignore"
alias ruler-check="ruler status && echo '--- Generated Files ---' && find . -name '*copilot*' -o -name '*claude*' -o -name '*cursor*' -o -name '*aider*' 2>/dev/null"

# Test environment management
alias ruler-test="cd ~/ruler-test-* 2>/dev/null || echo 'No test directory found'"
alias ruler-setup-test="curl -O https://raw.githubusercontent.com/your-repo/ruler-test-setup.sh && chmod +x ruler-test-setup.sh && ./ruler-test-setup.sh"

# Add aliases to zshrc
cat >> ~/.zshrc << 'EOF'

# Ruler AI Assistant Configuration Aliases
alias ruler-apply="ruler apply"
alias ruler-status="ruler status"
alias ruler-verbose="ruler apply --verbose"
alias ruler-cursor="ruler apply --agents cursor"
alias ruler-copilot="ruler apply --agents copilot"
alias ruler-claude="ruler apply --agents claude"
alias ruler-dev="ruler apply && echo '✅ AI rules applied successfully'"
alias edit-ruler="code .ruler/"

EOF

# Reload configuration
source ~/.zshrc

# Usage examples
ruler-apply          # Apply rules to all agents
ruler-cursor         # Apply only to Cursor
edit-ruler           # Edit rules with VS Code