Windsurf .windsurfrules как настроить правила проекта чтобы AI всегда знал ваш стек

Windsurf Rules — это файл с инструкциями для Cascade, который читается автоматически при каждом запросе. Без правил агент каждую сессию начинает с нуля: не знает ваш стек, стиль кода, запрещённые паттерны. С правилами он уже знает всё это с первого сообщения.

Секрет качественного AI-кода: не в выборе модели и не в длине промптов. Это конкретный контекст через файлы правил. Разбираем как настроить правильно.

Два типа правил: глобальные и workspace

Глобальные правила применяются во всех проектах и всех окнах Windsurf IDE. Хранятся в настройках Windsurf: Settings → Cascade → Global Rules.

Что писать в глобальные правила:

• Язык общения с агентом (например, «отвечай на русском языке»)
• Общие предпочтения по стилю (комментарии, документация)
• Поведение при ошибках

Workspace Rules (проектные правила) локальны для конкретного проекта. Хранятся в файле .windsurfrules в корне репозитория или настраиваются через Settings → AI Rules for Workspace. Поддерживают glob-паттерны для активации в конкретном контексте.

Что писать в workspace rules:

• Технологический стек проекта
• Структуру директорий
• Запрещённые паттерны
• Специфику платформы или фреймворка

Приоритет: workspace rules переопределяют глобальные при совпадении области. Если глобально написано «используй TypeScript», а workspace правило говорит «для этого проекта используй Python», Cascade использует Python.

Лимиты символов: важно знать заранее

Windsurf читает Rules с жёсткими ограничениями:

• Один Markdown-файл правила: до 6 000 символов
• Совокупно все правила (глобальные + workspace): до 12 000 символов
• При превышении: глобальные правила обрезаются в первую очередь

Практический вывод: не пишите длинные объяснения и комментарии в правилах. Только конкретные инструкции. Для группировки связанных инструкций: используйте простой XML-стиль:

<code_style>
Use TypeScript. Prefer interfaces over types. No enums.
Use Tailwind CSS, not raw CSS.
</code_style>

<structure>
Components in src/components/UI
Utils in src/utils (shared utilities go here)
API handlers in src/api
</structure>

Такая структура читается Cascade лучше, чем непрерывный текст.

Что писать в правилах: готовая структура

Хорошее правило отвечает на вопрос «что Cascade должен знать чтобы правильно выполнить любую задачу в этом проекте». Контекст должен описывать цель и ограничения, а не реализацию.

Блок 1: Цель проекта

This is a task management SaaS for remote teams.
Main features: projects, tasks, time tracking, reports.

Блок 2: Технологический стек

Frontend: Next.js 15 (App Router), React 18, TypeScript, Tailwind CSS
Backend: Node.js, Prisma ORM, PostgreSQL
Testing: Jest, React Testing Library
Package manager: pnpm

Блок 3: Структура директорий

src/
  app/        — Next.js App Router pages
  components/ — React components
  components/UI/ — reusable UI primitives
  lib/        — business logic and utils
  api/        — API route handlers

Блок 4: Кодстайл и запреты

Always use TypeScript. No JavaScript files.
Prefer interfaces over types.
No enums — use const objects instead.
No any type unless absolutely necessary.
Use Tailwind classes. Do not write raw CSS.

Блок 5: Поведение Cascade

Always explain what you changed and why.
Before fixing a test error, explain what the error means.
Assume the problem is in the test, not in the code, unless proven otherwise.
Always indicate which rules were applied.

Как Cascade использует правила

Cascade читает правила автоматически в начале каждого запроса. Не нужно их упоминать в промпте: они уже в контексте.

Manual mode — активация конкретного правила через @имя_правила в чате. Используется когда правило нужно не всегда, а только в определённых ситуациях.

Проверка что правила работают: добавьте в правила инструкцию «в конце каждого ответа укажи: Applied rules: [список]». Это позволяет убедиться, что Cascade читает правила правильно и применяет нужные.

Готовые шаблоны под стек

Next.js / React проект

# Project Rules

## Stack
Next.js 15, React 18, TypeScript, Tailwind CSS, Shadcn/UI
Database: Supabase (PostgreSQL)
Auth: Supabase Auth

## Code Style
- Prefer interfaces over types
- No enums (use const objects)
- Tailwind only, no raw CSS
- Use Server Components by default, Client Components only when needed

## Structure
- app/ — App Router pages and layouts
- components/ui/ — Shadcn primitives
- components/ — feature components
- lib/ — utilities and helpers

## Rules
- Always add loading and error states
- Use next/image for all images
- Specify exact version: Next.js 15, not 13 or 14

Python / FastAPI проект

# Project Rules

## Stack
Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic
Database: PostgreSQL
Testing: pytest, httpx

## Code Style
- Type hints everywhere
- Pydantic models for request/response validation
- No synchronous database calls in async endpoints
- Use dependency injection for database sessions

## Anti-patterns
- No raw SQL queries — use SQLAlchemy ORM
- Do not install packages globally — use virtual environment
- replace argparse with typer for CLI scripts

## Testing Rules
Before fixing a test error, explain what the error means.
Assume the problem may be in the test, not in the production code.

Go / Fiber проект

# Project Rules

## Stack
Go 1.22, Fiber v2, GORM, PostgreSQL
Testing: testify

## Structure
- internal/handler/ — HTTP handlers (structs with dependency injection)
- internal/service/ — business logic
- internal/repository/ — database layer
- cmd/ — entry points

## Rules
- Use dependency injection, not global variables
- All errors must be handled, no silent ignoring
- Keep handlers thin — business logic in service layer

Практические лайфхаки

Правила — итеративный процесс. Не нужно писать всё сразу. Добавляйте правило только когда Cascade регулярно делает одну и ту же ошибку. Увидели что AI использует устаревшую команду — сразу добавьте исправляющее правило.

Файл next_steps.txt. Добавьте в правила: «в конце каждой сессии запиши следующие шаги в файл next_steps.txt». Cascade плохо помнит контекст между сессиями — этот файл стал мостом между ними. Особенно полезно для длинных многосессионных проектов.

Символическая ссылка для единого источника правил. Если используете несколько IDE (Cursor, Windsurf, VS Code Copilot) — создайте один файл правил и сделайте symlink из других конфигурационных файлов. Единый источник истины для всех AI-ассистентов.

Файл правил в .gitignore. Если правила содержат информацию о внутренней архитектуре или безопасности — добавьте .windsurfrules в .gitignore. Для командных проектов где хотите шарить правила — наоборот, коммитьте файл в репозиторий.

windsurf.run — официальный ресурс с библиотекой правил от сообщества. Берите лучшие части чужих правил и адаптируйте. Аналог для Cursor — репозиторий awesome-cursor-rules на GitHub с 31K+ звёзд.

Для monorepo: описывайте структуру пакетов явно. Когда Cascade знает о папке shared/, он автоматически помещает туда утилиты вместо создания дублей в каждом пакете.

Doom Loop при тестах. Если Cascade входит в цикл «написать тест → тест упал → исправить тест → тест упал снова» — добавьте правило: «перед исправлением ошибки теста объясни что означает ошибка, затем уточни — проблема в тесте или в коде». Это замедляет агента, но предотвращает бесконечные исправления.

Максим: "Ребят, когда я начал работать с правилами в Windsurf, первые версии были длинные и подробные. Потом понял: правила должны быть как инструкция для нового разработчика — максимально конкретно, минимально воды. Как только я описал структуру монорепозитория NanaBanana в rules, Cascade сразу стал класть утилиты в правильные папки без напоминания. Один раз написал — работает постоянно."

FAQ

Что такое .windsurfrules и зачем он нужен? .windsurfrules: файл с инструкциями для Cascade, который читается автоматически при каждом запросе в Windsurf IDE. Без правил агент не знает ваш стек, запрещённые паттерны и структуру проекта. С правилами: знает с первого сообщения. Это ключевой инструмент для консистентного кода в командах.

Какой лимит символов у Windsurf Rules? 6 000 символов на один файл правила, 12 000 символов суммарно (глобальные + workspace). При превышении Cascade обрезает глобальные правила в первую очередь. Пишите конкретно и без лишних объяснений.

Чем Global Rules отличаются от Workspace Rules? Global Rules: для всех проектов: язык ответа, общие предпочтения. Workspace Rules: для конкретного проекта: стек, структура директорий, запреты. Workspace переопределяют Global при совпадении. Настраиваются через glob-паттерны для активации в нужном контексте.

Как проверить что Cascade читает правила? Добавьте в правила: «в конце каждого ответа укажи Applied rules: [список применённых правил]». Это наглядно показывает что именно применяется. Можно удалить после проверки.

Нужно ли упоминать правила в каждом промпте? Нет. Cascade читает Rules автоматически. Для ручной активации конкретного правила используйте @имя_правила в чате: это Manual Mode. Полезно для правил, которые не нужны всегда.

Стоит ли коммитить .windsurfrules в репозиторий? Зависит от ситуации. Для командных проектов: да, это обеспечивает единые стандарты. Если файл содержит чувствительную информацию об архитектуре или безопасности: добавьте в .gitignore. Командные workflows лучше хранить в репозитории отдельно.

Windsurf Rules и Cursor Rules — одно и то же? Аналогичная концепция, разный формат. В Cursor это .cursorrules, в Windsurf: .windsurfrules. Можно создать симлинк между ними для единого источника правил если используете оба инструмента.

Глоссарий

.windsurfrules — файл с правилами для Cascade в корне проекта. Читается автоматически при каждом запросе в данном workspace.

Global Rules — правила Windsurf применяемые во всех проектах. Настраиваются в Settings → Cascade → Global AI Rules.

Workspace Rules — правила для конкретного проекта. Могут использовать glob-паттерны для активации в определённом типе файлов.

Glob-паттерн — шаблон для отбора файлов по маске. *.py — все Python-файлы, src/**/*.tsx — все TSX в папке src. Используется для workspace rules.

Manual Mode — активация правила через @имя в чате вместо автоматического применения.

windsurf.run — официальный ресурс с библиотекой правил и MCP-практик от сообщества Windsurf.

Doom Loop — цикл когда Cascade бесконечно исправляет тесты вместо того чтобы разобраться в причине ошибки. Решается правилом с требованием объяснить ошибку перед исправлением.

Полный обзор Windsurf IDE и Cascade — в разделе VibeCoderz. Там же обзоры Cursor с аналогичными правилами и Claude Code с файлом CLAUDE.md.

По вопросам настройки rules-файлов под конкретный стек — запишитесь на консультацию к Максиму.

Обновлено: май 2026