# 1. Установка Windsurf (Linux, macOS, Windows)

Windsurf доступен на всех основных платформах. Установка занимает не более пары минут, а сам редактор использует ту же архитектуру расширений, что и VS Code, поэтому миграция происходит практически бесшовно. Рассмотрим каждый вариант отдельно.

🐧 Linux (Debian/Ubuntu)

Официальный способ — загрузка .deb-пакета с сайта Codeium. После скачивания устанавливаем через dpkg и при необходимости доустанавливаем зависимости.

# Скачиваем установщик (замените URL на актуальный с codeium.com)
wget https://codeium.com/windsurf/download/linux -O windsurf.deb

# Устанавливаем пакет
sudo dpkg -i windsurf.deb

# Если есть неудовлетворённые зависимости — фиксим
sudo apt-get install -f -y

# Запуск
windsurf
  

🍎 macOS

Пользователи macOS могут установить Windsurf через Homebrew — это самый быстрый способ, обеспечивающий автоматическое обновление.

# Установка через Homebrew
brew install --cask windsurf

# Альтернативно — скачать .dmg с сайта и перенести в Applications
open /Applications/Windsurf.app
  

🪟 Windows

Загрузите установщик .exe с официального сайта, запустите и следуйте инструкциям мастера установки. Также доступен портативный режим и winget.

# Установка через winget (Windows 10/11)
winget install Codeium.Windsurf

# Проверка установки
windsurf --version
  

После установки вам будет предложено войти в аккаунт Codeium или создать новый. Бесплатный тариф включает базовые AI-функции и достаточен для индивидуальной разработки. Pro-подписка открывает расширенные лимиты Cascade и приоритетную очередь обработки запросов.

# 2. Первый запуск и обзор интерфейса

Интерфейс Windsurf построен на базе VS Code, поэтому если вы работали с ним, адаптация займёт буквально минуты. Однако есть ряд уникальных панелей, которые стоит изучить сразу.

Основные области интерфейса

При первом запуске рекомендую сразу открыть папку проекта: File → Open Folder (или Ctrl+K Ctrl+O). Windsurf индексирует кодовую базу и строит контекстный граф, который используется Cascade для понимания структуры проекта. Индексация происходит в фоне и не блокирует работу.

Ключевое отличие от VS Code — панель Cascade в правой части экрана. Это не просто чат-бот, а полноценный AI-ассистент с доступом к файловой системе, терминалу и контексту всего проекта. Вы можете перетаскивать файлы в чат, выделять код и отправлять его на анализ, а также давать сложные многошаговые инструкции.

# 3. Cascade: AI-автодополнение и интеллектуальный чат

Cascade — это главная AI-функция Windsurf, которая объединяет три режима: чат (запросы в панели), inline-редактирование (выделил код → получил правки прямо в редакторе) и командный режим (быстрые действия через Ctrl+I).

Базовые сценарии Cascade

Допустим, у нас есть Python-скрипт для обработки CSV-файлов. Мы хотим добавить фильтрацию и агрегацию. Отправляем запрос в Cascade:

# Запрос в Cascade (естественный язык)
Добавь функцию filter_and_aggregate, которая читает CSV,
фильтрует строки по значению в колонке 'status' == 'active'
и возвращает среднее арифметическое по колонке 'amount'.
Используй pandas.
  

Cascade проанализирует проект, увидит, что pandas ещё не импортирован, и предложит полное решение. Результат будет выглядеть примерно так:

import pandas as pd

def filter_and_aggregate(filepath: str) -> float:
    """Читает CSV, фильтрует по status='active', считает среднее amount."""
    df = pd.read_csv(filepath)
    filtered = df[df['status'] == 'active']
    if len(filtered) == 0:
        return 0.0
    return filtered['amount'].mean()

# Пример использования
result = filter_and_aggregate('sales_2026.csv')
print(f"Средний чек активных клиентов: {result:.2f}")
  

Inline-редактирование через Ctrl+I

Выделите блок кода, нажмите Ctrl+I и введите инструкцию на естественном языке. Cascade изменит выделенный фрагмент, не затрагивая остальной код. Это удобно для быстрых правок — например, заменить цикл for на list comprehension или добавить обработку исключений.

# 4. Supercomplete и мультифайловое редактирование

Supercomplete — это продвинутая система автодополнения, которая знает контекст всего проекта, а не только открытого файла. Она предлагает целые блоки кода, сигнатуры функций из соседних модулей и даже учитывает стиль кода, принятый в проекте.

Пример: рефакторинг с Supercomplete

Предположим, у нас есть сервис аутентификации, разбросанный по нескольким файлам. Мы хотим вынести логику хеширования паролей в отдельный модуль и обновить все импорты. Задача, на которую раньше уходило 15-20 минут, с мультифайловым редактированием решается одним запросом.

# Запрос в Cascade для мультифайлового рефакторинга
Создай модуль utils/hash_utils.py с функциями hash_password
и verify_password (используй bcrypt). Обнови все импорты
в проекте, чтобы они ссылались на новый модуль.
Убедись, что старые импорты удалены.
  

Cascade просканирует все файлы, найдёт использования hash_password и verify_password, обновит импорты и создаст новый модуль:

# utils/hash_utils.py — новый модуль
import bcrypt

def hash_password(password: str) -> str:
    """Хеширует пароль с автоматической солью."""
    salt = bcrypt.gensalt(rounds=12)
    return bcrypt.hashpw(
        password.encode('utf-8'), salt
    ).decode('utf-8')

def verify_password(password: str, hashed: str) -> bool:
    """Проверяет соответствие пароля хешу."""
    return bcrypt.checkpw(
        password.encode('utf-8'), hashed.encode('utf-8')
    )
  

После выполнения Windsurf покажет дифф всех изменённых файлов, и вы сможете принять или отклонить каждое изменение по отдельности. Это ключевое преимущество перед обычными чат-ботами — полный контроль над тем, что попадает в кодовую базу.

# 5. Agent Mode: автономное выполнение задач

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

Пример: создание REST API с нуля

Попросим агента создать простой REST API на Flask с тремя эндпоинтами и базой данных SQLite:

# Запрос в Agent Mode
Создай REST API для управления задачами (todo list).
Стек: Flask + SQLite + SQLAlchemy.
Эндпоинты:
  GET    /api/tasks       — список всех задач
  POST   /api/tasks       — создать новую задачу
  PUT    /api/tasks/{id}  — обновить статус задачи
Добавь requirements.txt, README.md и docker-compose.yml.
Запусти сервер и проверь, что все эндпоинты отвечают.
  

Агент выполнит следующие шаги автоматически:

1. Создаст структуру проекта: app.py, models.py, requirements.txt
2. Напишет Flask-приложение с SQLAlchemy-моделями
3. Создаст docker-compose.yml и Dockerfile
4. Установит зависимости через pip install -r requirements.txt
5. Запустит сервер и протестирует эндпоинты через curl
6. При обнаружении ошибок — исправит код и перезапустит

Пример кода, который сгенерирует агент:

# app.py — основной файл приложения
from flask import Flask, request, jsonify
from models import db, Task

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///tasks.db'
db.init_app(app)

with app.app_context():
    db.create_all()

@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    tasks = Task.query.all()
    return jsonify([t.to_dict() for t in tasks])

@app.route('/api/tasks', methods=['POST'])
def create_task():
    data = request.get_json()
    task = Task(title=data['title'])
    db.session.add(task)
    db.session.commit()
    return jsonify(task.to_dict()), 201

if __name__ == '__main__':
    app.run(debug=True, port=5000)
  

Важно: Agent Mode выполняет реальные операции в вашей файловой системе. Перед запуском сложных задач убедитесь, что проект находится под версионным контролем (Git), чтобы можно было откатить нежелательные изменения. Рекомендую включать агента для изолированных задач и всегда просматривать дифф перед коммитом.

# 6. Интеграция с терминалом и Git

Встроенный терминал Windsurf — это не просто эмулятор shell. Cascade имеет прямой доступ к терминалу: он может выполнять команды, читать stdout/stderr и адаптировать свои ответы на основе вывода. Вы можете попросить Cascade объяснить ошибку, которую вы видите в терминале, и он предложит исправление с учётом контекста.

AI-ассистент в терминале

# Выполняем тесты — получаем ошибку импорта
pytest tests/ -v
ModuleNotFoundError: No module named 'sqlalchemy'

# Выделяем ошибку → Ctrl+Shift+L → Cascade объясняет и предлагает fix
pip install sqlalchemy
pytest tests/ -v
============================= 12 passed in 0.87s =============================
  

Git-интеграция с AI

Панель Source Control в Windsurf дополнена AI-функциями: автоматическая генерация сообщений коммитов на основе диффа, интеллектуальное разрешение конфликтов слияния и создание описаний Pull Request. Вот как это работает на практике:

# Обычный рабочий процесс с AI-ускорением
git add -A

# Жмём кнопку "Generate Commit Message" — Cascade анализирует дифф
git commit -m "feat(auth): extract password hashing to utils/hash_utils module

- Add hash_password and verify_password functions using bcrypt
- Update all imports across auth service and user management
- Remove deprecated inline hashing logic
- Add unit tests for new hash utilities"

# При конфликте слияния — Cascade предлагает варианты разрешения
git merge feature/new-dashboard
Auto-merging src/routes.py
CONFLICT (content): Merge conflict in src/routes.py

# Выделяем конфликтный блок → Cascade → "Resolve conflict"

AI-разрешение конфликтов — одна из самых впечатляющих функций. Cascade анализирует обе ветки, понимает намерения разработчиков и предлагает решение, которое сохраняет логику обоих изменений. Это экономит массу времени в крупных проектах с активной разработкой.

# 7. Советы и трюки для продуктивной работы

🔹 Формулируйте задачи чётко и с контекстом

Качество ответа Cascade прямо пропорционально качеству запроса. Вместо «почини этот код» напишите: «Функция parse_config падает с KeyError при отсутствии ключа database — добавь значение по умолчанию sqlite:///default.db и соответствующий тест». Чем конкретнее инструкция, тем точнее результат.

🔹 Используйте @-упоминания файлов

В чате Cascade можно упоминать файлы через @filename — это явно добавляет их в контекст запроса. Если вам нужно отрефакторить функцию, которая использует утилиты из трёх разных модулей, упомяните все три файла: @utils/db.py @utils/cache.py @services/auth.py.

🔹 Настройте кастомные правила в .windsurfrules

В корне проекта можно создать файл .windsurfrules, который определяет правила поведения Cascade для данного проекта: стиль кода, соглашения об именовании, запрещённые паттерны, обязательные импорты. Это аналог .cursorrules из Cursor IDE. Пример:

# .windsurfrules — правила для Cascade в этом проекте
- Всегда используй type hints в Python-функциях
- Для тестов используй pytest, не unittest
- Логирование через loguru, не стандартный logging
- Названия переменных — snake_case, классов — PascalCase
- Максимальная длина строки: 100 символов
- Перед созданием нового файла проверь, нет ли похожего в проекте

  

🔹 Комбинируйте Agent Mode с ручным контролем

Оптимальная стратегия: дайте агенту выполнить черновую работу (создать структуру, написать boilerplate, добавить тесты), а затем вручную доработайте критически важные участки. Так вы получаете скорость AI и сохраняете контроль над архитектурными решениями.

🔹 Горячие клавиши, которые стоит запомнить

🔹 Держите зависимости актуальными

Windsurf обновляется каждые две недели. Новые версии часто приносят улучшения Cascade и Supercomplete. Проверить наличие обновлений можно в Help → Check for Updates или через CLI: windsurf --update. Не откладывайте обновления — каждая версия делает AI точнее и быстрее.