Cursor Rules and GitHub Copilot

---
globs: src/**/*.ts,src/**/*.tsx
---

# Cursor Rules for TypeScript

See AGENTS.md for project conventions.

## TypeScript-Specific Rules

Always:

- Use strict: true in tsconfig
- Define function return types explicitly (no inference)
- Use const for all immutable bindings
- Avoid any; use unknown and narrow

Never:

- Use var
- Use null; prefer undefined
- Use ! non-null assertion without comment

---
globs: src/components/**/*.tsx
---

# React Component Rules

Applies only to React component files.

---
globs: "*.test.ts,*.spec.ts"
---

# Test Rules

Applies only to test files.

.cursor/
├── rules/
│   ├── typescript.mdc       # TypeScript rules (src/**/*.ts)
│   ├── react.mdc            # React-specific (src/**/*.tsx)
│   ├── tests.mdc            # Test files (*.test.ts)
│   └── api-routes.mdc       # API routes (src/api/**)

---
globs: "src/**/*.{ts,tsx}"
---

# TypeScript Project Rules

See AGENTS.md for commands and boundaries.

## Naming

Variables / functions: camelCase
Types / interfaces: PascalCase
Constants: UPPER_SNAKE_CASE (if immutable config)
Files: kebab-case

## TypeScript

Always:

- strict: true (tsconfig.json)
- Explicit return types on exported functions
- Use const for all bindings
- Import types: import type { T } from '...'

Never:

- any type; use unknown and narrow
- null; use undefined
- non-null assertion (!) without comment
- Function expressions; use const fn = () => {}

## Imports

Order:

1. External packages (react, next, zod, etc.)
2. Internal absolute paths (src/...)
3. Relative paths (../)

Example:
import React from 'react';
import { z } from 'zod';
import { useAuth } from 'src/hooks/useAuth';
import { Button } from './Button';

## Comments

Use JSDoc for:

- Public functions and types
- Non-obvious logic
- Why, not what

Avoid:

- Stating the obvious (// increment x)
- Stale comments (update on code change)

## Error Handling

Return errors, don't throw (in tools):
return {
success: false,
error: { code: 'INVALID_INPUT', message: '...' }
};

## Testing

Test file location: src/components/Button.test.tsx (alongside component)
Test structure: describe, it, expect

---
applyTo: "src/api/**/*.ts"
---

# API Route Instructions

Routes follow RESTful conventions: /api/v1/[resource]/[id]?

# GitHub Copilot Custom Instructions

See AGENTS.md for project conventions and commands.

## Coding Style

- TypeScript with strict mode
- camelCase for functions/variables, PascalCase for types
- Explicit return types on exported functions
- Use const; avoid var and null

## API Design

- RESTful routes: /api/v1/...
- Status codes: 200 (success), 400 (client error), 500 (server error)
- Error responses: { error: { code, message, details } }

## Testing

- Unit tests alongside source files (.test.ts)
- Use Vitest; aim for >80% coverage
- Test behavior, not implementation

## Performance

- Paginate list endpoints (max 50 items)
- Use indexes on frequently queried columns
- Avoid N+1 queries; use batch or joins

## Security

- All API routes require authentication
- Validate input on all endpoints
- Use parameterized queries (Prisma handles this)
- Secrets in .env.local, never in git

# GitHub Copilot Custom Instructions

See AGENTS.md for project conventions.

## Quick Guidelines

- TypeScript strict mode; explicit return types
- camelCase functions, PascalCase types
- REST API: /api/v1/..., status codes 200/400/500
- Test alongside source: Component.test.tsx
- Use const; avoid var and null
- Paginate lists (max 50); validate all inputs

AGENTS.md           ← source of truth for commands, boundaries, tech stack
├── CLAUDE.md       (optional; starts with `@AGENTS.md` import, add Claude-only hooks)
├── .cursor/rules/  (reference AGENTS.md sections, add Cursor-only rules)
└── .github/copilot-instructions.md (reference AGENTS.md, add Copilot focus areas)

#!/bin/bash
# .git/hooks/pre-commit

# Check that Cursor rules reference AGENTS.md
if grep -r "See AGENTS.md" .cursor/rules/ > /dev/null 2>&1; then
  echo "✓ Cursor rules reference AGENTS.md"
else
  echo "✗ Cursor rules missing AGENTS.md reference"
  exit 1
fi

# Check that Copilot instructions exist if AGENTS.md does
if [ -f "AGENTS.md" ] && [ ! -f ".github/copilot-instructions.md" ]; then
  echo "✗ AGENTS.md exists but .github/copilot-instructions.md missing"
  exit 1
fi

echo "✓ Context files OK"

.
├── AGENTS.md                          # Universal baseline
├── CLAUDE.md                          # Claude Code overlay (optional)
├── CONTRIBUTING.md                    # Detailed contribution guide
├── .cursor/
│   └── rules/
│       ├── typescript.mdc             # TS-specific rules
│       ├── react.mdc                  # React-specific rules
│       └── tests.mdc                  # Test file rules
├── .github/
│   └── copilot-instructions.md        # GitHub Copilot instructions
└── docs/
    ├── ARCHITECTURE.md                # Architecture overview
    └── runbooks/                      # Deployment, incident response

.cursor/rules/
├── ts-global.mdc           # All .ts files
├── api-routes.mdc          # packages/api/src/routes/**
├── web-components.mdc      # packages/web/src/components/**
└── tests-global.mdc        # All .test.ts files

# AGENTS.md

...

## Testing

Unit: Vitest (pnpm test)

@AGENTS.md

---
globs: "*.test.ts"
---

See AGENTS.md > Testing for test patterns.

## Cursor-Specific Test Rules

Never:

- Use .skip or .only (should not be committed)
- Test implementation; test behavior

# GitHub Copilot Custom Instructions

See AGENTS.md for full conventions.

## Testing

- Tests: src/\*_/_.test.ts (Vitest)
- Run: pnpm test
- Structure: describe, it, expect
- Test behavior, not implementation

# BAD: .cursor/rules/commands.mdc

pnpm dev
pnpm test
pnpm build

# GOOD: .cursor/rules/commands.mdc

See AGENTS.md > Quick Start for commands.
This file adds Cursor-specific tips.

# BAD: .github/copilot-instructions.md

Use npm install

(But AGENTS.md says pnpm; npm is old.)

# BAD: Cursor rules

Always:

- Use PascalCase for types
- Use camelCase for functions
- Use const
- Use async/await
- Use arrow functions
- ...30 more rules