Подробное руководство по режиму Plan¶
Бывало ли у вас такое: попросили Claude Code помочь с修改代码, и он горой работает, меняет кучу файлов, а в итоге оказывается, что пошёл не в том направлении? Или посередине работы обнаруживаете, что забыли учесть какую-то зависимость, и приходится всё откатывать?
Режим Plan именно для решения этих проблем. Он позволяет Claude сначала составить подробный план выполнения, а вы его проверяете и одобряете перед началом работы. Превращает «сначала выстрелим, потом нарисуем мишень» в «семь раз отмерь, один раз отрежь».
Что такое режим Plan¶
Plan режим vs обычный режим¶
В обычном режиме Claude Code думает и выполняет одновременно: анализирует код, редактирует файлы, запускает команды — всё это чередуется. Для простых задач это очень эффективно, но для сложных может привести к проблеме «шаг за шагом».
Режим Plan работает совершенно иначе:
| Характеристика | Обычный режим | Режим Plan |
|---|---|---|
| Способ выполнения | Думает и выполняет параллельно | Сначала планирует, выполняет после проверки |
| Операции с файлами | Может сразу читать и писать | Только читает, только анализирует и ищет |
| Выполнение команд | Может запускать команды напрямую | Не выполняет никаких модифицирующих команд |
| Подходящие сценарии | Простые изменения, быстрые исправления | Многофайловый рефакторинг, сложная разработка |
| Контроль рисков | Зависит от системы разрешений | Нулевой риск на этапе планирования |
Проще говоря, Claude в режиме Plan — это архитектор только с блокнотом. Он тщательно обследует объект (читает код, ищет файлы), рисует подробный план строительства (план выполнения), но ни одного кирпича не сдвинет.
Зачем нужно сначала планировать, потом выполнять¶
Преимущества предварительного планирования выходят далеко за рамки одной лишь «безопасности»:
- Глобальный взгляд: Claude сначала сканирует все связанные файлы, формирует общее понимание, а не обнаруживает упущения на полпути
- Проверяемость решений: Вы можете проверить план перед выполнением, найти потенциальные проблемы, внести предложения
- Меньше переработок: На этапе планирования уже можно обнаружить конфликты зависимостей, несоответствия интерфейсов
- Выравнивание знаний: Читая план, вы понимаете, правильно ли Claude понял проект
- Повторное использование: Хороший план можно сохранить как шаблон для похожих задач
Какие сценарии подходят для режима Plan¶
Настоятельно рекомендуется использовать режим Plan:
- Изменения затрагивают более 5 файлов
- Нужно модифицировать core-модули или публичные интерфейсы
- Добавление новых функций (особенно связанных с базой данных, API)
- Рефакторинг существующей структуры кода
- Исправление Bug'а неизвестного происхождения (нужно сначала разобраться)
- Вы ещё недостаточно знакомы с проектом, нужно сначала разобраться в структуре
Можно сразу использовать обычный режим:
- Исправление чётко определённого мелкого Bug'а
- Локальные изменения в одном файле
- Добавление комментариев или документации
- Простое форматирование или переименование
Как использовать режим Plan¶
Переключение режима с помощью Shift+Tab¶
Включить режим Plan очень просто. В поле ввода Claude Code нажмите Shift+Tab, чтобы циклически переключать режимы:
default → acceptEdits → plan → bypassPermissions → default → ...
Когда индикатор режима слева от поля ввода показывает plan, значит, вы вошли в режим Plan.
Можно также прямо в подсказке указать, что хотите планировать:
Пожалуйста, сначала помогите составить план, не меняйте код напрямую. Я хочу добавить функцию верификации email для системы пользователей.
Подсказка: Нажмите
Escape, чтобы в любой момент вернуться в обычный режим.
Поведение Claude в режиме Plan¶
После входа в режим Plan возможности Claude ограничены:
Что можно делать:
- Читать любые файлы
- Искать код (Grep, Glob)
- Анализировать структуру проекта
- Просматривать историю Git
- Искать информацию в сети
- Составлять подробный план выполнения
Чего делать не будет:
- Создавать или изменять файлы
- Выполнять команды с побочными эффектами
- Устанавливать пакеты зависимостей
- Запускать сборку или тесты
Это значит, что вы можете смело позволить Claude исследовать любой код в режиме Plan, не беспокоясь, что он случайно что-то «исправит».
Просмотр и редактирование плана¶
Сгенерированный Claude план обычно содержит следующую структуру:
## План выполнения: добавление верификации email
### Цель
Добавить этап верификации email в процесс регистрации пользователей.
### Анализ влияния
- Файлы для изменения: 6
- Файлы для создания: 3
- Изменения в БД: нужно добавить 1 таблицу
- Точки риска: существующие пользователи не затронуты, но нужен миграционный скрипт
### Шаги выполнения
**Первый этап: уровень базы данных**
1. Создать миграционный скрипт для таблицы `email_verifications`
2. Изменить таблицу `users`, добавить поле `email_verified`
**Второй этап: бизнес-логика**
3. Создать `email_verification_service.py`
4. Изменить `auth_router.py`, добавить эндпоинты для верификации
5. Изменить `user_service.py`, инициировать верификационное письмо при регистрации
**Третий этап: адаптация фронтенда**
6. Изменить страницу регистрации, добавить подсказку о верификации
7. Создать страницу верификации email
8. Изменить конфигурацию роутинга
### Риски и примечания
- SMTP конфигурация должна быть подготовлена заранее
- Нужно учитывать срок действия ссылки для верификации
- Существующих пользователей нужно пропустить при верификации
Вы можете вносить свои правки в план:
В целом план хороший, но есть несколько корректировок:
1. Новую страницу верификации создавать не нужно, используем существующие toast-уведомления
2. Срок действия ссылки — 24 часа
3. На первом этапе таблицу users не меняем, определяем статус по таблице email_verifications
Обновите план, пожалуйста.
Claude внесёт изменения в план согласно вашим замечаниям, и так до тех пор, пока вы не будете довольны.
Одобрение плана и начало выполнения¶
Убедившись, что план корректен, переключитесь обратно в обычный режим (нажмите Shift+Tab), а затем скажите Claude выполнить план:
План выглядит нормально, пожалуйста, начните выполнение по плану. Начните с первого этапа.
Можно также выбрать поэтапное выполнение:
Сначала выполните первый этап (уровень базы данных), затем остановитесь и дайте мне проверить.
Практическое руководство по режиму Plan¶
Пример 1: добавление аутентификации в существующий проект¶
Допустим, у вас есть проект на FastAPI, сейчас без какой-либо системы аутентификации, и нужно добавить JWT-аутентификацию.
Шаг 1: переключитесь в режим Plan, опишите задачу
В моём FastAPI-проекте сейчас нет аутентификации пользователей. Пожалуйста, помогите составить план добавления JWT-системы аутентификации.
Требования:
- Регистрация и вход пользователей
- Выдача и проверка JWT Token
- Защита роутов (некоторые эндпоинты требуют авторизации)
- Управление таблицей пользователей через SQLAlchemy
Сначала проанализируйте существующую структуру кода, затем составьте подробный план выполнения.
Шаг 2: Claude анализирует проект и генерирует план
Claude сначала просканирует структуру вашего проекта:
Я проанализировал структуру вашего проекта. Вот мои находки и план выполнения:
## Анализ текущего состояния проекта
- Фреймворк: FastAPI 0.115.x
- База данных: есть конфигурация SQLAlchemy (database.py), используется PostgreSQL
- Существующие модели: Product, Order (в директории models/)
- Роутеры: product_router.py, order_router.py (без защиты аутентификацией)
- Управление зависимостями: используется requirements.txt
## План выполнения
### Первый этап: инфраструктура (2 файла)
1. В requirements.txt добавить python-jose[cryptography], passlib[bcrypt]
2. В config.py добавить JWT-конфигурацию (SECRET_KEY, ALGORITHM, TOKEN_EXPIRE)
### Второй этап: модель пользователя и база данных (2 файла)
3. Создать models/user.py — модель User
4. Создать миграционный скрипт alembic
### Третий этап: логика аутентификации (3 файла)
5. Создать services/auth_service.py — хеширование пароля, выдача/проверка JWT
6. Создать schemas/auth.py — модели запросов/ответов
7. Создать routers/auth_router.py — эндпоинты /register, /login, /me
### Четвёртый этап: защита роутов (3 файла)
8. Создать dependencies/auth.py — зависимость get_current_user
9. Изменить product_router.py — операции записи требуют аутентификации
10. Изменить order_router.py — все операции требуют аутентификации
### Предупреждения о рисках
- SECRET_KEY в config.py должен использовать переменную окружения, нельзя хардкодить
- Существующие API-клиенты нужно адаптировать под заголовок авторизации
- Рекомендуется сначала проверить в тестовой среде
Шаг 3: проверка и выполнение
План отличный. Две корректировки:
1. Не нужен alembic, используем SQLAlchemy create_all напрямую
2. Операции чтения в product_router аутентификации не требуют, только создание и удаление
В остальном всё в порядке, выполняйте по плану.
Пример 2: рефакторинг большого модуля¶
Допустим, в вашем проекте есть файл utils.py на 3000 строк, в котором «всё и сразу», и его нужно разбить при рефакторинге.
Войдите в режим Plan:
utils.py разросся до 3000 строк, там всё подряд. Пожалуйста, проанализируйте этот файл и составьте план рефакторинга, чтобы разбить его на несколько модулей с чёткими обязанностями. Требования:
1. Проанализировать все функции в utils.py по их назначению
2. Спроектировать новую структуру модулей
3. Перечислить все файлы, которые импортируют utils.py, и их затронутые импорты
4. Убедиться, что после рефакторинга все существующие функции продолжают работать
Claude сгенерирует что-то вроде такого плана:
## План рефакторинга utils.py
### Анализ текущего состояния
utils.py содержит 47 функций, по результатам анализа они делятся на 5 категорий:
| Категория | Количество функций | Примеры функций |
|-----------|-------------------|-----------------|
| Строковые операции | 12 | slugify, truncate, sanitize_html |
| Дата и время | 8 | parse_date, format_datetime, get_timezone |
| Операции с файлами | 9 | read_file, ensure_dir, get_file_hash |
| Валидация данных | 11 | validate_email, validate_phone, check_url |
| HTTP-утилиты | 7 | retry_request, parse_response, build_url |
### Анализ ссылок
Всего 23 файла импортируют utils.py, подробный список如下:
(перечисление каждого файла и используемых функций...)
### Новая структура модулей
utils/
├── __init__.py # реэкспорт для обратной совместимости
├── strings.py # строковые операции
├── datetime.py # дата и время
├── files.py # операции с файлами
├── validators.py # валидация данных
└── http.py # HTTP-утилиты
### Шаги выполнения
(пошаговое перечисление...)
### Стратегия обратной совместимости
В utils/__init__.py сохраняются все оригинальные экспорты:
from .strings import *
from .datetime import *
...
Таким образом, даже необнаруженные ссылки продолжат работать.
Пример 3: исправление Bug'а в нескольких файлах¶
Пользователи жалуются: «Сумма заказа иногда рассчитывается неправильно», но вы не знаете, в чём проблема.
Войдите в режим Plan:
Пользователи сообщают, что сумма заказа иногда рассчитывается неправильно, но не каждый раз. Пожалуйста, помогите найти эту проблему:
1. Найти весь код, связанный с расчётом сумм
2. Проанализировать возможные причины эпизодических ошибок
3. Составить план исправления
Claude в режиме Plan проведёт глубокий анализ:
## Отчёт об исследовании Bug'а
### Код, связанный с расчётом сумм
После полного поиска код расчёта сумм распределён по 4 файлам:
- order_service.py:calculate_total() — основная логика расчёта
- discount_service.py:apply_discount() — расчёт скидки
- tax_service.py:calculate_tax() — расчёт налогов
- cart_service.py:get_cart_total() — итоговая сумма корзины
### Обнаруженные проблемы
**Коренная причина: проблема точности чисел с плавающей запятой**
В order_service.py строка 127:
total = sum(item.price * item.quantity for item in items)
В Python операции с плавающей запятой имеют проблемы с точностью:
>>> 0.1 + 0.2
0.30000000000000004
Когда заказ содержит товары с дробными ценами, накопленная погрешность может привести к отклонению итоговой суммы на 1 копейку.
**Вторичная проблема: порядок расчёта скидок**
Расчёт скидки в discount_service.py выполняется после расчёта налогов в tax_service.py,
но в некоторых сценариях параллельного выполнения порядок может нарушаться (потому что оба вызываются асинхронно).
### План исправления
1. Изменить все расчёты сумм на тип Decimal
2. Изменить порядок вызовов discount и tax на синхронный последовательный
3. Добавить unit-тесты на консистентность сумм
Этот пример показывает ценность режима Plan при исследовании Bug'ов — Claude не бросается исправлять код, а сначала проводит тщательный анализ.
Лучшие практики режима Plan¶
1. Описывайте «почему», а не «ка껶
Не рекомендуется:
В user.py добавьте метод verify_email, который принимает параметр token,
запрашивает таблицу email_verifications, и если token совпадает и не истёк,
устанавливает user.email_verified в True.
Рекомендуется:
Нам нужно, чтобы пользователи могли верифицировать свой email. После регистрации
пользователь получит письмо со ссылкой для верификации, при переходе по ссылке
статус email станет «верифицирован». Пожалуйста, спланируйте реализацию.
Почему? Потому что когда вы описываете «почему», у Claude больше пространства для выбора оптимального решения. Возможно, он заметит граничные случаи, о которых вы не подумали, или предложит более элегантную реализацию. Если вы уже расписали конкретную реализацию, ценность режима Plan значительно снижается.
2. Просите Claude выявлять риски в плане¶
Активно просите Claude анализировать риски:
В плане, пожалуйста, уделите особое внимание:
1. Какие существующие функции могут быть сломаны этими изменениями?
2. Какие конфигурационные файлы нужно синхронно изменить?
3. Нужны ли миграционные скрипты для изменений в базе данных?
4. Есть ли соображения по concurrency safety?
3. Выполняйте сложные планы поэтапно¶
Для больших задач не выполняйте весь план одним махом. Разбейте его на этапы, которые можно проверить по отдельности:
В этом плане 4 этапа, пожалуйста, выполняйте так:
- После завершения каждого этапа останавливайтесь
- Сообщайте мне о результатах этого этапа
- Ждите моего подтверждения перед следующим этапом
Преимущество: если на каком-то этапе что-то пойдёт не так, вы сможете вовремя скорректировать, не откатывая кучу изменений.
4. Комбинируйте план с Git-ветками¶
Оптимальный workflow: Plan режим → создание ветки → выполнение в новой ветке → код-ревью → мерж
# Сначала в режиме Plan составляем план
(переключиться в режим Plan, описать задачу, проверить план)
# Когда всё устроит, переключиться в обычный режим
Пожалуйста, сначала создайте новую ветку feature/email-verification, затем выполните план.
Если в процессе выполнения выяснится, что план неправильный, вы всегда можете вернуться на main и начать заново.
Режим Plan vs прямое кодирование¶
Когда режим Plan не нужен¶
- Простые задачи с изменением одного-двух файлов
- Точно знаете, что и как менять
- Нефункциональные изменения вроде добавления комментариев, правки текстов
- Запуск команд (установка зависимостей, запуск тестов)
Когда режим Plan обязателен¶
- Изменения затрагивают более 5 файлов
- Модификация публичных интерфейсов или core-модулей
- Недостаточное знание структуры проекта
- Bug неизвестного происхождения, нужно сначала разобраться
- Нужно оценить компромиссы между несколькими вариантами решений
Справочная таблица принятия решений¶
Какова ваша задача?
│
├─ Простое изменение (1-2 файла, направление ясно)
│ → Обычный режим, начинайте сразу
│
├─ Задача средней сложности (3-5 файлов, логика ясна)
│ → Можно сначала в режиме Plan быстро просканировать, подтвердить идею, затем переключиться на выполнение
│
└─ Сложная задача (много файлов, решение неясно, высокий риск)
→ Обязательно режим Plan, тщательное планирование перед выполнением
Продвинутые техники¶
1. Настройка шаблона Plan через CLAUDE.md¶
Вы можете определить требования к планированию в файле CLAUDE.md вашего проекта, чтобы каждый сеанс Plan режима следовал единому формату:
## Требования к режиму Plan
При входе в режим Plan, пожалуйста, генерируйте план по следующему шаблону:
### Обязательные разделы
1. **Анализ текущего состояния**: текущая структура кода и связанные файлы
2. **Проектирование решения**: конкретный план реализации, включая альтернативные варианты
3. **Область влияния**: какие файлы будут изменены, какие функции затронуты
4. **Оценка рисков**: возможные проблемы и меры по их предотвращению
5. **Шаги выполнения**: по порядку, каждый шаг можно проверить отдельно
6. **План тестирования**: как проверить корректность изменений
### Требования к формату
- Каждый шаг выполнения должен указывать затрагиваемые файлы
- Новые файлы отмечать [Новый]
- Изменяемые файлы отмечать [Изменить]
- Точки риска отмечать степень серьёзности: высокий/средний/низкий
Добавив этот раздел в CLAUDE.md, при каждом использовании режима Plan Claude будет формировать план в соответствии с этим шаблоном.
2. Использование подзадач (sub-agents) в режиме Plan¶
В режиме Plan вы можете попросить Claude использовать подзадачи (инструмент Agent) для более глубокого исследования:
Перед составлением плана, пожалуйста, помогите разобраться со следующими вопросами:
1. Какова текущая схема базы данных? Попросите подзадачу проанализировать все model-файлы
2. Каков список существующих API эндпоинтов? Попросите подзадачу просканировать все router-файлы
3. Какие сторонние библиотеки использует проект? Проверьте requirements.txt или pyproject.toml
Подзадачи выполняют исследовательские задачи в отдельном контексте, затем результаты объединяются в основной сессии, помогая Claude составить более точный план.
3. Сохранение и повторное использование планов¶
Хороший план можно сохранить как справочный шаблон. Попросите Claude экспортировать план в Markdown-файл:
Пожалуйста, сохраните только что составленный план в docs/plans/add-email-verification.md,
чтобы в будущем можно было использовать его как пример для похожих задач.
При следующей похожей задаче можно сослаться на него:
Пожалуйста, возьмите за основу структуру плана из docs/plans/add-email-verification.md
и составьте аналогичный план для SMS-верификации.
4. Использование режима Plan для код-ревью¶
Свойство «только чтение» режима Plan делает его идеальным для код-ревью:
(войдите в режим Plan)
Пожалуйста, проведите ревью всех service-файлов в src/services/, обращая особое внимание на:
1. Полнота обработки ошибок
2. Риски SQL-инъекций
3. Незакрытые ресурсы (соединения с БД, файловые дескрипторы)
4. Race conditions в асинхронном коде
Дайте подробный отчёт о ревью и рекомендации по улучшению.
Поскольку режим Plan не изменяет файлы, вы можете спокойно позволить Claude проводить ревью продакшен-кода, не опасаясь, что он «заодно» что-то исправит.
5. Комбинируйте с /compact для длинных сессий планирования¶
Процесс исследования в режиме Plan может потребовать много контекста (особенно если анализировалось много файлов). Если вы чувствуете, что контекст заканчивается, можно использовать /compact после завершения планирования и перед выполнением:
/compact сохранить полный план выполнения и анализ влияния, сжать промежуточный процесс исследования
Так в фазе выполнения будет достаточно контекстного пространства.
Часто задаваемые вопросы¶
Q: Может ли Claude случайно изменить файлы в режиме Plan?
A: Нет. Режим Plan на системном уровне запрещает все операции записи. Claude может читать любые файлы, но не может создавать, изменять или удалять что-либо.
Q: После составления плана, когда переключаюсь в обычный режим для выполнения, Claude ещё помнит план?
A: Да. Если вы не использовали /clear для очистки истории, переключение режима не теряет контекст. План остаётся в истории диалога, и Claude может выполнять его напрямую.
Q: Можно ли использовать MCP-инструменты в режиме Plan?
A: Можно использовать инструменты MCP только для чтения (поиск, запрос документации), но нельзя использовать инструменты с побочными эффектами.
Q: Если план мне не нравится, могу ли попросить Claude перепланировать?
A: Конечно. Вы можете много раз просить Claude корректировать план, пока не будете довольны. Свойство нулевого риска режима Plan означает, что вы можете смело экспериментировать и настраивать.
Q: Как делиться планами в командной работе?
A: Можно попросить Claude сохранить план в Markdown-файл и закоммитить в Git-репозиторий. Также можно включить содержимое плана прямо в описание PR для удобства код-ревью.