Как вести большую задачу: контекст и проверяемые этапы

Большая задача обычно начинается с разумно звучащего запроса. "Сделай справочник локалей: список, поиск по нему, фильтр по стране и приличное оформление." Через час перед вами страница, где список собран наполовину, поиск работает не по всем полям, оформление успело поменяться дважды, а разговор разросся настолько, что уже не видно, где там проверенный результат, а где просто прозвучавшее обещание.

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

Таким справочник и должен стать: список с поиском, а в строке код локали, язык, страна, валюта и домен. Держите этот макет в голове - в практике он пригодится как образец стиля, а не только как картинка.

Большая задача и длинный разговор

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

TASK_SPEC фиксирует цель, границы и проверку всей задачи. Затем работу по этой постановке делят на проверяемые этапы - milestones. У каждого есть результат и границы: например, добавить поиск, сохранив данные и оформление. Это помогает Claude работать по делу, а вам - видеть, где находится задача.

Если задача ещё неясна, первым этапом может быть разведка: прочитать два-три ключевых файла, назвать варианты решения и риски, затем уточнить описание задачи и следующие этапы.

Каждый этап завершайте проверками и короткой сводкой (summary): что сделано, чем проверено и что дальше. Если проект ведётся в Git, сохраняйте проверенные изменения небольшим коммитом. Сводка сохраняет решения, коммит - версию кода; вместе они помогают проверить результат и продолжить работу после паузы.

Что считать этапом

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

У этапа три обязательные части:

• результат - что именно начнёт работать;
• границы - чего в этот раз не трогаем;
• проверка - что вы посмотрите, чтобы убедиться.

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

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

Разделите результат на работающие части

Возьмём учебный справочник локалей. Поля у записи те же, что в макете выше: код локали, язык, страна, валюта и домен. Для простоты готовый массив лежит прямо в app.js, который подключён к index.html. Страница не загружает данные отдельным запросом, поэтому её можно открыть в браузере без сервера. Вот сам набор:

[
  { "code": "en-US", "language": "English", "country": "United States", "currency": "USD", "tld": ".us" },
  { "code": "de-DE", "language": "German", "country": "Germany", "currency": "EUR", "tld": ".de" },
  { "code": "fr-CA", "language": "French", "country": "Canada", "currency": "CAD", "tld": ".ca" },
  { "code": "ja-JP", "language": "Japanese", "country": "Japan", "currency": "JPY", "tld": ".jp" }
]

Пожелание целиком звучит так: список, поиск и фильтр по стране. "Приличное оформление" из вступления отдельным этапом не выделяем: базовый вид страница получает вместе со списком на M1, а в "отложенное" попадает только новое оформление, то есть смена темы. Разложим пожелание на три этапа.

Сначала нужен работающий список: на нём удобно проверять отбор записей. Поиск и фильтр можно добавлять в разном порядке; здесь выбран поиск, а на M3 проверяем их совместную работу. Стрелка между этапами означает, что предыдущий результат уже проверен, а зелёный M3 - этап, после которого пожелание выполнено целиком.

Здесь делим работу по результату. Внутри каждого этапа есть чтение кода, правки и проверка. План "сначала весь HTML, потом весь JS, в конце всё проверим" откладывает проверку поведения до самого конца. Готовая разметка тоже бывает полезным промежуточным результатом, но она ещё не показывает, работает ли поиск.

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

И три этапа тут - пример, а не норма. Бывает два, бывает шесть.

Дайте контекст текущему этапу

Когда этап выбран, агенту нужны сведения именно под него, а не весь проект целиком. Запрос на M2 в учебном справочнике может выглядеть так:

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

Прочитай @index.html и @app.js.

Нужно:
- поле поиска над списком;
- поиск по коду локали и по названию языка;
- запросы de-DE и German находят запись de-DE;
- запрос zzz не оставляет строк в списке;
- пустой запрос показывает весь список.

Фильтр по стране в этот раз не добавляем.
Если нужен другой файл, назови его и прочитай.
Сначала назови результат и границы этапа, файлы пока не меняй.

Если предложенные границы подходят, следующим сообщением попросите выполнить M2 и перечислить проверки в браузере. Заодно попросите отделить то, что агент проверил сам, от того, что ещё предстоит проверить вам.

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

Оформление тут - отдельный вид сведений, и на этом этапе его как раз сохраняют. Бывает и наоборот: внешний вид входит в результат этапа, например когда страница появляется впервые. Словами его не задать - просьба "сделай красиво" не содержит ничего проверяемого, и решение остаётся за агентом. Тогда приложите образец: макет, скриншот или маленький файл с цветами и названиями классов.

Заодно стоит помнить, чем такая формулировка не является. Строка "фильтр в этот раз не добавляем" - указание, а не техническая преграда. Она задаёт направление, но ничего не блокирует, поэтому результат вы всё равно смотрите сами.

Когда этап пора уменьшить

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

Спросите про каждое пожелание, нужно ли оно для выбранного результата. Новая цветовая тема и навигация могут подождать, а видимое поле ввода для поиска необходимо. Если в записях не хватает сведений, по которым нужно искать, сначала уточните границы: можно дополнить данные в текущем этапе или выделить их подготовку в отдельный проверяемый этап. Запрет менять данные нельзя молча отменить по ходу работы.

Уточняющий запрос выходит коротким:

Данные, оформление и навигацию в этот раз не меняем,
запиши их отдельными пунктами на потом.
Оставляем поиск по коду и языку: поле ввода, совпадения, пустой запрос.

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

Бывает и так, что этап не идёт: вы поправляете агента, он переделывает, и опять не то. Неудачные попытки при этом никуда не деваются, они остаются в разговоре, и следующая попытка опирается уже на них. Документация Claude Code даёт простой ориентир: если одно и то же пришлось поправлять больше двух раз, начните чистый разговор с запросом, в который вписано всё, что вы успели узнать. Например: "подход с отдельным массивом для поиска не подошёл, он расходится с исходными данными; ищи прямо по основному массиву". Такой запрос обычно работает лучше, чем третья правка подряд. А если и он не помогает, этап, скорее всего, слишком велик, и его стоит разделить.

Сохраните точку продолжения

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

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

Имя файла любое, подойдёт и уже существующая рабочая заметка. Пусть это будет PROGRESS.md. Ниже учебный пример после проверки M1; в своей заметке записывайте только то, что действительно сделали и наблюдали:

# Справочник локалей

## Сделано
M1: страница показывает список локалей из массива в app.js.

## Проверено
Открыл index.html в браузере: 4 записи, все пять полей каждой строки
совпадают с исходным массивом в app.js.

## Не проверено
Что показывает страница, если набор данных пустой.
Эта проверка не входила в критерии M1; поведение для пустого массива пока неизвестно.

## Решения
Данные храним массивом в app.js, отдельной загрузки данных нет.
Состав записей и оформление при добавлении поиска сохраняем.

## Отброшено
Загрузку данных из отдельного JSON-файла: без сервера браузер
его не прочитает, а страница должна открываться как файл.

## Файлы
index.html, app.js

## Оставшиеся этапы
M2: работает поиск по коду локали или названию языка.
Проверка: de-DE и German находят запись de-DE;
zzz не находит записей; пустой запрос показывает все четыре.

M3: фильтр по стране работает совместно с поиском.
Проверка: Canada + French оставляют fr-CA;
Canada + German дают пустой список;
сброс обоих условий возвращает четыре записи.

## Следующий шаг
Выполнить M2. Фильтр по стране пока не добавлять.

Ключевая здесь секция "Проверено". Запись "всё работает" через неделю не значит ничего, а "открыл в браузере, 4 записи, поля совпадают" - значит. Отдельная секция для непроверенного нужна ровно потому, что завтра вы этой разницы уже не вспомните.

Секцию "Отброшено" легко счесть лишней, ведь там то, чего в проекте нет. Но в новом разговоре агент ничего не знает о прошлых попытках и может честно предложить тот же путь заново. Одна строка с причиной экономит целый круг.

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

Два ограничения. Временный ход задачи не переезжает в CLAUDE.md - там живут постоянные правила проекта, а не то, чем вы заняты сегодня. И заметка не сохраняет версию кода: это текст о состоянии, а не копия файлов.

Продолжите с нужными сведениями

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

Если помогает - продолжайте в ней, специально ничего делать не нужно. Правила "очищать разговор после каждого этапа" не существует, как и порога в процентах, после которого якобы пора начинать заново.

Если непонятно, сколько места заняла история, вызовите /context и посмотрите на расход окна. Сопоставьте его с ходом работы: какие длинные выводы и обсуждения ещё нужны следующему этапу? Команда помогает оценить объём, но не определяет за вас, какие сведения полезны.

Если накопился посторонний материал и вы решили начать чистый разговор, сначала сохраните заметку. Команда /clear начинает новую беседу: прежняя история не подаётся в её рабочий контекст, исходники остаются на диске, а проектные инструкции продолжают загружаться. Это не безвозвратное удаление старой беседы: к сохранённому разговору можно вернуться через /resume. Но для продолжения в новой сессии нужные решения лучше передать явно.

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

Вход в новый разговор выглядит буднично:

Прочитай @PROGRESS.md, @index.html и @app.js.
Своими словами скажи, что уже готово и проверено, а что осталось.
Файлы пока не меняй.

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

Пройдите справочник целиком

Разбор закончен, дальше тот же справочник своими руками: от пустой папки до проверенного M2 и точки продолжения. Четыре шага идут по порядку статьи. На каждом сначала формулируйте промпт сами, а наш вариант открывайте вторым мнением: смысл в том, чтобы решить, какие сведения агенту нужны, а не скопировать строку.

Шаг 1. План без кода

Проекта ещё нет, и первое, чего хочется - попросить "сделай справочник". Тогда файлы появятся раньше решений о них. Задача шага обратная: получить план и ни одного файла. Прежде чем печатать, прокрутите в голове четыре вещи:

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

Наш вариант:

Хочу учебный справочник локалей: список записей, поиск по нему
и фильтр по стране. Проекта пока нет.

Страница должна открываться в браузере как файл, без сервера и сборки:
только index.html, styles.css и app.js. У записи поля код локали (en-US),
язык, страна, валюта и домен.

Сначала составь план:
- назови цель, границы и способ проверки всей задачи;
- раздели работу на три этапа;
- для каждого назови результат и то, что я увижу при проверке;
- скажи, каких сведений тебе не хватает от меня;
- перечисли файлы, которые создал бы.

Файлы пока не создавай.

Полученные этапы сверьте с таблицей M1-M3 выше; другой порядок - нормально. Разложил агент работу на "вся разметка, потом весь JS" - попросите переделать так, чтобы после каждого этапа страница что-то умела. А если у этапа не названо наблюдаемое поведение, поправьте формулировку сейчас: до первой строки кода это стоит одной реплики.

Шаг 2. Только M1, и сразу с образцом

Рамка узкая: страница показывает четыре записи, и всё. Ни поиска, ни фильтра. А вот внешний вид отложить не выйдет - страница появляется впервые, какой-то вид у неё будет. Поэтому приложите образец: сохраните в папку проекта mockup.html, статичную разметку без JavaScript, только цвета и имена классов.

<style>
  body   { background:#0f172a; color:#e2e8f0; font-family:system-ui, sans-serif; padding:24px }
  .search{ width:100%; margin-bottom:12px; padding:10px 14px; border-radius:10px;
           background:#1e293b; color:#e2e8f0; border:1px solid #334155 }
  table  { width:100%; border-collapse:collapse }
  th, td { padding:10px 12px; text-align:left; border-bottom:1px solid #334155 }
  th     { color:#8b98b1; font-size:13px }
  .code  { font-family:ui-monospace, monospace; font-weight:700; color:#818cf8 }
</style>

<input class="search" placeholder="Search by code or language">
<table>
  <tr><th>Code</th><th>Language</th><th>Country</th><th>Currency</th><th>TLD</th></tr>
  <!-- образец строки; живые строки рисует app.js -->
  <tr><td class="code">en-US</td><td>English</td><td>United States</td><td>USD</td><td>.us</td></tr>
</table>

Поле поиска в образце уже нарисовано, но на M1 его на страницу не переносим: пустое поле, которое ничего не делает, трудно проверить. Его стиль лежит в классе .search и пригодится на M2.

И ещё одна деталь: данные агенту нужно дать явно. Без них он придумает свой набор, и проверки из таблицы - четыре строки, de-DE, Canada - перестанут сходиться. Теперь промпт: подумайте, чем удержать агента внутри одного этапа, что попросить показать до правок и чем будете проверять результат.

Выполняем только M1: страница показывает список локалей
из массива в app.js. Поиска и фильтра в этот раз нет,
поле поиска из образца пока не добавляй.

Данные - этот массив из четырёх записей, состав не меняй:
[вставьте массив из статьи]

Внешний вид бери из @mockup.html: цвета и имена классов оттуда,
новых не придумывай.

Сначала покажи план файлов и скажи, на чём остановишься.
Файлы не создавай, пока я не подтвержу план.
После правок назови, что мне открыть и с чем сверить.

Остановись после M1, к M2 без моего слова не переходи.

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

Шаг 3. M2 и честная заметка

Промпт на M2 уже разобран в "Дайте контекст текущему этапу" - вернитесь к нему и подставьте свои пути. В разборе файлов два, у вас после M1 их три: к index.html и app.js добавился styles.css, его тоже укажите. И допишите одну строку: внешний вид теперь сохраняем, а не задаём.

Оформление уже задано на M1 по @mockup.html - сохрани его как есть,
поле поиска оформи классом .search оттуда.

Границы агент назвал верно - разрешайте правки. Полез в фильтр или в структуру данных - переспрашивайте до работы. Когда три проверки поиска прошли, запишите состояние в PROGRESS.md по образцу выше, только теперь уже после M2 и со своим списком файлов.

И проверьте свою заметку на прочность. Представьте, что в ней вместо раздела "Проверено" стоит строка "всё почти готово, осталось немного". Через неделю она не значит ничего. Допишите её так, чтобы по ней можно было продолжить: что именно вы открыли и увидели, что осталось за пределами проверок, какой следующий шаг. Ориентир - "M2: запросы de-DE и German находят de-DE, zzz не находит ничего, пустой запрос возвращает четыре записи", "поведение при пустом наборе данных не проверял", "следующий шаг - M3, фильтр по стране".

Шаг 4. Продолжите с чистого разговора

Последний шаг проверяет не код, а заметку. Начните новый разговор, попросите пересказать состояние по PROGRESS.md и актуальным файлам - всем трём, включая styles.css, - а потом сравните пересказ с тем, что вы делали. Агент назвал готовым то, чего вы не проверяли, - скорее всего, заметка написана слишком общо, и лечит это её правка, а не новый разговор. Но сверьте и с файлами: причина бывает и в коде, и в ошибке самого агента. Сошлось - у вас проверенный M1, проверенный M2 и точка, с которой начнётся M3.

Как перейти к следующему этапу

Итоговая последовательность получается короткой:

1. выберите ближайший результат, который можно проверить;
2. дайте агенту источники под этот этап и назовите границы;
3. выполните текущий этап; новые пожелания запишите отдельно;
4. выполните оговорённую проверку; в нашем примере проверьте поведение страницы в браузере;
5. запишите состояние: сделано, проверено, не проверено, что отбросили, следующий шаг;
6. решите, продолжать в этом разговоре или начать чистый.

Один этап - это не одно сообщение. Их может уйти три, а может пятнадцать, и это нормально. Число этапов не равно и числу разговоров: пара соседних этапов спокойно живёт в одной беседе, а один тяжёлый иногда занимает две.

Зато на любом шаге вы сможете ответить, что уже работает и чем это проверено. Для большой задачи это, пожалуй, самое важное.