creating-windsurf-packages

Creating Windsurf Packages

Overview

Windsurf uses a single .windsurf/rules file containing plain markdown instructions with NO frontmatter.

CRITICAL CONSTRAINTS:

• No frontmatter - Pure markdown only
• 12,000 character limit - Hard limit enforced by Windsurf
• Single file - All rules in one .windsurf/rules file

Quick Reference

Aspect	Requirement
Format	Plain markdown
Frontmatter	None (forbidden)
Character limit	12,000 max
File location	.windsurf/rules (single file)

Creating Rules

Plain markdown with optional H1 title and organized sections:

# React Development Guidelines

Guidelines for building React applications in this project.

## Component Structure

- Use functional components with hooks
- Keep components under 200 lines
- Extract logic into custom hooks when appropriate
- Co-locate styles with components

## State Management

We use Zustand for global state:

- Create stores in `src/stores/`
- Use selectors to prevent unnecessary re-renders
- Keep stores focused on single concerns

\`\`\`typescript
// Good: Focused store
const useAuthStore = create((set) => ({
  user: null,
  login: (user) => set({ user }),
  logout: () => set({ user: null }),
}));
\`\`\`

## Testing

- Write tests alongside components (`.test.tsx`)
- Use React Testing Library
- Test user behavior, not implementation details
- Aim for 80% coverage on new code

Character Budget Tips

To stay under 12,000 characters:

1. Focus on project-specific patterns - AI already knows general best practices
2. Use concise language - Every word counts
3. Limit code examples - Only essential patterns
4. Skip obvious practices - Don't repeat what AI knows
5. Reference external docs - Link instead of repeating

Example: Project-Specific Context

# Project Architecture

## Tech Stack

- **Frontend**: React 18 + TypeScript + Vite
- **Styling**: Tailwind CSS
- **State**: Zustand
- **Routing**: React Router v6
- **API**: REST with axios

## Directory Structure

\`\`\`
src/
  components/     # Reusable UI components
  features/       # Feature-specific code
  hooks/          # Custom React hooks
  stores/         # Zustand stores
  utils/          # Helper functions
  types/          # TypeScript types
\`\`\`

## Coding Conventions

- Use PascalCase for components
- Use camelCase for functions/variables
- Use kebab-case for file names
- Export components as named exports

## API Integration

All API calls go through `src/api/client.ts`:

\`\`\`typescript
import { apiClient } from '@/api/client';

// Use the client
const users = await apiClient.get('/users');
\`\`\`

## Environment Variables

Access via `import.meta.env`:

- `VITE_API_URL` - Backend API URL
- `VITE_APP_ENV` - Environment (dev/staging/prod)