AI-гайд

Claude Code Desktop: рабочие практики

У тебя уже есть опыт с Claude Code Desktop — ты в нём писала бота. Эта статья — не про «как открыть» и не про «что такое CLI вообще». Она про четыре навыка, которые отделяют «модель пишет код, я нервничаю» от «модель пишет код, я спокойно веду проект»: CLAUDE.md, plan mode, управление контекстом, скоупинг задач. Все примеры — из твоего стека: Python + aiogram + SQLite + OpenAI API.

CLAUDE.md — память между сессиями

Claude Code сам по себе не помнит, что ты делала вчера. Он помнит только то, что прямо сейчас в его контексте: открытый чат и файлы, на которые ты сослалась. CLAUDE.md — это файл в корне проекта, который Claude Code читает в каждой сессии автоматически. Туда кладутся правила, не меняющиеся от задачи к задаче.

Что туда писать для бота:

• Стек одной строкой. «Python 3.11, aiogram 3, SQLite (bot.db), AsyncOpenAI, модель gpt-5.4-mini». Без этого Claude каждый раз переспрашивает или, хуже, додумывает.
• Структура проекта. Где лежат хендлеры, где — работа с БД, где — промпты. 5–7 строк, не больше.
• Жёсткие правила. «Все запросы к OpenAI — через AsyncOpenAI, не блокирующий клиент. Никогда не импортируй openai напрямую в хендлерах».
• Что НЕ делать. «Не добавляй сторонние библиотеки без согласования. Не трогай схему БД — миграции пишутся отдельно».

Чего туда не писать: текущие задачи, временные TODO, объяснение конкретной фичи. Это — в чат или в отдельный файл задачи. CLAUDE.md — про инварианты, а не про текущую работу. Хороший размер — 30–60 строк. Если стало 200 — модель начнёт хуже его читать (см. Базовый LLM, раздел про lost-in-the-middle).

Plan mode — «сначала покажи план, потом пиши код»

Plan mode — режим, в котором Claude Code не правит файлы, а сначала показывает тебе план: какие файлы тронет, что изменит, какие риски. Включается специальной командой в начале запроса или горячей клавишей в интерфейсе.

Зачем он нужен:

• Поймать недопонимание раньше. Ты говоришь «добавь команду /goals». Claude в плане пишет: «создам хендлер, добавлю таблицу goals, добавлю кнопку в главное меню». Ты видишь, что таблица уже есть (user_notes с типом goal) и поправляешь план до того, как Claude написал миграцию.
• Большие задачи разбиваются естественно. Если в плане 8 шагов — задача слишком большая для одного чата. Лучше сказать «давай сделаем шаги 1–3 в этой сессии, шаги 4–8 — в следующей».
• Меньше «откатов». Когда Claude уже написал 300 строк по неправильному пониманию — больно и тебе, и контексту чата (см. ниже).

Когда plan mode не нужен: точечная правка в одном файле («поправь опечатку», «переименуй переменную», «добавь try/except вокруг этого вызова»). Каждый план стоит токенов — для пятиминутной задачи это лишнее.

Управление контекстом: /clear, /compact, новый чат

У каждого чата есть окно контекста — сколько текста модель видит одновременно. Это вся история сообщений, все открытые файлы, весь CLAUDE.md. Окно большое (сотни тысяч токенов), но не бесконечное, и чем оно полнее, тем хуже модель держит фокус. Тонкости — в Базовом LLM; здесь — практика.

Три инструмента:

• /clear — стирает историю чата. CLAUDE.md остаётся, открытые файлы — нет. Используй, когда заканчиваешь одну задачу и переходишь к другой («дописали хендлер /start, теперь беру таск про кризисный протокол»). Не пытайся «дотащить» контекст — лучше начать чисто и явно дать Claude нужные файлы заново.
• /compact — сжимает историю чата: Claude сам пересказывает её коротко и продолжает работать с этим пересказом вместо полного лога. Используй, когда задача ещё не закончена, но чат стал длинным (модель начала забывать ранние решения, путать имена). После /compact проверь, что в пересказе осталось важное; если потерялось — допиши явно: «не забудь, что у нас в БД таблица называется user_notes, не notes».
• Новый чат — самый чистый старт. Всё новое окно, только CLAUDE.md. Используй между крупными темами: «закончили работу с базой, дальше переходим к промптам бота».

Скоупинг задач — главный навык

Большинство неприятностей с Claude Code — не от того, что модель плохая, а от того, что задача слишком большая для одного чата. Хороший размер задачи — такой, чтобы план укладывался в 3–5 шагов, а вся работа — в один чат без /compact.

Плохой запрос: «сделай кризисный протокол».
Хороший запрос:

1. «Список триггерных слов и фраз для кризисного протокола — отдельный Python-модуль crisis/triggers.py». Один чат.
2. «Функция-детектор кризиса по сообщению пользователя, использующая crisis/triggers.py». Один чат.
3. «Интеграция детектора в основной хендлер сообщений + safe-ответ». Один чат.

После каждого шага — проверка: запустила бота, написала триггерное сообщение, увидела, что детектор сработал. Не «сделаю всё, потом проверю»: если что-то сломалось на шаге 1, шаг 3 будет писаться поверх битого фундамента.

Claude Code CLI — когда полезен

Кроме Desktop-приложения, Claude Code есть как утилита командной строки. Ты ей не пользуешься — это нормально, для твоей работы Desktop достаточно. Знать про CLI стоит на случай, когда:

• Нужно прогнать одну и ту же задачу на куче файлов. Например, «пройдись по всем модулям и добавь docstring». В CLI это пишется как один скрипт, в Desktop — десятки ручных запусков.
• Запуск из CI/CD. Когда у Сониного бота появятся автотесты на pull-request'ах — туда можно подключить CLI, чтобы Claude комментировал диффы. Это уже скорее задача для Георгия (он тебе CI настроил), но знать существование инструмента полезно.
• Скриптуемые рабочие процессы. Если однажды захочется «каждое утро — отчёт о коммитах и предложения по рефакторингу», это пишется через CLI.

Чем CLI отличается от Desktop: нет графического интерфейса, нет plan mode в привычном виде (хотя есть аналог), нет автообновления файлов «на лету» — каждое действие явно запускается. Зато можно встроить в любой скрипт. Для интерактивной работы Desktop удобнее почти всегда.

Чего не делать

• Не наполнять CLAUDE.md «на всякий случай». Каждая лишняя строка — это контекст, который тратится при каждом запуске. Если правило применяется в одной задаче из десяти — это не правило, это уточнение к конкретному запросу.
• Не путать /compact с /clear. /compact — продолжаем тему, /clear — начинаем новую. Использовать /compact при смене темы — значит тащить за собой пересказ старой задачи в новую.
• Не задавать одной командой задачу на 8 файлов и 200 строк — она почти всегда заканчивается тем, что половину приходится переписывать.
• Не оставлять «временные» правки без пометки. Если попросила Claude «временно отключи проверку токена для теста» — сразу запиши это в tasks.md или комментарий TODO, иначе через неделю найдёшь это в проде.

Что почитать дальше

• Как работают LLM — фундамент — что такое токен, окно контекста, lost-in-the-middle. После этого управление контекстом из этой статьи становится не «магией», а физикой.
• Claude Research + расширенное мышление — другой режим работы, для глубоких исследований перед кодом.
• Claude Code для начинающих — если хочется освежить базу: как давать команды, типичные ошибки.