name: Cursor Development Rules description: Provides comprehensive development rules and guidelines for Cursor project development. Use when working on Cursor projects, setting up development environments, or implementing coding standards.

Cursor Project Development Rules

This Skill provides comprehensive development rules and guidelines for Cursor project development, including worktree-aware Docker development, coding standards, API design, frontend development, testing strategies, and Docker best practices.

Quick Start

To access specific development rules:

# View coding standards
cat rules/coding-standards.md

# View API guidelines
cat rules/api-guidelines.md

# View frontend guidelines
cat rules/frontend-guidelines.md

# View testing guidelines
cat rules/testing-guidelines.md

# View Docker development rules
cat rules/docker-development.md

# Get project information
python scripts/helper.py info

Available Rules

• coding-standards.md: Coding conventions and style guides for TypeScript, Python, and general development
• api-guidelines.md: FastAPI API design guidelines and best practices
• frontend-guidelines.md: Next.js frontend development guidelines with TypeScript and Tailwind CSS
• testing-guidelines.md: Testing strategy and implementation guidelines for unit, integration, and E2E tests
• docker-development.md: Docker development environment rules and worktree integration

Project Overview

This is a worktree-aware Docker scaffold with Next.js + FastAPI + PostgreSQL + Playwright E2E that enables parallel development across multiple git worktrees without port/container/network/volume/database name conflicts.

Key Features

• Worktree Support: Simultaneous development on multiple branches
• Docker Development: Consistent containerized development environment
• Automatic Environment: Git hooks for automatic .env generation
• Complete Isolation: Each worktree has independent environment
• Port Management: Automatic port allocation (3000+Δ, 8000+Δ, 5400+Δ)
• Database Isolation: Worktree-specific database names (app_<hash6>)
• Volume Isolation: Worktree-specific Docker volumes
• Network Isolation: Worktree-specific Docker networks

Development Commands

# Environment management
python tool-scripts/devctl.py env-gen --write-root
python tool-scripts/devctl.py up
python tool-scripts/devctl.py down

# Testing
python tool-scripts/devctl.py test js      # Frontend unit tests
python tool-scripts/devctl.py test py      # Backend unit tests
python tool-scripts/devctl.py test ui      # Playwright E2E
python tool-scripts/devctl.py test api     # API E2E tests
python tool-scripts/devctl.py test all    # All tests

# Database
python tool-scripts/devctl.py migrate upgrade
python tool-scripts/devctl.py migrate downgrade base

# Worktree management
git worktree add ../wt-feature feature/my-branch
git worktree remove wt-feature

Architecture

• Frontend: Next.js 14 with TypeScript, Tailwind CSS, Vitest, Playwright
• Backend: FastAPI with Python 3.11, SQLAlchemy, Alembic, pytest
• Database: PostgreSQL with worktree-specific databases
• Testing: Vitest (unit), Playwright (UI E2E), httpx (API E2E)
• Development: Docker Compose with worktree isolation