Разница между «Claude сделал не то» и «Claude сделал ровно то» почти всегда лежит не в модели, а в формулировке задачи. Агент не читает мысли: он видит только текст вашего запроса, содержимое проекта и то, что вы явно дали ему в контекст. Если в запросе не сказано, какой файл трогать, по какому образцу писать и как проверить результат, агент выберет всё это сам — и с приличной вероятностью выберет иначе, чем выбрали бы вы.

Расплата измеряется не только качеством: каждая неудачная попытка съедает контекст, и после двух-трёх кругов исправлений сессия захламляется провальными подходами. Дешевле потратить лишнюю минуту на формулировку, чем десять минут на переделку.

После этого урока у вас будет рабочая схема промпта, которую можно разворачивать под любую задачу.

Что уже умеем / что добавим

Вы уже запускаете Claude Code, управляете разрешениями, видите расход контекста через /context и чистите сессию через /clear и /compact. Теперь мы займёмся тем, что вы вводите руками каждый день: самим текстом запроса. Разберём его на составные части и соберём шаблоны под типовые задачи.

Что вы узнаете в рамках статьи

• Из каких смысловых блоков состоит хороший промпт и какие из них обязательны
• Как давать агенту контекст через @ссылки, изображения и вывод команд
• Почему критерий проверки важнее подробного описания решения
• Как разделять исследование, план и реализацию вместо одного большого запроса
• Готовые шаблоны промптов под баг, новую функцию и рефакторинг

Ключевые термины

• Промпт — текст запроса, который вы отправляете агенту в рамках одного хода диалога.
• Контекст задачи — файлы, ошибки, скриншоты и ограничения, которые агент должен видеть, чтобы решить задачу правильно.
• Критерий проверки — проверяемый признак того, что работа выполнена: прохождение тестов, успешная сборка, совпадение со скриншотом.
• @-ссылка — упоминание файла или каталога в промпте через символ @; содержимое файла попадает в контекст сразу, без отдельного чтения.
• Plan mode — режим, в котором агент исследует код и предлагает план, но не вносит правок, пока вы его не утвердите. Включается Shift+Tab.
• Course correction — приём быстрого вмешательства: остановить агента клавишей Esc, не дожидаясь конца неверной работы.

Пять блоков, из которых собирается промпт

Практически любой рабочий запрос раскладывается на пять частей. Не все обязательны, но чем сложнее задача, тем больше их нужно.

Задача — что должно измениться. Формулируется глаголом: «добавь», «исправь», «перепиши». Это единственный блок, без которого промпт не существует.

Область — где именно. Конкретный файл, каталог, модуль. Без этого агент начнёт искать сам, прочитает лишнее и раздует контекст.

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

Ограничения — чего делать нельзя: не подключать новые зависимости, не менять публичный API, не трогать соседние модули.

Проверка — как убедиться, что готово.

Сравните две формулировки одной задачи:

Плохо:
добавь тесты для валидации

Хорошо:
Напиши тесты для функции validateEmail в @src/utils/validate.ts.
Возьми за образец стиль тестов в @src/utils/format.test.ts.
Покрой случаи: user@example.com — true, invalid — false,
user@.com — false. Моки не используй.
После написания запусти тесты и почини падения.

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

Контекст: подсовывайте, а не описывайте

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

@-ссылка вставляет содержимое файла в разговор сразу. Каталог тоже можно указать: @src/components покажет список файлов, но не их содержимое. Полезная деталь: @-ссылка дополнительно подтягивает CLAUDE.md из каталога файла и родительских.

Ошибку не пересказывайте — вставляйте целиком, со стектрейсом. Данные можно передать через пайп:

cat error.log | claude -p "найди причину этих ошибок"
git log --oneline -20 | claude -p "суммируй последние коммиты"

Изображения вставляются прямо в поле ввода: перетаскиванием, через Ctrl+V (на Windows и WSL — Alt+V) или указанием пути к файлу. Скриншот ошибки, макет интерфейса, схема базы данных — всё это агент разбирает.

Есть и обратный приём: не давать контекст, а поручить агенту собрать его самому. «Посмотри в истории git, как появился этот API» работает лучше, чем ваша реконструкция по памяти.

Проверка важнее описания решения

Агент останавливается, когда работа выглядит завершённой. Если проверить её нечем, «выглядит завершённой» — единственный доступный сигнал, и роль контролёра достаётся вам: каждая ошибка ждёт, пока вы её заметите.

Дайте проверку — и цикл замкнётся без вас. Агент сделает, запустит, прочитает результат и будет исправлять, пока не пройдёт. Проверкой может быть что угодно, дающее читаемый ответ: набор тестов, код выхода сборки, линтер, сравнение скриншота с макетом.

Сборка падает вот с этой ошибкой:
[вставьте полный текст ошибки]

Почини и убедись, что сборка проходит. Разберись с причиной,
а не глуши симптом.

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

Сначала исследование, потом план, потом код

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

Включите plan mode нажатием Shift+Tab — в статусной строке появится ⏸ plan mode on. В этом режиме агент читает и отвечает, но не правит файлы.

Фаза 1 (plan mode):
Прочитай @src/auth и разберись, как устроены сессии и вход.
Посмотри заодно, как хранятся секреты в переменных окружения.

Фаза 2 (plan mode):
Нужно добавить вход через Google OAuth. Какие файлы затронуты?
Как выглядит поток сессии? Составь план.

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

Планирование добавляет накладные расходы, поэтому на опечатке или переименовании переменной оно излишне. Правило простое: если вы можете описать нужный диff одной фразой — план не нужен.

Шаблоны под типовые задачи

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

Баг:

Симптом: [что видит пользователь].
Где искать: [файл или каталог], вероятнее всего в [участок].
Напиши падающий тест, воспроизводящий проблему, затем почини.
Разберись с причиной, симптом не глуши.

Новая функция по образцу:

Посмотри, как устроены [существующие сущности] — хороший пример
в @path/to/Example.ts. По тому же образцу сделай [что нужно].
Новых зависимостей не подключай, обойдись тем, что уже есть.
Проверка: [команда].

Рефакторинг:

Перепиши @path/to/file.ts на [целевой подход], сохранив поведение.
Публичный API не меняй. После правки прогони [команда тестов]
и покажи вывод.

Частые ошибки

• Промпт без области действия. Запрос вида «почини авторизацию» заставляет агента прочитать десятки файлов в поисках нужного места. Контекст забивается, качество падает. Всегда называйте файл или каталог, даже приблизительно.
• Описание решения вместо задачи и критерия. Подробная инструкция «сделай так, потом так» лишает агента возможности найти вариант лучше и не даёт ему способа проверить себя. Описывайте желаемый результат и способ его проверить.
• Пересказ ошибки своими словами. «Там что-то падает на сборке» — это потеря информации. Вставляйте полный текст со стектрейсом: он и точнее, и короче в токенах, чем ваш пересказ плюс последующие уточнения.
• Бесконечные исправления в одной сессии. Если вы поправили агента дважды и результат всё ещё не тот, контекст уже засорён неудачными подходами. Сделайте /clear и напишите промпт заново, с учётом того, что выяснили.

Наиболее частые вопросы

• Насколько длинным должен быть промпт? — Ровно настолько, чтобы в нём были область, критерий проверки и ограничения. Обычно это три-шесть строк; длиннее нужно только для действительно многосоставных задач.
• Всегда ли лучше формулировать точно? — Нет. Когда вы исследуете код и готовы к правкам курса, расплывчатый вопрос вроде «что бы вы здесь улучшили?» полезен именно тем, что вскрывает то, о чём вы не догадались спросить.
• Чем @ссылка лучше, чем просто указать путь текстом? — @ кладёт содержимое файла в контекст немедленно, без отдельного шага чтения, и заодно подтягивает CLAUDE.md из каталога этого файла.
• Что делать, если агент пошёл не туда посреди работы? — Нажмите Esc. Работа остановится, контекст сохранится, и вы сможете скорректировать направление, не начиная с нуля.
• Нужно ли повторять в промпте то, что уже написано в CLAUDE.md? — Нет. CLAUDE.md загружается в каждую сессию, дублирование только расходует контекст и размывает акценты.

Итоги

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

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