## Подробное руководство по режиму Plan Бывало ли у вас такое: попросили Claude Code помочь с изменением кода, и он горой работает, меняет кучу файлов, а в итоге оказывается, что пошёл не в том направлении? Или посередине работы обнаруживаете, что забыли учесть какую-то зависимость, и приходится всё откатывать? Режим Plan именно для решения этих проблем. Он позволяет Claude сначала составить подробный план выполнения, а вы его проверяете и одобряете перед началом работы. Превращает «сначала выстрелим, потом нарисуем мишень» в «семь раз отмерь, один раз отрежь». ## Что такое режим Plan ### Plan режим vs обычный режим В обычном режиме Claude Code думает и выполняет одновременно: анализирует код, редактирует файлы, запускает команды — всё это чередуется. Для простых задач это очень эффективно, но для сложных может привести к проблеме «шаг за шагом». Режим Plan работает совершенно иначе: | Характеристика | Обычный режим | Режим Plan | |----------------|---------------|------------| | Способ выполнения | Думает и выполняет параллельно | Сначала планирует, выполняет после проверки | | Операции с файлами | Может сразу читать и писать | **Только читает**, только анализирует и ищет | | Выполнение команд | Может запускать команды напрямую | Не выполняет никаких модифицирующих команд | | Подходящие сценарии | Простые изменения, быстрые исправления | Многофайловый рефакторинг, сложная разработка | | Контроль рисков | Зависит от системы разрешений | Нулевой риск на этапе планирования | Проще говоря, Claude в режиме Plan — это архитектор только с блокнотом. Он тщательно обследует объект (читает код, ищет файлы), рисует подробный план строительства (план выполнения), но ни одного кирпича не сдвинет. ### Зачем нужно сначала планировать, потом выполнять Преимущества предварительного планирования выходят далеко за рамки одной лишь «безопасности»: 1. **Глобальный взгляд**: Claude сначала сканирует все связанные файлы, формирует общее понимание, а не обнаруживает упущения на полпути 2. **Проверяемость решений**: Вы можете проверить план перед выполнением, найти потенциальные проблемы, внести предложения 3. **Меньше переработок**: На этапе планирования уже можно обнаружить конфликты зависимостей, несоответствия интерфейсов 4. **Выравнивание знаний**: Читая план, вы понимаете, правильно ли Claude понял проект 5. **Повторное использование**: Хороший план можно сохранить как шаблон для похожих задач ### Какие сценарии подходят для режима 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 план обычно содержит следующую структуру: ```markdown ## План выполнения: добавление верификации 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 режима следовал единому формату: ```markdown ## Требования к режиму 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 для удобства код-ревью.