Claude Code 101

Этот курс познакомит вас с Claude Code — AI-помощником для программирования от Anthropic. Мы начнём с базовой теории о том, как работают большие языковые модели (LLM), а затем перейдём к практике: установка, настройка и реальные примеры использования.

Официальная документация Claude Code: code.claude.com/docs

Для кого этот курс:

Разработчики, которые хотят ускорить свою работу с помощью AI
Аналитики данных, которые хотят автоматизировать рутинные задачи
Все, кому интересно попробовать Claude Code на практике

Структура курса:

Модуль	Тема
01	Основы LLM
02	Что такое Claude Code
03	Возможности Claude Code
04	Практика: Анализ акций
05	Больше примеров
06	Качество кода от AI
07	Армия агентов
08	MCP и расширения
09	Лучшие практики
10	Другие модели

Что вам понадобится:

Компьютер с macOS, Linux или Windows
Терминал (командная строка)
Аккаунт Anthropic с API-ключом (или подписка Claude Pro/Max)
Python 3.10+ (для практических примеров)

Модуль 1: Основы больших языковых моделей (LLM)

Подробнее о моделях Claude: claude.ai/pricing | docs.anthropic.com/en/docs/about-claude/models

Что такое LLM?

LLM (Large Language Model) — это большая языковая модель. Проще говоря, это программа, которая умеет работать с текстом: читать, понимать и генерировать его.

Представьте себе очень начитанного собеседника, который прочитал миллиарды текстов из интернета, книг и статей. Он не “думает” как человек, но может очень хорошо предсказывать, какое слово должно идти следующим в предложении. Из этой простой способности рождаются удивительные вещи: написание кода, ответы на вопросы, перевод текстов и многое другое.

Как работает LLM: простое объяснение

Шаг 1: Обучение

Модель “читает” огромное количество текстов. Во время чтения она учится находить закономерности:

Какие слова часто стоят рядом
Как строятся предложения
Какая логика связывает идеи

Это похоже на то, как ребёнок учит язык: он слышит много речи и начинает понимать правила, даже не зная грамматики.

Шаг 2: Параметры

Результат обучения — это миллиарды числовых параметров (весов). Каждый параметр — это маленький кусочек “знания”. Когда говорят “модель на 175 миллиардов параметров”, это значит, что у неё 175 миллиардов таких настроек.

Модель	Параметры	Компания
GPT-4	~1.8 триллиона*	OpenAI
Claude 4.5 Sonnet	не раскрыто	Anthropic
Claude 4.6 Opus	не раскрыто	Anthropic
Llama 3	8B — 405B	Meta
Gemini	не раскрыто	Google

Точные цифры для многих моделей не публикуются.

Шаг 3: Генерация текста

Когда вы задаёте вопрос модели, она не ищет готовый ответ в базе данных. Вместо этого она генерирует текст слово за словом (точнее, токен за токеном), каждый раз выбирая наиболее подходящее следующее слово.

Ваш вопрос: "Столица Франции — это"
Модель думает: [Париж: 95%] [Лион: 2%] [Марсель: 1%] ...
Ответ: "Париж"

Ключевые понятия

Токены — LLM работает не со словами, а с токенами. Токен — это кусочек текста. Примеры:

“Hello” → 1 токен
“Привет” → 2-3 токена (кириллица занимает больше токенов)
“программирование” → 3-4 токена

Почему это важно? Потому что у каждой модели есть лимит контекста — максимальное количество токенов, которое она может обработать за один раз.

Контекстное окно — это “память” модели в рамках одного разговора.

Модель	Размер контекста
Claude 4.5 Sonnet	200K токенов
Claude 4.6 Opus	200K токенов
GPT-4 Turbo	128K токенов

200K токенов — это примерно 150,000 слов или 500 страниц текста.

Промпт (Prompt) — это текст, который вы отправляете модели. Качество промпта напрямую влияет на качество ответа.

Температура — настройка, которая влияет на “креативность” модели. Температура 0 — самый вероятный ответ, температура 1 — более “творческий”.

Anthropic и Claude

Anthropic — компания, которая создала Claude. Она была основана в 2021 году бывшими сотрудниками OpenAI.

Модель	Особенность	Лучше всего для
Claude 4.5 Haiku	Быстрая и дешёвая	Простые задачи, чат-боты
Claude 4.5 Sonnet	Баланс скорости и качества	Ежедневная работа с кодом
Claude 4.6 Opus	Максимальное качество	Самые сложные задачи

Итоги модуля

LLM — это модель, которая предсказывает следующий токен на основе контекста
Качество ответа зависит от качества промпта
У моделей есть ограничения: они могут ошибаться и “галлюцинировать”
Claude от Anthropic — одна из лучших моделей для работы с кодом

Модуль 2: Что такое Claude Code

Официальная документация: code.claude.com/docs/en/overview | Быстрый старт

Введение

Claude Code — это AI-помощник для программирования, который работает прямо в вашем терминале. В отличие от обычного чата с Claude, Claude Code может:

Читать файлы вашего проекта
Создавать и редактировать файлы
Запускать команды в терминале
Работать с git
Искать информацию в интернете
Понимать контекст всего проекта

Инструмент	Где работает	Что умеет
ChatGPT / Claude.ai	Веб-браузер	Отвечает на вопросы, пишет код в чате
GitHub Copilot	IDE (VS Code, JetBrains)	Автодополнение кода в редакторе
Cursor	IDE	AI-редактор кода с чатом
Claude Code	Терминал	Полный доступ к проекту, выполнение команд, работа с файлами

Claude Code — экран приветствия

Установка Claude Code

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

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

# macOS через Homebrew
brew install --cask claude-code

# Windows через WinGet
winget install Anthropic.ClaudeCode

Способы авторизации

Вариант 1: Anthropic API Key

export ANTHROPIC_API_KEY="sk-ant-..."
claude

Вариант 2: Claude Max подписка — подписка Claude Pro ($20/мес), Claude Max ($100/мес или $200/мес).

Основные команды

Команда	Что делает
`/help`	Показать справку
`/exit`	Выйти из Claude Code
`/clear`	Очистить историю разговора
`/compact`	Сжать контекст
`/model`	Показать или сменить модель
`/cost`	Показать стоимость текущей сессии
`/permissions`	Управление разрешениями

Режимы работы

claude                    # Обычный интерактивный режим
claude -p "..."           # Выполнить одну команду и выйти (headless)
claude --continue         # Продолжить предыдущий разговор
claude --model claude-sonnet-4-5-20250929  # Запустить с конкретной моделью

Разрешения (Permissions)

Действие	Нужно разрешение?
Чтение файлов	Нет
Создание/редактирование файлов	Да (при первом разе)
Запуск команд (python, npm)	Да (при первом разе)
Запуск потенциально опасных команд (rm, sudo)	Да (каждый раз)

Флаг --dangerously-skip-permissions отключает все запросы на разрешение. Используйте с осторожностью.

Работа с IDE

Самый простой способ для начинающих — запустить Claude Code прямо во встроенном терминале VS Code. Вы видите файлы проекта, изменения в реальном времени и Claude Code — всё в одном окне:

Claude Code во встроенном терминале VS Code

Также можно использовать отдельный терминал рядом с IDE:

┌─────────────────────────────┬──────────────────────────────┐
│   VS Code / IDE             │   Терминал                   │
│   📁 my-project/            │   $ claude                   │
│   ├── src/                  │                              │
│   │   ├── main.py      ◀───│── > Добавь логирование       │
│   │   └── utils.py         │     в main.py                │
│   ├── tests/                │                              │
│   └── README.md             │   Claude Code создаёт файлы, │
│                             │   а вы видите изменения      │
│   Подсветка синтаксиса      │   в IDE в реальном времени   │
│   Git diff                  │                              │
└─────────────────────────────┴──────────────────────────────┘

Файл CLAUDE.md

Создайте CLAUDE.md в корне проекта, чтобы дать Claude Code инструкции о вашем проекте. Claude Code автоматически прочитает этот файл и будет следовать вашим правилам.

Итоги модуля

Claude Code работает в терминале и имеет полный доступ к проекту
Установка: curl -fsSL https://claude.ai/install.sh | bash
Используйте slash-команды для управления
Откройте проект в IDE рядом с терминалом для удобства

Модуль 3: Возможности Claude Code

Официальная документация: code.claude.com/docs/en/how-claude-code-works

Как Claude Code работает: агентный цикл

Когда вы даёте задачу Claude Code, он работает в три фазы:

Собрать контекст — читает файлы, ищет по проекту
Выполнить действие — редактирует код, запускает команды
Проверить результат — запускает тесты, смотрит вывод

Эти фазы повторяются в цикле, пока задача не решена:

Агентный цикл Claude Code

Claude сам решает, какой инструмент использовать на каждом шаге. Вы можете прервать в любой момент (Esc) и направить в другую сторону.

Встроенные инструменты

Категория	Что может Claude
Файлы	Читать, редактировать, создавать, переименовывать
Поиск	Искать файлы по имени, искать по содержимому (regex)
Выполнение	Запускать команды, тесты, серверы, git
Веб	Искать в интернете, открывать документацию

Работа с файлами

> Объясни, что делает файл src/main.py
> Создай файл utils/helpers.py с функциями для работы с датами
> В файле main.py добавь обработку ошибок в функцию load_data()
> Найди все файлы, где используется функция calculate_price()

Запуск команд

> Запусти main.py с аргументом --verbose
> Установи библиотеки pandas, matplotlib и yfinance
> Создай виртуальное окружение Python и установи зависимости

Работа с Git

> Инициализируй git-репозиторий
> Посмотри что изменилось и сделай коммит с хорошим описанием
> Создай pull request с описанием всех изменений

Отладка и исправление ошибок

> У меня ошибка: "TypeError: cannot unpack non-iterable NoneType object"
  в файле processor.py на строке 45. Исправь.
> Запусти тесты. Если что-то упало — исправь.

Мультимодальный ввод (Multimodal Prompting)

Claude Code понимает не только текст, но и изображения. Вы можете передать скриншот, макет дизайна или диаграмму — и Claude будет работать с ними как с контекстом.

Как передать изображение:

Drag & drop — перетащите картинку прямо в терминал Claude Code
Копировать-вставить — скопируйте изображение и вставьте (Ctrl+V / Cmd+V)
Путь к файлу — укажите путь: @screenshot.png

Примеры использования:

> [вставить скриншот бага в UI]
  Видишь этот баг? Кнопка "Сохранить" перекрывает текст. Исправь CSS.

> [вставить макет из Figma]
  Реализуй этот дизайн страницы. Используй Tailwind CSS.

> [вставить диаграмму архитектуры]
  Вот схема микросервисов. Создай структуру проекта по этой архитектуре.

> [вставить скриншот ошибки в браузере]
  Вот что я вижу в консоли браузера. Найди и исправь эту ошибку.

Когда это полезно:

Сценарий	Что передаёте	Что Claude делает
Баг в UI	Скриншот страницы	Находит проблему в CSS/HTML и исправляет
Реализация дизайна	Макет из Figma/Sketch	Пишет код компонента по картинке
Архитектура	Диаграмму системы	Создаёт структуру проекта и модули
Ошибка в браузере	Скриншот консоли	Находит баг по стектрейсу на картинке
Код-ревью	Скриншот PR	Анализирует изменения и даёт фидбек

Совет: мультимодальный ввод особенно мощен в связке с проверкой результата. Попросите Claude: “Реализуй этот макет. Потом сделай скриншот результата и сравни с оригиналом” — и он сможет сам итеративно улучшать код, пока результат не совпадёт с макетом.

Headless-режим (автоматизация)

claude -p "Сгенерируй API документацию для всех endpoints в src/api/"
claude -p "Проверь код в последнем коммите и найди возможные проблемы"

Работа с сессиями

claude --continue          # Продолжить последний разговор
claude --resume            # Выбрать из недавних сессий
claude --continue --fork-session  # Ответвить: новая сессия с историей старой

Таблица возможностей

Возможность	Пример использования	Сложность
Чтение файлов	”Объясни этот код”	Простая
Создание файлов	”Создай скрипт для…”	Простая
Запуск команд	”Запусти тесты”	Простая
Git операции	”Закоммить с описанием”	Простая
Отладка	”Исправь эту ошибку”	Средняя
Рефакторинг	”Улучши структуру кода”	Средняя
Создание проекта	”Создай REST API”	Средняя
Мультимодальный ввод	”Реализуй этот макет [скриншот]“	Средняя
Многофайловые задачи	”Добавь логирование везде”	Сложная
CI/CD интеграция	Автоматический ревью	Сложная

Итоги модуля

Claude Code работает через агентный цикл: собрать контекст → выполнить → проверить → повторить
Он работает с файлами, git, командами и может создавать целые проекты
Мультимодальный ввод — передавайте скриншоты, макеты и диаграммы прямо в промпт
Headless-режим (claude -p) позволяет использовать Claude Code в автоматизации

Модуль 4: Практика — Анализ акций Microsoft

Что мы будем делать

В этом модуле мы создадим Python-программу, которая:

Загружает данные о цене акций Microsoft (MSFT) за последний год
Визуализирует цену акций на графике
Отмечает ключевые события на графике
Помогает понять, почему цена росла или падала

Подготовка

mkdir stock-analysis
cd stock-analysis
claude

Попросите Claude Code подготовить окружение:

Создай виртуальное окружение Python, файл requirements.txt
с библиотеками yfinance, pandas, matplotlib, requests и seaborn.
Активируй окружение и установи зависимости.

Этап 1: Загрузка данных об акциях

Создай файл stock_analysis.py со следующей функцией:

1. Функция download_stock_data(ticker, period):
   - Загружает данные об акциях по тикеру (например "MSFT")
     за указанный период (например "1y" — один год)
   - Использует библиотеку yfinance
   - Возвращает DataFrame

2. В блоке if __name__ == "__main__" вызови функцию для тикера MSFT

Claude Code создаст файл с полным кодом:

import yfinance as yf
import pandas as pd


def download_stock_data(ticker: str, period: str = "1y") -> pd.DataFrame:
    """Загружает данные об акциях."""
    stock = yf.Ticker(ticker)
    df = stock.history(period=period)
    df = df.reset_index()
    df["Date"] = pd.to_datetime(df["Date"]).dt.tz_localize(None)
    return df


if __name__ == "__main__":
    df = download_stock_data("MSFT", period="1y")
    print(df.head())

Этап 2: Визуализация цены акций

Добавь в stock_analysis.py функцию plot_stock_price(df, ticker):
- Строит график цены закрытия акций
- Добавь скользящие средние: MA50 и MA200
- Сохрани в файл stock_price.png

Этап 3: Добавляем объём торгов

Добавь функцию plot_price_and_volume(df, ticker) —
два графика один под другим: цена и объём торгов.

Этап 4: Добавляем ключевые события

Добавь функцию add_key_events(df, ticker):
- Список ключевых событий Microsoft
- Вертикальные линии на графике (зелёные — позитивные, красные — негативные)

Что мы узнали из графиков

Почему цена растёт:

Сильные квартальные отчёты
Рост облачного бизнеса (Azure)
AI-продукты (Copilot)

Почему цена падает:

Слабые прогнозы
Замедление роста
Макроэкономика

Скользящие средние:

MA50 выше MA200 — бычий сигнал
MA50 ниже MA200 — медвежий сигнал
Пересечение MA50 и MA200 — “золотой крест” или “крест смерти”

Домашнее задание

Замените тикер — проанализируйте AAPL, GOOGL, NVDA
Добавьте сравнение двух акций на одном графике
Добавьте RSI индикатор
Экспорт в HTML с помощью plotly

Итоги модуля

Мы создали полноценную программу анализа акций шаг за шагом
Claude Code помогал на каждом этапе
Каждый промпт был конкретным и описывал ожидаемый результат

Модуль 5: Больше примеров использования Claude Code

Введение

В этом модуле мы рассмотрим разные сценарии, где Claude Code может помочь. Каждый пример — это реальная задача, которую можно решить за несколько минут.

Пример 1: Веб-скрапер для сбора данных

Создай Python-скрипт news_scraper.py, который:
1. Использует библиотеку requests и beautifulsoup4
2. Загружает главную страницу Hacker News
3. Извлекает заголовки новостей, ссылки и баллы
4. Сохраняет результат в hacker_news.csv

Пример 2: Автоматизация работы с файлами

Создай скрипт file_organizer.py, который:
1. Принимает путь к папке как аргумент
2. Создаёт подпапки по типу файла
3. Перемещает файлы в соответствующие подпапки
4. Поддерживает флаг --dry-run

Пример 3: REST API за 5 минут

Создай REST API на FastAPI для управления заметками:
- CRUD операции
- SQLite через SQLAlchemy
- Dockerfile и docker-compose.yml

Пример 4: Анализ данных и отчёт

Создай скрипт sales_report.py:
- Генерирует тестовые данные
- Анализирует продажи
- Создаёт 4 графика (2x2)
- Сохраняет в sales_dashboard.png

Пример 5: Бот для Telegram

Создай Telegram-бота на Python:
- /start, /weather, /currency, /joke
- Токены из переменных окружения

Пример 6: Рефакторинг существующего кода

Проанализируй весь Python-код и:
- Найди проблемы, добавь type hints, docstrings, логирование
- Создай отчёт refactoring_report.md

Пример 7: Работа с базой данных

Создай утилиту db_migrator.py:
- Читает данные из SQLite
- Экспорт в CSV, JSON, Parquet
- Интерактивное меню

Пример 8: Тестирование

Для проекта stock_analysis.py:
- Тесты на pytest с моками
- conftest.py с фикстурами

Пример 9: Документация

Создай полный README.md, добавь docstrings, CHANGELOG.md

Сводная таблица

#	Задача	Сложность	Время*	Ключевые навыки
1	Веб-скрапер	Простая	5 мин	requests, BS4, CSV
2	Файловый органайзер	Простая	5 мин	os, argparse
3	REST API	Средняя	15 мин	FastAPI, SQLAlchemy, Docker
4	Дашборд продаж	Средняя	10 мин	pandas, matplotlib
5	Telegram бот	Средняя	15 мин	API, бот-фреймворк
6	Рефакторинг	Средняя	10 мин	Анализ кода, PEP 8
7	DB-утилита	Средняя	10 мин	SQLite, CLI
8	Тесты	Средняя	10 мин	pytest, mocking
9	Документация	Простая	5 мин	Markdown, docstrings

Примерное время с Claude Code. Без него каждая задача заняла бы в 3-5 раз больше.

Советы из практики

Итеративный подход — не пытайтесь описать всё в одном промпте
Проверка на каждом шаге — запускайте и тестируйте
Контекст проекта — дайте Claude Code больше информации
Файл CLAUDE.md — создайте правила для проекта
Работа с ошибками — просто скопируйте ошибку Claude Code

Итоги модуля

Конкретность — чем точнее промпт, тем лучше результат
Итерации — разбивайте задачи на шаги
Проверка — всегда проверяйте сгенерированный код
Контекст — давайте Claude Code информацию о проекте

Модуль 6: Качество моделей и кода от AI-агентов

Подробнее о моделях: docs.anthropic.com/en/docs/about-claude/models | Настройка моделей в Claude Code

Не весь код одинаково полезен

AI-агенты пишут код быстро. Но быстро — не значит хорошо. “Рабочий” и “качественный” — это разные вещи.

Сравнение моделей

Модель	Скорость	Качество кода	Цена	Лучше всего для
Claude 4.5 Haiku	Очень быстрая	Хорошее	$	Простые задачи, быстрые правки
Claude 4.5 Sonnet	Быстрая	Очень хорошее	$$	Ежедневная работа, рефакторинг
Claude 4.6 Opus	Медленнее	Отличное	$$$$	Архитектура, сложная логика

Типичные проблемы качества

Галлюцинации в коде — AI может “выдумать” несуществующие функции
Забытая обработка ошибок — код работает только на “happy path”
Проблемы с безопасностью — SQL injection, хардкод секретов
Избыточная сложность — 50 строк с классами для 5-строчной задачи
Устаревшие подходы — os.path вместо pathlib

Чеклист качества кода

Базовый уровень:

Код запускается
Код делает то, что нужно
Нет хардкода секретов
Зависимости существуют

Средний уровень:

Type hints
Docstrings
Обработка ошибок
Тесты

Продвинутый уровень:

Линтер проходит
Безопасность проверена
Edge cases обработаны

Как заставить Claude Code писать качественно

Детальный промпт — описывайте требования к качеству
Файл CLAUDE.md — создайте правила один раз
Двухшаговый подход — сначала генерация, потом ревью
Автоматическая проверка — ruff, mypy, pytest

Бенчмарки моделей

Модель	SWE-bench	Комментарий
Claude 4.6 Opus	~72%	Лучший результат среди всех моделей*
Claude 4.5 Sonnet	~70%	Отличный баланс цены и качества
GPT-4o	~38%	Отстаёт в coding-бенчмарках

Когда НЕ доверять AI-коду

Криптография — используйте проверенные библиотеки
Финансовые вычисления — AI может ошибиться в округлении
Безопасность — проверяйте аутентификацию и авторизацию вручную

Итоги модуля

Качество зависит от промпта и модели
Opus для сложных задач, Sonnet для повседневной работы
Файл CLAUDE.md с правилами качества — ваш лучший друг
Не доверяйте AI в критических областях

Модуль 7: Армия агентов — автономная разработка

Документация: Субагенты | Agent Teams | Параллельные сессии

Введение

Один Claude Code — это мощный инструмент. Но что если запустить несколько агентов одновременно, каждый со своей задачей? Что если дать им спецификацию проекта и позволить самим решать, как его построить?

В этом модуле мы разберём, как превратить одного AI-помощника в целую команду разработчиков.

Идея: от одного агента к армии

Один агент:

Вы → Claude Code → результат

Вы даёте задачу, агент выполняет, вы проверяете. Это работает, но у одного агента есть ограничения:

Один контекст — он может “забыть” начало длинного разговора
Одна задача — пока он пишет код, он не может одновременно запускать тесты
Последовательная работа — задачи выполняются одна за другой

Армия агентов:

Спецификация
    ├── Агент 1: Backend API
    ├── Агент 2: Frontend
    ├── Агент 3: Тесты
    ├── Агент 4: Документация
    └── Агент 5: DevOps

Каждый агент работает параллельно и автономно над своей частью. Как настоящая команда разработчиков, где каждый знает свою зону ответственности.

Способ 1: Несколько терминалов с Claude Code

Самый простой подход — открыть несколько терминалов.

Шаг 1: Подготовьте спецификацию

Создайте файл SPEC.md в корне проекта:

# Спецификация проекта: Task Manager API

## Описание
REST API для управления задачами с аутентификацией.

## Технологии
- Python 3.12, FastAPI, SQLAlchemy 2.0, PostgreSQL
- pytest для тестов
- Docker для деплоя

## Модули
1. **auth** — регистрация, логин, JWT токены
2. **tasks** — CRUD для задач
3. **users** — профили пользователей
4. **notifications** — уведомления по email

## Структура
src/
├── api/          # Endpoints
├── models/       # SQLAlchemy модели
├── schemas/      # Pydantic схемы
├── services/     # Бизнес-логика
├── tests/        # Тесты
└── main.py       # Точка входа

Шаг 2: Запустите агентов в разных терминалах

Терминал 1 — Архитектор:

cd my-project
claude

> Прочитай SPEC.md. Создай структуру проекта:
  все папки, __init__.py файлы, базовые конфиги,
  requirements.txt, Dockerfile, docker-compose.yml.
  НЕ пиши бизнес-логику — только скелет проекта.

Терминал 2 — Backend-разработчик (после того как архитектор закончил):

cd my-project
claude

> Прочитай SPEC.md. Реализуй модуль auth:
  - Модель User в models/user.py
  - Схемы в schemas/auth.py
  - Сервис аутентификации в services/auth.py
  - Endpoints в api/auth.py
  - Используй JWT через python-jose

Терминал 3 — Разработчик тестов:

cd my-project
claude

> Прочитай SPEC.md и файлы в src/.
  Напиши тесты для всех существующих модулей.
  Используй pytest + pytest-asyncio.
  Замокай базу данных через SQLite in-memory.
  Запусти тесты и убедись что проходят.

Терминал 4 — Документация:

cd my-project
claude

> Прочитай весь код в src/.
  Создай полный README.md:
  - Описание проекта
  - Установка и настройка
  - API документация со всеми endpoints
  - Примеры запросов (curl)
  - Как запускать тесты
  - Docker инструкции

Координация:

Архитектор работает первым — создаёт структуру и интерфейсы
Разработчики работают параллельно — каждый в своём модуле
Тестировщик работает последним — когда код уже написан
Документация идёт в конце — когда API стабилен

Способ 2: Headless-режим с оркестрацией

Более продвинутый подход — управлять агентами из скрипта.

#!/bin/bash
# orchestrator.sh — запускает армию агентов

PROJECT_DIR="$(pwd)"
SPEC="$PROJECT_DIR/SPEC.md"

echo "Запуск армии агентов..."
echo "Спецификация: $SPEC"

# Шаг 1: Архитектор создаёт структуру
echo "Этап 1: Архитектура"

claude -p "Прочитай SPEC.md. Создай структуру проекта: \
все папки, конфиги, requirements.txt, базовые файлы. \
Только скелет, без бизнес-логики."

# Шаг 2: Параллельная разработка модулей
echo "Этап 2: Параллельная разработка"

# Запускаем 3 агента параллельно
claude -p "Прочитай SPEC.md. Реализуй модуль auth: \
модели, схемы, сервисы, endpoints." &
PID1=$!

claude -p "Прочитай SPEC.md. Реализуй модуль tasks: \
модели, схемы, сервисы, endpoints." &
PID2=$!

claude -p "Прочитай SPEC.md. Реализуй модуль users: \
модели, схемы, сервисы, endpoints." &
PID3=$!

# Ждём завершения всех агентов
wait $PID1 $PID2 $PID3

# Шаг 3: Тесты
echo "Этап 3: Тестирование"

claude -p "Прочитай весь код в src/. Напиши тесты для всех модулей. \
Запусти тесты. Если что-то падает — исправь код и тесты."

# Шаг 4: Документация
echo "Этап 4: Документация"

claude -p "Прочитай весь проект. Создай полный README.md \
с API-документацией, примерами и инструкциями."

echo "Проект готов!"

Запуск оркестратора:

chmod +x orchestrator.sh
./orchestrator.sh

Способ 3: Claude Code как субагенты (встроенная функция)

Claude Code в IDE-инструментах (Cursor, VS Code) может сам запускать субагентов — дочерние процессы, которые работают автономно.

Когда вы даёте Claude Code сложную задачу, он может:

Разбить задачу на подзадачи
Запустить субагента для каждой подзадачи
Собрать результаты
Интегрировать всё вместе

Пример задачи для Cursor с субагентами:

Создай полный проект Task Manager API по спецификации в SPEC.md.

Разбей работу на этапы:
1. Сначала создай структуру проекта
2. Потом реализуй каждый модуль параллельно
3. Потом напиши тесты
4. Потом создай документацию

Используй субагентов для параллельных задач где возможно.

Способ 4: Спецификация как контракт

Самый мощный подход — это когда вы пишете только спецификацию, а агенты сами решают как её реализовать.

Уровень 1: Высокоуровневый (для прототипа)

# Task Manager

Веб-приложение для управления задачами.

Пользователь может:
- Регистрироваться и логиниться
- Создавать задачи с заголовком, описанием и дедлайном
- Отмечать задачи как выполненные
- Фильтровать задачи по статусу
- Получать уведомления о дедлайнах

Технологии: Python, FastAPI, PostgreSQL, Docker.

Этого достаточно чтобы агент (особенно на модели Opus) создал полноценный проект. Но результат может отличаться от ожиданий.

Уровень 2: Детальный (рекомендуется)

# Task Manager API

## Модели данных

### User
| Поле | Тип | Описание |
|------|-----|----------|
| id | UUID | Уникальный идентификатор |
| email | string | Email (уникальный) |
| password_hash | string | Хеш пароля |
| name | string | Имя пользователя |
| created_at | datetime | Дата регистрации |

### Task
| Поле | Тип | Описание |
|------|-----|----------|
| id | UUID | Уникальный идентификатор |
| title | string | Заголовок (макс. 200 символов) |
| description | text | Описание (опционально) |
| status | enum | pending / in_progress / done |
| priority | enum | low / medium / high |
| due_date | datetime | Дедлайн (опционально) |
| user_id | UUID | Владелец задачи |
| created_at | datetime | Дата создания |
| updated_at | datetime | Дата обновления |

## API Endpoints

### Аутентификация
- POST /auth/register — регистрация
- POST /auth/login — логин (возвращает JWT)
- POST /auth/refresh — обновление токена

### Задачи
- GET /tasks — список задач текущего пользователя
  - Query params: status, priority, sort_by, page, per_page
- POST /tasks — создать задачу
- GET /tasks/{id} — получить задачу
- PUT /tasks/{id} — обновить задачу
- DELETE /tasks/{id} — удалить задачу

### Бизнес-правила
- Пользователь видит только свои задачи
- При удалении аккаунта удаляются все его задачи
- Дедлайн не может быть в прошлом
- Название задачи обязательно

Уровень 3: Контрактный (для продакшена)

# Контракт: Task Manager API v1.0

## Нефункциональные требования
- Время ответа API: <200ms (p95)
- Покрытие тестами: >85%
- Zero downtime deployment
- Rate limiting: 100 req/min per user

## Безопасность
- JWT с ротацией refresh-токенов
- Bcrypt для паролей (cost factor 12)
- CORS только для разрешённых доменов
- Rate limiting на /auth/* endpoints

## Обработка ошибок
- Все ошибки в формате: {"error": {"code": "...", "message": "..."}}
- HTTP 400 — невалидные данные
- HTTP 401 — не аутентифицирован
- HTTP 403 — нет прав доступа
- HTTP 404 — ресурс не найден
- HTTP 429 — превышен лимит запросов
- HTTP 500 — внутренняя ошибка (логировать в Sentry)

## Тесты
- Unit тесты для каждого сервиса
- Integration тесты для каждого endpoint
- E2E тесты для основных сценариев
- Load тесты (locust) для критических путей

Какой уровень спецификации использовать?

Ситуация	Уровень	Почему
Прототип / хакатон	1 (высокоуровневый)	Скорость важнее качества
Рабочий проект	2 (детальный)	Баланс скорости и предсказуемости
Продакшен	3 (контрактный)	Нужна гарантия качества

Способ 5: Agent Teams — встроенные команды агентов

Это официальная функция Claude Code для координации нескольких агентов. В отличие от ручных способов выше, Agent Teams — это встроенный механизм, где агенты сами координируют работу, обмениваются сообщениями и ведут общий список задач.

Функция экспериментальная. Документация: code.claude.com/docs/en/agent-teams

Как это устроено:

Компонент	Роль
Team Lead	Главная сессия Claude Code. Создаёт команду, раздаёт задачи, собирает результаты
Teammates	Отдельные экземпляры Claude Code. Каждый работает над своей задачей
Task List	Общий список задач. Агенты сами берут задачи и отмечают выполнение
Mailbox	Система сообщений между агентами. Могут общаться напрямую друг с другом

Главное отличие от субагентов: в Agent Teams агенты общаются друг с другом напрямую, а не только отчитываются главному.

Субагенты:                    Agent Teams:

  Главный                       Лид
  ├── Суб 1 → отчёт             ├── Агент 1 ←→ Агент 2
  ├── Суб 2 → отчёт             ├── Агент 2 ←→ Агент 3
  └── Суб 3 → отчёт             └── Агент 3 ←→ Агент 1
                                 (+ общий список задач)

Субагенты vs Agent Teams:

	Субагенты	Agent Teams
Контекст	Свой, результат возвращается вызывающему	Свой, полностью независимый
Общение	Только отчёт главному агенту	Агенты общаются друг с другом напрямую
Координация	Главный агент управляет всем	Общий список задач, самоорганизация
Лучше для	Точечные задачи, где важен только результат	Сложная работа, требующая обсуждений и сотрудничества
Токены	Меньше: результаты сжимаются	Больше: каждый агент — отдельный экземпляр Claude

Включение Agent Teams:

Функция отключена по умолчанию. Включите через settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Или через переменную окружения:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Создание команды:

Запустите Claude Code и опишите задачу и нужную команду на естественном языке:

Я проектирую CLI-инструмент для отслеживания TODO-комментариев
в коде. Создай команду агентов для исследования задачи
с разных сторон: один на UX, один на техническую архитектуру,
один в роли критика (devil's advocate).

Claude Code сам:

Создаст команду с общим списком задач
Запустит агентов для каждой роли
Даст им работать и обсуждать друг с другом
Соберёт результаты
Завершит работу команды

Режимы отображения:

In-process — все агенты в одном терминале:

Переключение между агентами: Shift+Up / Shift+Down
Просмотр списка задач: Ctrl+T
Работает в любом терминале

Split panes — каждый агент в своей панели:

Нужен tmux или iTerm2
Видите вывод всех агентов одновременно
Можно кликнуть в панель агента и общаться с ним напрямую

{
  "teammateMode": "in-process"
}

Или для split panes:

claude --teammate-mode tmux

Управление командой:

Задать количество агентов и модель:

Создай команду из 4 агентов для параллельного рефакторинга
этих модулей. Используй Sonnet для каждого агента.

Требовать одобрение плана перед работой:

Запусти агента-архитектора для рефакторинга модуля аутентификации.
Требуй одобрение плана перед тем как он начнёт менять код.

Агент создаст план, отправит его лиду на проверку. Лид одобрит или вернёт на доработку с комментариями. Только после одобрения агент начнёт писать код.

Режим делегирования (Delegate Mode):

Без этого режима лид иногда начинает делать задачи сам вместо делегирования. Delegate Mode ограничивает лида только координацией: он может запускать агентов, раздавать задачи и собирать результаты, но не может трогать код.

Включается: Shift+Tab после создания команды.

Общение с агентами напрямую:

Вы можете обратиться к любому агенту напрямую, минуя лида:

In-process: Shift+Up/Down для выбора агента, затем печатайте
Split panes: кликните в панель нужного агента

Когда Agent Teams работают лучше всего:

Хорошо подходят для:

Исследование и ревью — несколько агентов одновременно изучают разные аспекты проблемы
Новые модули — каждый агент отвечает за свой модуль, не мешая другим
Отладка с конкурирующими гипотезами — агенты проверяют разные теории параллельно и спорят друг с другом
Кросс-слойные изменения — frontend, backend и тесты, каждый под ответственностью отдельного агента

Не подходят для:

Последовательные задачи (используйте одну сессию)
Правки в одном файле (будут конфликты)
Задачи с множеством зависимостей (координация съест все преимущества)

Пример: параллельный код-ревью

Создай команду агентов для ревью PR #142. Запусти трёх ревьюеров:
- Один фокусируется на безопасности
- Один проверяет производительность
- Один валидирует покрытие тестами
Пусть каждый проверит и отчитается о находках.

Каждый ревьюер смотрит на один и тот же PR, но через свою “линзу”. Лид собирает находки от всех троих.

Пример: отладка с конкурирующими гипотезами

Пользователи жалуются, что приложение отключается после первого
сообщения вместо того чтобы держать соединение.
Создай команду из 5 агентов для исследования разных гипотез.
Пусть они спорят друг с другом и пытаются опровергнуть
теории коллег, как научные дебаты. Запиши итоги в findings.md.

Это мощный подход: один агент находит причину и останавливается. Пять агентов, которые спорят друг с другом, с большей вероятностью найдут настоящую причину.

Советы по Agent Teams:

Давайте агентам достаточно контекста — агенты не наследуют историю разговора лида. Подробно описывайте задачу при создании:

Запусти агента для ревью безопасности с промптом:
"Проверь модуль аутентификации в src/auth/ на уязвимости.
Фокусируйся на работе с токенами, управлении сессиями
и валидации входных данных. Приложение использует JWT
в httpOnly куках. Отчитайся со степенями серьёзности."

Правильный размер задач — слишком маленькие задачи: координация дороже пользы. Слишком большие: агенты работают слишком долго без проверки. Идеально: задачи, которые дают чёткий результат (функция, тест-файл, ревью).
Избегайте конфликтов файлов — два агента в одном файле = перезаписи. Разделяйте работу так, чтобы каждый агент владел своим набором файлов.
Следите за прогрессом — проверяйте что делают агенты, перенаправляйте если что-то идёт не так. Не оставляйте команду без присмотра надолго.

Ограничения Agent Teams:

Функция экспериментальная — может меняться
Нет возобновления сессий — /resume не восстанавливает агентов
Статус задач может отставать — агенты иногда забывают отметить задачу как выполненную
Одна команда на сессию — нельзя создать вложенные команды
Лид фиксирован — нельзя передать лидерство другому агенту
Split panes нужен tmux или iTerm2 — не работает в VS Code терминале или Ghostty

Паттерны работы с армией агентов

Паттерн 1: Конвейер (Pipeline)

Архитектор → Разработчик → Тестировщик → Ревьюер → Деплой

Каждый агент работает последовательно, передавая результат следующему.

# Этап 1: Архитектура
claude -p "Создай структуру проекта по SPEC.md"

# Этап 2: Код
claude -p "Реализуй все модули по SPEC.md"

# Этап 3: Тесты
claude -p "Напиши тесты и исправь баги"

# Этап 4: Ревью
claude -p "Проверь весь код на качество и безопасность. \
Создай отчёт review.md"

# Этап 5: Документация
claude -p "Создай полную документацию проекта"

Паттерн 2: Параллельные специалисты

           ┌─→ Агент: Backend ──┐
Спецификация─┼─→ Агент: Frontend ─┼─→ Интеграция
           └─→ Агент: DevOps ───┘

Агенты работают параллельно над разными частями системы. Важно: для этого паттерна нужны чёткие интерфейсы между модулями. Определите их заранее в спецификации.

Паттерн 3: Генерация + Проверка

Агент-генератор → Агент-ревьюер → Агент-исправитель

Один агент пишет код, другой проверяет, третий исправляет найденные проблемы.

# Генерация
claude -p "Напиши модуль обработки платежей по SPEC.md"

# Ревью
claude -p "Проверь код модуля payments/ на:
1. Безопасность (SQL injection, XSS)
2. Обработку ошибок
3. Edge cases
4. Соответствие SPEC.md
Запиши проблемы в файл review_issues.md"

# Исправление
claude -p "Прочитай review_issues.md и исправь все найденные проблемы. \
После каждого исправления запускай тесты."

Паттерн 4: Специализированные роли

Дайте каждому агенту конкретную роль:

Агент "Product Manager":
   "Прочитай SPEC.md, найди противоречия и неясности.
    Предложи уточнения."

Агент "Архитектор":
   "По SPEC.md спроектируй архитектуру.
    Создай диаграммы и ADR (Architecture Decision Records)."

Агент "Разработчик":
   "Реализуй модуль X по спецификации и архитектурным решениям."

Агент "QA":
   "Напиши тесты. Найди баги. Проверь edge cases."

Агент "Техписатель":
   "Создай документацию: README, API docs, deployment guide."

Агент "Безопасник":
   "Проведи security review. Найди уязвимости. Предложи исправления."

Практический пример: проект за 30 минут

Задача: создать API для блога с авторами, статьями и комментариями.

Шаг 1: Пишем спецификацию (5 минут)

# Blog API

## Модели
- Author: id, name, email, bio
- Post: id, title, content, author_id, status (draft/published),
  created_at, updated_at
- Comment: id, post_id, author_name, content, created_at

## Endpoints
- CRUD для Author, Post, Comment
- GET /posts — с пагинацией и фильтрами
- GET /authors/{id}/posts — статьи автора
- POST /posts/{id}/publish — публикация черновика

## Требования
- FastAPI + SQLite
- Тесты (pytest)
- Docker
- README с примерами

Шаг 2: Запускаем конвейер (25 минут)

# Терминал 1: Архитектор
claude -p "Прочитай SPEC.md. Создай структуру проекта, \
модели данных и базовую конфигурацию."

# Терминал 2: Backend (после архитектора)
claude -p "Прочитай SPEC.md. Реализуй все endpoints. \
Используй существующую структуру проекта."

# Терминал 3: Тесты + Качество (после backend)
claude -p "Прочитай весь код. Напиши тесты для всех endpoints. \
Запусти тесты. Исправь баги. Запусти ruff и mypy — исправь все ошибки."

# Терминал 4: Документация (после тестов)
claude -p "Создай README.md с полной документацией. \
Добавь примеры curl-запросов для каждого endpoint."

Результат: за 30 минут (большая часть — ожидание агентов) вы получите:

Полноценный REST API
Модели данных и миграции
Тесты с покрытием >80%
Docker-конфигурацию
Документацию с примерами

Git Worktrees и tmux: инфраструктура для параллельной работы

Когда несколько агентов работают одновременно над одним репозиторием, главная проблема — конфликты файлов. Два агента не могут одновременно менять один файл в одной рабочей копии. Решение — git worktrees.

Что такое git worktree:

Git worktree позволяет создать несколько рабочих директорий из одного репозитория. Каждая директория подключена к своей ветке, но все они используют один .git.

my-project/                  # Основная рабочая копия (ветка main)
my-project-auth/             # Worktree для агента 1 (ветка feature/auth)
my-project-api/              # Worktree для агента 2 (ветка feature/api)
my-project-tests/            # Worktree для агента 3 (ветка feature/tests)

Без worktrees:

Агент 1 и Агент 2 → один и тот же файл → КОНФЛИКТ

С worktrees:

Агент 1 → my-project-auth/   → своя копия файлов
Агент 2 → my-project-api/    → своя копия файлов
                              → Мерж потом

Как настроить worktrees для агентов:

# Создаём worktree для первого агента
git worktree add -b feature/auth ../my-project-auth main

# Создаём worktree для второго агента
git worktree add -b feature/api ../my-project-api main

# Создаём worktree для третьего агента
git worktree add -b feature/tests ../my-project-tests main

# Проверяем список всех worktrees
git worktree list

Запускаем агентов в worktrees:

# Терминал 1: Агент работает над аутентификацией
cd ../my-project-auth
claude --dangerously-skip-permissions
> Реализуй модуль аутентификации по SPEC.md

# Терминал 2: Агент работает над API
cd ../my-project-api
claude --dangerously-skip-permissions
> Реализуй API endpoints по SPEC.md

# Терминал 3: Агент работает над тестами
cd ../my-project-tests
claude --dangerously-skip-permissions
> Напиши тесты для всех модулей

Мерж результатов:

cd my-project

# Мержим ветку аутентификации
git merge feature/auth

# Мержим ветку API
git merge feature/api

# Мержим тесты
git merge feature/tests

# Если есть конфликты — просим Claude Code разрешить
claude
> Разреши все merge-конфликты. Код из обеих веток важен.

Очистка worktrees:

# Удаляем worktrees после мержа
git worktree remove ../my-project-auth
git worktree remove ../my-project-api
git worktree remove ../my-project-tests

# Удаляем мержнутые ветки
git branch -d feature/auth feature/api feature/tests

tmux: управление множеством терминалов

Когда у вас 5-10 агентов одновременно, открывать 10 окон терминала — неудобно. tmux решает эту проблему: все терминалы в одном окне.

tmux (Terminal MUltipleXer) — программа, которая позволяет создавать несколько терминалов в одном окне. Вы можете разделить экран на панели, переключаться между ними и видеть всё одновременно.

Установка tmux:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Запуск
tmux

Базовые команды tmux:

Все команды tmux начинаются с prefix — по умолчанию это Ctrl+b.

Действие	Команда
Новая панель справа	`Ctrl+b %`
Новая панель снизу	`Ctrl+b "`
Переключение панелей	`Ctrl+b стрелки`
Новое окно (вкладка)	`Ctrl+b c`
Следующее окно	`Ctrl+b n`
Предыдущее окно	`Ctrl+b p`
Закрыть панель	`Ctrl+d` или `exit`
Отключиться от сессии	`Ctrl+b d`
Вернуться к сессии	`tmux attach`

Пример: 4 агента в tmux

# Создаём сессию
tmux new-session -s agents

# Разделяем экран на 4 панели
# Ctrl+b %     (делим вертикально)
# Ctrl+b "     (делим горизонтально)
# Ctrl+b стрелка → (переходим в правую панель)
# Ctrl+b "     (делим горизонтально)

Результат:

┌───────────────────┬───────────────────┐
│                   │                   │
│  Агент 1: Auth    │  Агент 2: API     │
│  (worktree auth)  │  (worktree api)   │
│                   │                   │
├───────────────────┼───────────────────┤
│                   │                   │
│  Агент 3: Tests   │  Агент 4: Docs    │
│  (worktree tests) │  (worktree docs)  │
│                   │                   │
└───────────────────┴───────────────────┘

Скрипт: автоматическая настройка

#!/bin/bash
# setup_agents.sh — создаёт worktrees и tmux-сессию для параллельной работы

PROJECT_DIR="$(pwd)"
PROJECT_NAME="$(basename $PROJECT_DIR)"
SESSION_NAME="agents-$PROJECT_NAME"

# Создаём worktrees
echo "Создаю worktrees..."
git worktree add -b feature/auth "../${PROJECT_NAME}-auth" main
git worktree add -b feature/api "../${PROJECT_NAME}-api" main
git worktree add -b feature/tests "../${PROJECT_NAME}-tests" main

# Создаём tmux-сессию с 4 панелями
echo "Создаю tmux-сессию..."
tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_DIR"

# Панель 1: основная (уже создана)
tmux send-keys -t "$SESSION_NAME" "cd $PROJECT_DIR && claude" Enter

# Панель 2: auth
tmux split-window -h -t "$SESSION_NAME" -c "../${PROJECT_NAME}-auth"
tmux send-keys -t "$SESSION_NAME" "claude --dangerously-skip-permissions" Enter

# Панель 3: api
tmux split-window -v -t "$SESSION_NAME" -c "../${PROJECT_NAME}-api"
tmux send-keys -t "$SESSION_NAME" "claude --dangerously-skip-permissions" Enter

# Панель 4: tests
tmux select-pane -t "$SESSION_NAME:0.0"
tmux split-window -v -t "$SESSION_NAME" -c "../${PROJECT_NAME}-tests"
tmux send-keys -t "$SESSION_NAME" "claude --dangerously-skip-permissions" Enter

# Подключаемся к сессии
echo "Готово! Подключаюсь к tmux-сессии..."
tmux attach -t "$SESSION_NAME"

Worktrees + tmux + Agent Teams:

Все три инструмента отлично работают вместе:

Worktrees — каждый агент в своей изолированной копии, нет конфликтов файлов
tmux — все агенты видны на одном экране, быстрое переключение
Agent Teams — агенты общаются друг с другом и координируют работу

Инструменты для оркестрации агентов

Кроме встроенных функций Claude Code, сообщество создало мощные инструменты для управления армией агентов.

Gas Town — промышленная фабрика агентов

Gas Town — самый амбициозный оркестратор от Стива Йегге (Steve Yegge), ветерана Amazon и Google. Его идея: Claude Code — это не инструмент, а строительный блок. Настоящая продуктивность начинается, когда вы запускаете 20-30 агентов одновременно.

Gas Town использует специализированные роли, как настоящая команда:

Роль	Что делает
Mayor (Мэр)	Ваш главный собеседник. Координирует работу, распределяет задачи
Polecats (Рабочие)	Запускаются по запросу, делают конкретные задачи, создают Merge Requests
Refinery (Завод)	Решает проблему мержа — объединяет изменения от десятков рабочих в main
Witness (Наблюдатель)	Следит за рабочими, помогает застрявшим агентам
Deacon (Дьякон)	Демон-оркестратор, пингует всех и поддерживает работу системы
Dogs (Собаки)	Помощники дьякона: уборка веток, мелкие задачи
Crew (Экипаж)	Ваши личные агенты для интерактивной работы

Ключевые идеи Gas Town:

GUPP (Gastown Universal Propulsion Principle) — если у агента есть работа на крючке, он обязан её выполнить. Это решает проблему “агент остановился и ждёт”.
Beads — легковесный трекер задач, хранящийся прямо в git.
Molecules — цепочки задач (workflows), которые переживают перезапуск агента.
tmux — основной интерфейс. Все агенты живут в tmux-панелях.

Gas Town — инструмент для опытных пользователей. Он дорогой (десятки долларов в час на API), сложный и экспериментальный. Но он показывает, куда движется индустрия.

OpenSpec — разработка от спецификации

OpenSpec — лёгкий фреймворк, где спецификация первична, а код — следствие.

Идея OpenSpec:

Вы описываете что хотите в спецификации
Спецификация живёт в репозитории рядом с кодом
Каждое изменение сначала отражается в спецификации (spec delta), потом в коде
Ревью фокусируется на намерении (что хотели сделать), а не на реализации

OpenSpec работает не только с Claude Code, но и с Cursor, Windsurf, Copilot, Gemini CLI. Он генерирует файлы CLAUDE.md и .claude/commands/ для Claude Code.

Claude MPM — мульти-агентный проект-менеджер

Claude MPM — фреймворк с 47+ специализированными агентами и 44+ встроенными навыками. Готовые агенты для разных ролей: архитектор, разработчик, тестировщик, ревьюер.

cmux — параллельные агенты в изоляции

cmux — запускает Claude Code, Codex CLI, Gemini CLI и другие агенты одновременно, каждый в своём изолированном VS Code workspace. Полная изоляция без конфликтов.

Сравнение инструментов:

Инструмент	Сложность	Масштаб	Особенность
Agent Teams (встроенный)	Средняя	3-5 агентов	Общение между агентами, общий список задач
Gas Town	Очень высокая	20-30 агентов	Промышленная фабрика с ролями и workflows
OpenSpec	Низкая	Любой	Спецификация как единый источник правды
Claude MPM	Средняя	5-15 агентов	47+ готовых ролей и 44+ навыков
cmux	Низкая	3-5 агентов	Изолированные VS Code workspaces

Как выбрать:

Начинающий (1-3 агента) — Agent Teams или cmux
Продвинутый (3-10 агентов) — Claude MPM
Эксперт (10+ агентов) — Gas Town
Процесс-ориентированный (фокус на спецификации) — OpenSpec

Ограничения и подводные камни

1. Конфликты при параллельной работе — два агента одновременно редактируют один файл. Решение: разделяйте зоны ответственности. Один агент — один модуль. Используйте git worktrees.

2. Несогласованные интерфейсы — один агент создал get_user(id), а другой вызывает fetch_user(user_id). Решение: определите интерфейсы заранее в спецификации или в файле interfaces.py.

3. Дублирование кода — разные агенты пишут одну и ту же утилиту. Решение: архитектор создаёт общие модули (utils/, common/) перед тем как разработчики начнут работу.

4. Контекстные ограничения — каждый агент имеет свой контекст и не знает, что делают другие. Решение: используйте общие файлы (SPEC.md, CLAUDE.md, ARCHITECTURE.md).

5. Стоимость — много агентов = много API-вызовов = больше денег. Решение: используйте Haiku/быстрые модели для простых задач, Opus только для архитектурных решений.

Когда какой подход использовать

Подход	Сложность	Скорость	Когда использовать
1 агент	Низкая	Средняя	Маленькие задачи, прототипы
Несколько терминалов	Средняя	Быстрая	Проекты средней сложности
Bash-оркестратор	Средняя	Быстрая	Повторяемые процессы
Спецификация + конвейер	Высокая	Очень быстрая	Большие проекты, команды
Agent Teams	Средняя	Очень быстрая	Сложные задачи, ревью, отладка

Будущее: полностью автономные агенты

Сегодня: агент выполняет одну задачу по вашему промпту. Вы координируете работу между агентами. Вы проверяете результат.

Завтра (уже появляется): агент сам разбивает задачу на подзадачи, сам запускает тесты и исправляет ошибки, сам просит уточнений.

Послезавтра: вы пишете только бизнес-требования, армия агентов сама проектирует, кодит, тестирует и деплоит. Вы ревьюите и одобряете результат.

Ключевой навык будущего — умение писать хорошие спецификации и умение оценивать результат. Это уже важнее, чем умение писать код руками.

Итоги модуля

Армия агентов — это запуск нескольких Claude Code для параллельной работы
5 встроенных способов: ручные терминалы, bash-оркестратор, субагенты в IDE, спецификация как контракт, Agent Teams
Agent Teams — встроенная функция Claude Code с общим списком задач и обменом сообщениями между агентами
Git worktrees решают проблему конфликтов: каждый агент в своей изолированной копии
tmux позволяет видеть и управлять десятками агентов на одном экране
Внешние инструменты: Gas Town (промышленная фабрика), OpenSpec (спецификация-первая), Claude MPM (47+ ролей), cmux
Ключ к успеху — хорошая спецификация и чёткое разделение ответственности
Паттерны: конвейер, параллельные специалисты, генерация + проверка
Будущее — полностью автономные агенты, которым нужна только спецификация

Модуль 8: MCP и Agent Skills — расширяем возможности Claude Code

Введение

Claude Code сам по себе умеет многое: читать файлы, писать код, запускать команды. Но его настоящая сила раскрывается, когда вы подключаете внешние инструменты. В этом модуле мы разберём:

MCP (Model Context Protocol) — протокол для подключения Claude Code к внешним сервисам: базам данных, GitHub, Jira, Sentry и сотням других
Agent Skills — модульные навыки, которые делают Claude специалистом в конкретной области

Часть 1: MCP — Model Context Protocol

MCP — это открытый стандарт для подключения AI к внешним инструментам. Проще говоря, MCP позволяет Claude Code работать не только с файлами на вашем компьютере, но и с любыми внешними сервисами.

Документация: code.claude.com/docs/en/mcp

Что можно делать с MCP:

Работать с задачами из трекеров: “Реализуй фичу из Jira-тикета ENG-4521 и создай PR на GitHub”
Анализировать мониторинг: “Проверь Sentry — какие ошибки появились после последнего деплоя?”
Делать запросы к базам данных: “Найди в PostgreSQL 10 пользователей, которые зарегистрировались вчера”
Работать с дизайном: “Обнови шаблон email по новым макетам из Figma”
Автоматизировать рутину: “Создай черновики писем в Gmail для этих 10 пользователей”

Архитектура MCP:

Claude Code
    ├── MCP Server: GitHub    → создание PR, ревью, issues
    ├── MCP Server: Sentry    → мониторинг ошибок
    ├── MCP Server: PostgreSQL → запросы к базе данных
    ├── MCP Server: Notion    → документация
    └── MCP Server: Slack     → уведомления

Каждый MCP-сервер — это маленькая программа, которая “переводит” запросы Claude Code в команды конкретного сервиса.

Типы MCP-серверов:

Тип	Как работает	Когда использовать
HTTP (remote)	Подключается к облачному сервису по URL	GitHub, Sentry, Notion — облачные сервисы
SSE (remote)	Устаревший вариант HTTP	Старые серверы, которые ещё не обновились
stdio (local)	Запускается как процесс на вашей машине	Базы данных, локальные инструменты

Установка MCP-серверов:

HTTP-сервер (облачный):

# Подключить GitHub
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Подключить Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Подключить Sentry
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Stdio-сервер (локальный):

# Подключить PostgreSQL
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

# Подключить Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Управление серверами:

# Посмотреть все подключённые серверы
claude mcp list

# Подробности о конкретном сервере
claude mcp get github

# Удалить сервер
claude mcp remove github

# Внутри Claude Code — статус серверов
/mcp

Популярные MCP-серверы:

Сервер	Что делает	Команда установки
GitHub	PR, issues, ревью кода	`claude mcp add --transport http github https://api.githubcopilot.com/mcp/`
Sentry	Мониторинг ошибок	`claude mcp add --transport http sentry https://mcp.sentry.dev/mcp`
Notion	Документация, wiki	`claude mcp add --transport http notion https://mcp.notion.com/mcp`
PostgreSQL	Запросы к базе данных	`claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "..."`
Slack	Сообщения и каналы	`claude mcp add --transport http slack https://mcp.slack.com/mcp`

Полный список: github.com/modelcontextprotocol/servers

Аутентификация:

Многие облачные MCP-серверы требуют аутентификацию. Claude Code поддерживает OAuth 2.0:

# 1. Добавьте сервер
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. Внутри Claude Code — авторизуйтесь
> /mcp
# Выберите "Authenticate" для нужного сервера
# Откроется браузер для входа

Для серверов с API-ключами:

# Через заголовок авторизации
claude mcp add --transport http my-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Области видимости (Scopes):

MCP-серверы можно настроить на разных уровнях:

Scope	Где хранится	Кто видит	Когда использовать
local (по умолчанию)	`~/.claude.json`	Только вы, только этот проект	Личные серверы, секреты
project	`.mcp.json` в проекте	Вся команда (через git)	Общие инструменты команды
user	`~/.claude.json`	Только вы, все проекты	Личные утилиты для всех проектов

# Добавить сервер для всей команды (project scope)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

Файл .mcp.json можно закоммитить в git, и все члены команды получат доступ к тем же серверам:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
      "env": {}
    }
  }
}

Обратите внимание на ${DATABASE_URL} — Claude Code поддерживает переменные окружения в конфигурации. Каждый разработчик может задать свои значения.

Практический пример: отладка с Sentry и GitHub

> Подключись к Sentry. Какие новые ошибки появились за последние 24 часа?

Claude Code (через MCP):
"Найдено 3 новых ошибки:
1. TypeError в billing/process.py строка 45 — 127 случаев
2. ConnectionError в api/external.py строка 89 — 34 случая
3. ValidationError в auth/login.py строка 23 — 12 случаев"

> Покажи стектрейс для первой ошибки и исправь её

Claude Code:
1. Получает стектрейс из Sentry
2. Открывает billing/process.py
3. Находит и исправляет баг
4. Запускает тесты

> Создай PR на GitHub с исправлением

Claude Code (через MCP):
1. Создаёт ветку fix/billing-typeerror
2. Коммитит исправление
3. Создаёт PR с описанием бага и ссылкой на Sentry

Весь цикл — от обнаружения ошибки до создания PR — занимает несколько минут.

Практический пример: запрос к базе данных

> Сколько новых пользователей зарегистрировалось за последнюю неделю?
  Разбей по дням. Покажи также из каких стран они приходят.

Claude Code (через MCP к PostgreSQL):
"Новые регистрации за последнюю неделю:

| Дата       | Кол-во | Топ-3 страны        |
|------------|--------|---------------------|
| 2025-02-10 | 145    | US, DE, BR          |
| 2025-02-11 | 132    | US, UK, FR          |
| ...

Всего: 987 новых пользователей. Рост на 12% по сравнению с прошлой неделей."

MCP-ресурсы через @-упоминания:

MCP-серверы могут предоставлять ресурсы, которые можно упоминать через @:

> Проанализируй @github:issue://123 и предложи решение

> Сравни @postgres:schema://users с @docs:file://database/user-model

MCP Tool Search:

Когда у вас подключено много MCP-серверов (десятки), все их инструменты могут съесть контекстное окно. Claude Code решает это с помощью Tool Search:

Вместо загрузки всех инструментов сразу, Claude Code ищет нужные по запросу
Включается автоматически, когда инструменты занимают больше 10% контекста

# Настроить порог автоматического включения (5% контекста)
ENABLE_TOOL_SEARCH=auto:5 claude

# Всегда включён
ENABLE_TOOL_SEARCH=true claude

Часть 2: Agent Skills — модульные навыки

Agent Skills — это модульные пакеты инструкций, которые превращают Claude из универсального помощника в специалиста по конкретной теме.

Представьте, что вы наняли нового сотрудника. Вы даёте ему папку с инструкциями: “Вот как у нас устроена работа с базой данных. Вот шаблоны. Вот скрипты.” Skills работают так же — это “папка с инструкциями” для Claude.

Документация: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

Зачем нужны Skills:

Без Skills	С Skills
Каждый раз объясняете Claude как работать с PDF	Claude сам знает — у него есть PDF-skill
Повторяете одни и те же инструкции	Написали инструкцию один раз — используете всегда
Claude даёт общие ответы	Claude даёт ответы с учётом ваших правил и процессов

Встроенные Skills:

Skill	Что делает
PowerPoint (pptx)	Создание презентаций, редактирование слайдов
Excel (xlsx)	Создание таблиц, анализ данных, графики
Word (docx)	Создание и редактирование документов
PDF (pdf)	Генерация PDF-отчётов

Три уровня загрузки:

Skills используют принцип прогрессивной загрузки — Claude загружает только то, что нужно прямо сейчас.

Уровень	Когда загружается	Стоимость	Содержимое
1. Метаданные	Всегда, при запуске	~100 токенов	Имя и описание
2. Инструкции	Когда skill активирован	До 5K токенов	SKILL.md
3. Ресурсы	По необходимости	Без ограничений	Файлы, скрипты, справочники

Создание своих Skills для Claude Code:

В Claude Code skills — это просто папки с файлом SKILL.md.

.claude/skills/my-skill/
└── SKILL.md

Или в домашней папке (для всех проектов):

~/.claude/skills/my-skill/
└── SKILL.md

Пример: Skill для работы с базой данных

---
name: company-database
description: Работа с базой данных компании. Используй при запросах
  к базе данных, создании отчётов или анализе данных пользователей.
---

# Работа с базой данных компании

## Подключение

Используй SQLAlchemy с переменной окружения DATABASE_URL:

## Основные таблицы

| Таблица | Описание | Ключевые поля |
|---------|----------|---------------|
| users | Пользователи | id, email, name, created_at |
| orders | Заказы | id, user_id, total, status |
| products | Товары | id, name, price, category |

## Правила

- НИКОГДА не делай DELETE или UPDATE без WHERE
- Всегда используй LIMIT для больших таблиц
- Для отчётов используй read-only подключение
- Даты всегда в формате ISO 8601

Пример: Skill для код-ревью

---
name: code-review
description: Проводит код-ревью по стандартам компании.
  Используй при ревью кода, проверке PR или анализе качества.
---

# Код-ревью по стандартам компании

## Чеклист ревью

### Обязательно проверить:
1. **Type hints** — все функции должны иметь типы
2. **Docstrings** — все публичные функции задокументированы
3. **Тесты** — есть тесты для нового кода
4. **Безопасность** — нет SQL injection, XSS, хардкода секретов
5. **Логирование** — используется logging, не print

### Формат комментариев:
- Критично: блокирует мерж
- Важно: желательно исправить
- Мелочь: можно исправить позже
- Совет: необязательно, но улучшит код

Пример: Skill для деплоя

---
name: deployment
description: Управление деплоем приложения. Используй при развёртывании,
  настройке CI/CD или работе с Docker/Kubernetes.
---

# Деплой приложения

## Окружения

| Окружение | URL | Ветка |
|-----------|-----|-------|
| dev | dev.app.com | develop |
| staging | staging.app.com | release/* |
| production | app.com | main |

## Процесс деплоя

1. Убедись что все тесты проходят
2. Создай тег версии: git tag v1.X.Y
3. Запусти деплой: make deploy ENV=staging
4. Проверь логи: make logs ENV=staging
5. Если ОК — деплой в production

Безопасность Skills:

Skills — мощный инструмент. Используйте только skills из доверенных источников:

Skills, которые вы написали сами
Skills от Anthropic (встроенные)
Skills от вашей команды (через git)

Не устанавливайте skills из неизвестных источников — они могут содержать вредоносные инструкции.

Часть 3: MCP + Skills + Agent Teams = суперсила

Самые мощные сценарии — это когда вы объединяете MCP, Skills и Agent Teams:

Спецификация проекта
     │
     ├── Agent Team Lead (координация)
     │    ├── MCP: GitHub (PR, issues)
     │    ├── MCP: Jira (задачи)
     │    └── Skill: project-management
     │
     ├── Teammate: Backend Dev
     │    ├── MCP: PostgreSQL (запросы к БД)
     │    └── Skill: code-review
     │
     ├── Teammate: QA
     │    ├── MCP: Sentry (мониторинг)
     │    └── Skill: testing-standards
     │
     └── Teammate: DevOps
          ├── MCP: AWS (инфраструктура)
          └── Skill: deployment

Пример рабочего дня с MCP + Skills:

Утро — проверка ошибок:

> Проверь Sentry за ночь. Есть новые ошибки?
  (MCP: Sentry → находит ошибки)

> Исправь критичную ошибку и создай PR
  (MCP: GitHub → создаёт PR с фиксом)

День — работа над фичей:

> Какие задачи назначены мне в Jira?
  (MCP: Jira → показывает задачи)

> Реализуй задачу ENG-4521.
  Посмотри схему базы данных перед началом.
  (MCP: PostgreSQL → показывает схему)
  (Skill: code-review → проверяет код по стандартам)

Вечер — деплой:

> Всё готово. Задеплой на staging и проверь логи.
  (Skill: deployment → следует процессу деплоя)
  (MCP: Sentry → проверяет нет ли новых ошибок)

Настройка для команды:

Создайте .mcp.json в корне проекта и закоммитьте в git. Добавьте skills в папку .claude/skills/:

my-project/
├── .mcp.json                    # MCP-серверы для команды
├── .claude/
│   └── skills/
│       ├── code-review/
│       │   └── SKILL.md         # Стандарты ревью
│       ├── database/
│       │   └── SKILL.md         # Правила работы с БД
│       └── deployment/
│           └── SKILL.md         # Процесс деплоя
├── CLAUDE.md                    # Общие правила проекта
└── src/
    └── ...

Каждый член команды получит одинаковые инструменты и правила при запуске Claude Code в проекте.

Часть 4: Hooks — автоматизация без AI

Документация: code.claude.com/docs/en/hooks

Hooks — это обычные скрипты, которые запускаются автоматически на определённые события в Claude Code. В отличие от инструкций в CLAUDE.md (которые Claude может проигнорировать), хуки гарантированно выполняются каждый раз.

Когда использовать Hooks:

Запустить линтер после каждого редактирования файла
Запретить изменения в определённых папках
Отформатировать код после правок
Отправить уведомление когда Claude трогает критичные файлы
Запустить проверку безопасности перед коммитом

Пример: автоформатирование после правок

Claude может сам написать хук. Попросите:

> Напиши хук который запускает eslint --fix после каждого
  редактирования файла

Или настройте вручную в .claude/settings.json:

{
  "hooks": {
    "afterFileEdit": [
      {
        "command": "npx eslint --fix $FILE",
        "description": "Auto-fix lint errors"
      }
    ]
  }
}

Типы событий:

Событие	Когда срабатывает
`afterFileEdit`	После редактирования файла
`beforeCommand`	Перед запуском команды
`afterCommand`	После запуска команды
`onSessionStart`	При начале сессии
`onSessionEnd`	При завершении сессии
`onCompact`	При сжатии контекста

Главное отличие от CLAUDE.md: хуки — детерминированные. Они не используют AI, просто запускают скрипт. Это гарантия, а не рекомендация.

Часть 5: Plugins — пакеты расширений

Документация: code.claude.com/docs/en/plugins

Plugins — это пакеты, которые объединяют Skills, Hooks, субагентов и MCP-серверы в одну устанавливаемую единицу. Думайте о них как о расширениях для браузера, только для Claude Code.

Зачем нужны:

Переиспользование — одна настройка для нескольких проектов
Распространение — поделитесь своими инструментами с командой
Маркетплейсы — установите готовые расширения от сообщества

Как установить:

/plugin    # Открыть маркетплейс и выбрать плагин

Что внутри плагина:

my-plugin/
├── skills/
│   └── review/SKILL.md       # Чек-лист ревью
├── hooks/
│   └── settings.json          # Хуки для автоформатирования
├── agents/
│   └── security-reviewer.md   # Субагент для проверки безопасности
└── mcp/
    └── config.json            # MCP-серверы

Часть 6: Как всё работает вместе

Карта расширений:

Расширение	Что делает	Когда загружается	Нагрузка на контекст
CLAUDE.md	Постоянные инструкции	Начало каждой сессии	Каждый запрос
Skills	Знания и воркфлоу	По требованию	Низкая до использования
MCP	Внешние сервисы	Начало сессии	Каждый запрос
Субагенты	Изолированные задачи	По запуску	Изолировано
Agent Teams	Координация агентов	По запуску	Изолировано
Hooks	Автоматические скрипты	На событие	Ноль
Plugins	Пакеты расширений	При установке	Зависит от содержимого

Принцип: чем реже — тем лучше

Каждое расширение занимает место в контексте. Порядок приоритета:

CLAUDE.md — для правил которые нужны ВСЕГДА (до ~500 строк)
Skills — для справочных материалов и воркфлоу (загружаются по требованию)
MCP — для подключения к внешним сервисам
Hooks — для автоматизации (нулевая нагрузка на контекст)

Комбинации расширений:

Комбинация	Как работает	Пример
Skill + MCP	MCP даёт подключение, Skill учит его использовать	MCP подключает БД, Skill описывает схему
Skill + субагент	Skill запускает субагентов для параллельной работы	`/review` запускает 3 субагента: безопасность, производительность, стиль
CLAUDE.md + Skills	CLAUDE.md — правила всегда, Skills — справочники по требованию	CLAUDE.md: “следуй API конвенциям”, Skill: полный гайд по API
Hook + MCP	Hook запускает внешние действия через MCP	Хук отправляет в Slack когда Claude трогает критичные файлы

Итоги модуля

MCP — открытый протокол для подключения к внешним сервисам (GitHub, Sentry, PostgreSQL, Notion, Slack)
Три типа серверов: HTTP, SSE (устаревший), stdio (локальные)
Три области видимости: local, project, user
Agent Skills — модульные пакеты инструкций с прогрессивной загрузкой
Встроенные skills: PowerPoint, Excel, Word, PDF
Свои skills — папка с файлом SKILL.md
Hooks — детерминированные скрипты, нулевая нагрузка на контекст
Plugins — пакеты расширений (Skills + Hooks + субагенты + MCP)
MCP + Skills + Hooks + Agent Teams = полноценная автоматизация рабочего процесса

Модуль 9: Лучшие практики работы с Claude Code

Основано на: code.claude.com/docs/en/best-practices

Главное правило

Большинство лучших практик сводятся к одному: контекстное окно заполняется быстро, и качество падает по мере заполнения.

Контекстное окно хранит всю вашу беседу: сообщения, содержимое файлов, вывод команд. Одна сессия отладки может съесть десятки тысяч токенов. Когда окно заполнено, Claude начинает “забывать” ранние инструкции и ошибаться чаще.

Все советы ниже — это способы эффективно управлять контекстом.

1. Дайте Claude способ проверить свою работу

Это самый важный совет. Claude работает гораздо лучше, когда может сам проверить результат: запустить тесты, сравнить скриншоты, проверить вывод.

Без проверки вы — единственный фидбек. С проверкой — Claude ловит свои ошибки сам.

Подход	Плохо	Хорошо
Критерии проверки	”напиши функцию валидации email"	"напиши validateEmail. Тесты: user@example.com → true, invalid → false. Запусти тесты после реализации”
UI изменения	”сделай дашборд красивее"	"[вставить скриншот] реализуй этот дизайн. Сделай скриншот результата и сравни с оригиналом”
Исправление ошибок	”билд падает"	"билд падает с ошибкой: [ошибка]. Исправь и проверь что билд проходит. Найди причину, а не подави ошибку”

2. Сначала исследуй, потом планируй, потом кодь

Если Claude сразу бросается кодить — он может решить не ту проблему. Разделяйте работу на фазы:

Фаза 1: Исследование (Plan Mode)

Переключитесь в Plan Mode (Shift+Tab дважды). Claude только читает файлы и отвечает на вопросы, ничего не меняя.

> Прочитай src/auth/ и разберись как мы работаем с сессиями.

Фаза 2: Планирование

> Хочу добавить Google OAuth. Какие файлы нужно менять?
  Какой будет flow? Составь план.

Фаза 3: Реализация (Normal Mode)

Переключитесь обратно и дайте Claude кодить по плану:

> Реализуй OAuth flow по твоему плану.
  Напиши тесты для callback handler, запусти и исправь ошибки.

Фаза 4: Коммит

> Закоммить с хорошим описанием и создай PR.

Когда можно пропустить планирование: если задача простая (исправить опечатку, добавить лог, переименовать переменную) — просто попросите Claude сделать. Планирование нужно для неясных задач, изменений в нескольких файлах или незнакомом коде.

3. Будьте конкретны в промптах

Чем точнее промпт — тем меньше итераций.

Стратегия	Плохо	Хорошо
Ограничьте задачу	”добавь тесты для foo.py"	"напиши тест для foo.py покрывающий случай когда пользователь не залогинен. Без моков”
Укажите источники	”почему у ExecutionFactory такой странный API?"	"посмотри git history ExecutionFactory и объясни как его API пришёл к текущему виду”
Сошлитесь на паттерны	”добавь виджет календаря"	"посмотри как сделаны существующие виджеты. HotDogWidget.php — хороший пример. Сделай по тому же паттерну”
Опишите симптом	”исправь баг логина"	"логин падает после таймаута сессии. Проверь src/auth/, особенно обновление токена. Напиши тест что воспроизводит баг, потом исправь”

Давайте богатый контекст:

@файл — ссылайтесь на файлы через @, Claude прочитает их
Скриншоты — вставляйте картинки прямо в промпт (drag & drop)
URL — давайте ссылки на документацию
Pipe — cat error.log | claude для отправки содержимого файлов

4. Управляйте сессией

Прерывайте и корректируйте рано:

Не ждите пока Claude закончит, если видите что идёт не туда:

Esc — остановить Claude. Контекст сохранён, можно перенаправить
Esc + Esc или /rewind — откатиться к предыдущему состоянию (и код, и беседу)
“Откати это” — Claude отменит свои изменения
/clear — полный сброс контекста для новой задачи

Правило двух попыток: если вы поправили Claude дважды по одной теме и он всё ещё делает не так — контекст засорён неудачными попытками. Сделайте /clear и начните заново с лучшим промптом.

Управляйте контекстом агрессивно:

/clear          — сброс между задачами
/compact        — сжать контекст, сохранив важное
/compact focus on the API changes   — сжать с фокусом
/context        — посмотреть что занимает место

Используйте субагентов для исследований:

Субагенты работают в отдельном контексте и возвращают только краткий результат:

> Используй субагента чтобы изучить как наша система аутентификации
  обрабатывает обновление токенов и есть ли готовые OAuth утилиты.

Субагент прочитает десятки файлов, но ваш основной контекст получит только резюме. Это один из самых мощных инструментов для сохранения контекста.

Возобновляйте разговоры:

claude --continue    # Продолжить последний разговор
claude --resume      # Выбрать из недавних

Используйте /rename чтобы давать сессиям понятные имена: “oauth-миграция”, “отладка-утечки-памяти”.

5. Настройте окружение

Напишите хороший CLAUDE.md:

Запустите /init — Claude создаст начальный CLAUDE.md на основе вашего проекта.

Что включать:

Команды для сборки и тестов, которые Claude не угадает
Правила стиля кода, отличающиеся от стандартных
Инструкции по тестированию
Архитектурные решения проекта
Переменные окружения

Что НЕ включать:

То, что Claude поймёт из кода сам
Стандартные конвенции языка
Подробную API-документацию (лучше ссылку)
Описание каждого файла

Держите CLAUDE.md коротким — до ~500 строк. Если больше, Claude начинает игнорировать правила. Переносите справочные материалы в Skills.

Используйте CLI-инструменты:

Claude отлично работает с CLI:

gh (GitHub CLI) — создание PR, issues, ревью
aws, gcloud — работа с облаком
sentry-cli — мониторинг ошибок

> Используй 'gh issue list' чтобы найти открытые баги
  и исправь самый критичный

Claude может и учить новые CLI-инструменты на лету:

> Используй 'foo-tool --help' чтобы разобраться в инструменте,
  потом реши задачу A с его помощью

Настройте разрешения:

Используйте /permissions чтобы разрешить безопасные команды раз и навсегда:

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(ruff check *)"
    ]
  }
}

6. Масштабируйте работу

Headless-режим для автоматизации:

# Одноразовый запрос
claude -p "объясни что делает этот проект"

# Структурированный вывод для скриптов
claude -p "перечисли все API endpoints" --output-format json

# Стриминг для обработки в реальном времени
claude -p "проанализируй лог-файл" --output-format stream-json

Паттерн Writer/Reviewer:

Используйте две сессии — одна пишет код, другая ревьюит:

Сессия A (Писатель)	Сессия B (Ревьюер)
“Реализуй rate limiter для API"
	"Проверь реализацию rate limiter в src/middleware/. Найди edge cases и race conditions"
"Вот фидбек: [вывод B]. Исправь”

Свежий контекст ревьюера не предвзят — он не привязан к коду, который сам написал.

Fan-out для массовых операций:

# Миграция 2000 файлов
for file in $(cat files.txt); do
  claude -p "Мигрируй $file с React на Vue. Верни OK или FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

7. Типичные ошибки

“Сессия-свалка” — начали с одной задачи, потом спросили про другое, потом вернулись к первой. Контекст засорён. Решение: /clear между несвязанными задачами.

“Бесконечные правки” — Claude делает неправильно, вы поправляете, опять неправильно. Контекст отравлен неудачными попытками. Решение: после двух неудач — /clear и новый, лучший промпт.

“Раздутый CLAUDE.md” — файл на 1000 строк. Claude игнорирует половину. Решение: безжалостно режьте. Если Claude и так делает правильно без инструкции — удалите её.

“Бесконечное исследование” — вы попросили Claude “разобраться” без ограничений. Он прочитал сотни файлов и забил контекст. Решение: ограничивайте scope или используйте субагентов.

“Доверяй, но не проверяй” — Claude написал код, который выглядит правильно, но не обрабатывает edge cases. Решение: всегда давайте способ проверки (тесты, скрипты). Если не можете проверить — не деплойте.

8. Развивайте интуицию

Эти советы — отправные точки, не догмы. Иногда нужно дать контексту накапливаться, потому что вы глубоко в сложной проблеме. Иногда нечёткий промпт — именно то что нужно, чтобы увидеть как Claude интерпретирует задачу.

Обращайте внимание на что работает. Когда Claude выдаёт отличный результат — замечайте что вы сделали: структуру промпта, контекст, режим. Когда Claude буксует — спросите себя почему. Контекст зашумлён? Промпт слишком размытый? Задача слишком большая для одного прохода?

Итоги модуля

Самое важное — дайте Claude способ проверить свою работу (тесты, скриншоты, критерии)
Контекст — главный ресурс. Используйте /clear, /compact, субагентов для управления
Фазы работы: исследование → планирование → реализация → коммит
Конкретные промпты = меньше итераций. Указывайте файлы, паттерны, критерии
CLAUDE.md — коротко и по делу, до 500 строк
Прерывайте рано — Esc, /rewind, /clear вместо длинных сессий
Масштабируйте: headless-режим, writer/reviewer, fan-out для массовых задач

Модуль 10: Claude Code с другими моделями

Ссылки: Claude Code Router | OpenRouter | Официальные провайдеры

Зачем использовать другие модели

Claude Code по умолчанию работает только с моделями Anthropic (Claude). Но есть ситуации, когда хочется использовать другие модели:

Бесплатные модели — для простых задач не обязательно платить
Лимиты подписки — закончились токены в 2 часа ночи во время дебага
Приватность — код не должен покидать ваш компьютер
Эксперименты — попробовать как GPT, Gemini или Qwen справляются с теми же задачами
Оптимизация затрат — простые задачи на дешёвой модели, сложные на мощной

Как это работает: ANTHROPIC_BASE_URL

Claude Code использует API для связи с моделью. Ключевой трюк: можно подменить URL, на который Claude Code отправляет запросы:

export ANTHROPIC_BASE_URL="https://другой-сервер.com/api"
export ANTHROPIC_AUTH_TOKEN="ваш-ключ"
export ANTHROPIC_API_KEY=""  # обязательно очистить, чтобы Claude Code не пытался использовать старый ключ Anthropic

Claude Code думает, что общается с Anthropic, но на самом деле запросы идут на другой сервер. Для этого тот сервер должен поддерживать Anthropic Messages API.

Способ 1: OpenRouter — универсальный шлюз

OpenRouter — это единый API с доступом к 400+ моделям от 60+ провайдеров. Одна регистрация, один ключ, сотни моделей.

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="or_ваш_ключ"
export ANTHROPIC_API_KEY=""  # Важно: оставить пустым, чтобы не было конфликта

claude --model openai/gpt-oss-20b

Важно: если вы ранее логинились в Claude Code через Anthropic, выполните /logout перед использованием OpenRouter. Также не используйте .env файл — Claude Code его не читает. Переменные нужно добавить в ~/.bashrc или ~/.zshrc.

Бесплатные аккаунты: OpenRouter даёт доступ к бесплатным моделям без пополнения баланса, но с лимитом — около 50 запросов в день к бесплатным моделям. Для активной работы рекомендуется пополнить баланс хотя бы на $5.

Бесплатные модели:

Модель	Описание	Контекст
`openai/gpt-oss-20b:free`	Open-weight модель от OpenAI	128K
`qwen/qwen3-coder:free`	Оптимизирована для кода	262K
`deepseek/deepseek-r1:free`	Сильные рассуждения, хороша для отладки	128K

Эти модели стоят $0. Для простых задач (объяснение кода, форматирование, генерация документации) их хватает.

Через OpenRouter доступны и премиум-модели: GPT-4o, Gemini, Claude (иногда с лучшей доступностью чем напрямую). Оплата по факту использования.

Способ 2: Claude Code Router — умный прокси

Claude Code Router — это прокси, который стоит между Claude Code и провайдерами моделей. Его главная фича — умная маршрутизация: разные задачи отправляются на разные модели.

npm install -g @musistudio/claude-code-router

Настройка .claude-code-router/config.json:

{
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "${OPENROUTER_API_KEY}",
      "models": ["qwen/qwen3-coder:free", "openai/gpt-oss-20b:free"]
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3:4b", "deepseek-coder:6.7b"]
    }
  ]
}

Запуск:

# Запустить роутер
ccr start

# Открыть веб-интерфейс для настройки
ccr ui

Умная маршрутизация:

Категория	Какую модель использовать	Зачем
Default	Qwen3 Coder (бесплатная)	Простые запросы: объяснения, форматирование
Think	DeepSeek R1	Сложные рассуждения, отладка
Long Context	Модель с большим контекстом	Работа с большими кодовыми базами
Background	Дешёвая/быстрая модель	Фоновые задачи

Итог: “отформатируй JSON” идёт на бесплатную модель, а “спроектируй микросервисную архитектуру” — на Claude или GPT.

Способ 3: Ollama — модели на своём компьютере (бесплатно)

Что такое Ollama

Ollama — это бесплатный инструмент для запуска больших языковых моделей (LLM) локально на вашем компьютере. По сути, это «Docker для LLM»: вы одной командой скачиваете модель и сразу начинаете с ней работать. Ollama построен на базе llama.cpp и оптимизирован для работы на обычных компьютерах — без дорогих серверов и облачных подписок.

Ключевые особенности:

Полностью бесплатно — нет платы за токены, подписок, лимитов
Приватность — код и данные никогда не покидают ваш компьютер
Работа офлайн — после скачивания модели интернет не нужен
Простой CLI — ollama pull, ollama run, ollama launch — всё интуитивно
OpenAI-совместимый API — работает с любыми инструментами, включая Claude Code
GPU-ускорение — поддержка Apple Silicon (Metal), NVIDIA (CUDA) и AMD (ROCm)
Библиотека моделей — доступ к сотням open-source моделей через ollama.com/library

Начиная с версии 0.14.0, Ollama поддерживает Anthropic Messages API, что делает интеграцию с Claude Code нативной — не нужен промежуточный прокси.

Установка

# macOS (через Homebrew)
brew install ollama

# macOS / Linux (универсальный способ)
curl -fsSL https://ollama.com/install.sh | sh

# Или скачайте приложение с ollama.com

Быстрый старт: ollama launch

Самый простой способ — команда ollama launch, которая автоматически настраивает переменные окружения и запускает Claude Code:

# Скачать модель и запустить Claude Code одной командой
ollama launch claude

# Или сначала настроить, потом запустить
ollama launch claude --config

Команда ollama launch сама установит нужные переменные окружения — не нужно ничего настраивать вручную.

Ручная настройка

Если вы хотите контролировать процесс вручную:

# Скачать модели для кода
ollama pull qwen3-coder
ollama pull gpt-oss:20b
ollama pull glm-4.7

# Подключение к Claude Code
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"

# Запустить Claude Code с выбранной моделью
claude --model qwen3-coder

Модель	Размер	Для чего	Мин. RAM
`qwen3-coder`	~30B	Лучшая для кода, длинный контекст (262K)	32 GB
`gpt-oss:20b`	20B	Open-weight от OpenAI, хороший баланс	16 GB
`glm-4.7`	30B MoE (3B active)	Нативный tool calling, быстрая	32 GB
`gpt-oss:120b`	120B	Максимальное качество, нужно мощное железо	64+ GB

Когда это полезно

Приватный код — данные клиента, внутренний код компании, NDA-проекты
Без интернета — работа в самолёте, в изолированной среде, на закрытых серверах
Без лимитов — запускайте сколько угодно, ограничение только ваше железо
Без затрат — $0 навсегда, платите только за электричество
Эксперименты — попробовать новые open-source модели сразу после выхода

Требования к железу

Размер модели	RAM	GPU	Скорость
4B параметров	8 GB	Не обязательно	Быстрая
7–20B параметров	16–32 GB	Желательно	Средняя
30B+ параметров	32+ GB	Нужно	Медленная без GPU

Честное предупреждение о скорости: локальные модели работают значительно медленнее облачных API. На MacBook Pro с M1 Max (64 GB RAM) простой запрос может занимать 30–60 секунд, а работа с файлами — до 2 минут. Для комфортной работы рекомендуется Apple Silicon с 32+ GB unified memory или ПК с NVIDIA GPU.

Способ 4: LiteLLM — прокси для смешанных конфигураций

LiteLLM — прокси, который позволяет переключаться между Anthropic, OpenAI, Ollama и десятками других провайдеров через единый API.

model_list:
  - model_name: gpt-oss-20b
    litellm_params:
      model: openai/gpt-oss-20b
      api_key: os.environ/OPENROUTER_KEY
  - model_name: local-coder
    litellm_params:
      model: ollama/qwen3:4b
      api_base: http://localhost:11434
  - model_name: claude-sonnet
    litellm_params:
      model: claude-sonnet-4-5-20250929
      api_key: os.environ/ANTHROPIC_API_KEY

# Запустить прокси
litellm --config litellm_config.yaml

# Подключить Claude Code
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="litellm_master"
claude --model gpt-oss-20b

LiteLLM полезен когда у вас несколько провайдеров и вы хотите единую точку входа с логированием затрат и балансировкой нагрузки.

Способ 5: Официальные облачные провайдеры

Anthropic официально поддерживает запуск Claude Code через облачных провайдеров. Это те же модели Claude, но оплата через вашего облачного провайдера:

Amazon Bedrock:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

Google Vertex AI:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

Microsoft Azure Foundry:

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key

Это полезно для корпоративных сценариев: биллинг через существующие контракты с AWS/GCP/Azure, соответствие политикам безопасности, контроль доступа через IAM.

Честное предупреждение: другие модели работают хуже

Это важно знать перед тем, как вы начнёте экспериментировать.

Почему Claude Code лучше работает с Claude:

Промпты оптимизированы для Claude — Anthropic точно знает как их модели реагируют на инструкции
Tool calling — Claude обучен работать с инструментами (редактирование файлов, git, bash). Другие модели могут это делать плохо
Модель обучена для агентной среды — Claude тренировали для многошагового выполнения задач

Типичные проблемы с другими моделями:

Проблема	Пример
Не вызывает инструменты	Модель пишет текст вместо того чтобы отредактировать файл
Генерирует мусор	Пустые строки и пробелы вместо кода
Игнорирует контекст	Не читает файлы проекта, отвечает “вообще”
Ломает формат	Ответ не парсится Claude Code

Что работает, а что нет:

Задача	С другими моделями	Рекомендация
Объяснить код	Хорошо	Qwen, DeepSeek, GPT — справляются
Ответить на вопрос	Хорошо	Любая модель
Документация	Хорошо	Бесплатные модели подходят
Редактирование файлов	Плохо	Нужна модель с tool calling
Запуск команд	Плохо	Нужна модель с tool calling
Сложные многошаговые задачи	Плохо	Используйте Claude

Практический совет: используйте другие модели для чтения и анализа, а Claude — для действий (редактирование, запуск, git).

Сравнение подходов

Подход	Сложность	Стоимость	Приватность	Качество
OpenRouter	Простой	От $0 (бесплатные модели)	Средняя	Зависит от модели
Claude Code Router	Средний	От $0	Средняя	Умная маршрутизация
Ollama	Простой (`ollama launch`)	$0 (нужно железо)	Максимальная	Ограничено размером модели
LiteLLM	Сложный	Зависит от провайдеров	Средняя	Гибкий
Bedrock/Vertex/Foundry	Средний	Pay-as-you-go	Высокая (корпоративная)	Claude (полное качество)

Как начать

Самый простой путь: OpenRouter + бесплатная модель

# 1. Зарегистрируйтесь на openrouter.ai и получите ключ
# 2. Установите переменные
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="or_ваш_ключ"
export ANTHROPIC_API_KEY=""

# 3. Запустите с бесплатной моделью
claude --model qwen/qwen3-coder:free

Для максимальной приватности: Ollama

# 1. Установите Ollama
brew install ollama

# 2. Запустите Claude Code одной командой (скачает модель автоматически)
ollama launch claude

# Или вручную:
ollama pull qwen3-coder
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
claude --model qwen3-coder

Для продвинутых: Claude Code Router

# 1. Установите роутер
npm install -g @musistudio/claude-code-router

# 2. Настройте провайдеров (config.json)
# 3. Запустите
ccr start && ccr ui

Альтернатива: Cline и Kilo Code, если Claude Code недоступен

Бывают ситуации, когда Claude Code нельзя установить или использовать напрямую — например, корпоративная политика блокирует CLI-инструменты, нет доступа к API Anthropic, или ваша организация ограничивает установку сторонних терминальных приложений.

В таком случае отличной альтернативой станут Cline и Kilo Code — AI-агенты, которые работают как расширения для VS Code:

Cline — open-source агент, который может автономно читать и редактировать файлы, запускать команды в терминале и работать с браузером
Kilo Code — форк Cline с дополнительными режимами работы (Code, Architect, Ask, Debug) и улучшенным управлением контекстом

Ключевое преимущество: эти расширения поддерживают подключение через OpenRouter, который предоставляет доступ к моделям Claude (и сотням других) через единый API. Это значит, что вы можете использовать те же модели Claude Sonnet и Opus, но через VS Code расширение вместо терминального агента.

Как настроить:

Установите расширение Cline или Kilo Code из VS Code Marketplace
Зарегистрируйтесь на OpenRouter и получите API-ключ
В настройках расширения выберите OpenRouter как провайдер и укажите ваш API-ключ
Выберите модель — например, anthropic/claude-sonnet-4 или бесплатную альтернативу

Kilo Code в VS Code с моделью Claude Sonnet через OpenRouter

Бесплатные модели через OpenRouter — если нет бюджета на API, можно использовать бесплатные модели (DeepSeek, Qwen, GPT-OSS) прямо в Cline/Kilo Code. Качество будет ниже, чем у Claude, но для многих задач этого достаточно.

Сценарий	Решение
Корпорация блокирует CLI-инструменты	Cline/Kilo Code как VS Code расширение
Нет доступа к API Anthropic	OpenRouter как прокси к моделям Claude
Нет бюджета на API	Бесплатные модели через OpenRouter
Нужен агентный подход в VS Code	Kilo Code с режимами Code/Architect/Debug

Итоги модуля

Claude Code можно подключить к любой OpenAI-совместимой модели через ANTHROPIC_BASE_URL
OpenRouter — самый простой путь к 400+ моделям, включая бесплатные
Claude Code Router — умный прокси с маршрутизацией задач по моделям
Ollama — локальные модели для приватности и работы без интернета
LiteLLM — единый прокси для смешанных конфигураций
Bedrock/Vertex/Foundry — официальные провайдеры для корпоративного использования
Другие модели работают хуже — промпты и инструменты оптимизированы под Claude
Лучшая стратегия: другие модели для анализа и вопросов, Claude для действий и сложных задач
Если Claude Code недоступен — используйте Cline или Kilo Code в VS Code с OpenRouter

Дополнительные курсы и ресурсы

Если хотите углубить знания по Claude Code, вот подборка курсов на английском языке:

Курс	Автор	Длительность	Стоимость
Claude Code: A Highly Agentic Coding Assistant	DeepLearning.AI + Anthropic (Elie Schoppik)	~2 часа	Бесплатно
Claude Code in Action	Anthropic (официальный)	Самостоятельный	Бесплатно
Claude Code: Software Engineering with Generative AI Agents	Coursera / Vanderbilt University (Dr. Jules White)	~5 часов	Бесплатно (аудит)
Claude Code for Everyone	Сообщество	Самостоятельный	Бесплатно

Также рекомендуем другие курсы от Anthropic:

Claude 101 — основы работы с Claude для повседневных задач
Building with the Claude API — создание приложений через API
Introduction to Model Context Protocol — построение MCP-серверов на Python

Спасибо за прохождение курса Claude Code 101!

Курс создан в 2025 году. Claude Code активно развивается, поэтому некоторые детали могут меняться. Всегда сверяйтесь с официальной документацией.