Приложение к двум статьям: справочнику и практикуму. Статьи объясняют, этот файл заполняют. Образец заполнения — учебный пример; карта всего набора — комплект.
Скопируйте его к себе в репозиторий и правьте под свой проект: это заготовка, а не стандарт. Части независимы — можно начать с самопроверки, а можно сразу с диагностики, если уже что-то сломалось.
| Часть | Когда нужна |
|---|---|
| 1. Самопроверка | Первый проход: что умею, что вижу впервые |
| 2. Диагностика отказа | Что-то сломалось и непонятно почему |
| 3. Шаблон промпта | Повторяемая задача, которую хочется стабилизировать |
| 4. Инвентаризация контекста | Разобрать, что фактически попало во вход модели |
| 5. Вечер практикума | Пройти шесть шагов на своей задаче за один заход |
1. Самопроверка
Отмечайте пункт, только если можете объяснить его коллеге и показать в своём проекте. «Слышал» не считается. Неотмеченное — ваш список обучения.
Отказы, которые я встречал и узнаю
Уровень промпта:
- Недоопределённая задача: модель выбрала критерии приёмки сама
- Конфликт инструкций: правила проекта и промпт требуют разного
- Инструкция без наблюдаемого результата: улучшение нельзя проверить
- Галлюцинация при отсутствии основания: нужного факта не было во входе
- Неверная «высота» инструкции: жёсткий скрипт или «действуй разумно»
- Непроверяемость правок промпта: сравнение по последнему впечатлению
Уровень контекста:
- Деградация на длинном входе: качество падает внутри заявленного окна
- Отвлекающий материал: похожее, но нерелевантное вредит сильнее пустоты
- Потеря середины: факт из середины входа используется хуже
- Загрязнение контекста ошибкой: ранний неверный вывод влияет до конца
- Переполнение окна и слепая компактизация: сжатие съело договорённость
- Дорогие инструменты: вывод инструмента съедает бюджет контекста
- Пересекающиеся инструменты: модель выбирает не тот
- Отсутствие внешней памяти: состояние не переживает сессию
- Инъекция инструкций через данные: текст из тикета исполнен как команда
Приёмы промпт-инжиниринга
- Критерии успеха сформулированы до написания промпта
- Явно названы задача, роль и аудитория результата
- Инструкция, данные и примеры структурно разделены
- Few-shot: два–пять канонических примеров, включая пограничный
- Длинный материал в начале, вопрос и ограничения в конце
- Осознанное управление рассуждением и его объёмом
- Контракт формата вывода (схема или структурированный вывод)
- Два–три жёстких ограничения вместо пошагового сценария
- Явно разрешено сказать «в материале этого нет»
- Большая задача разбита в цепочку проверяемых шагов
- Правки промпта идут от воспроизведённого отказа
- Промпт лежит в репозитории и проходит ревью
- Учтена модельная специфика используемого вендора
Приёмы контекст-инжиниринга
- Могу перечислить всё, что попадает во вход агента на одном шаге
- Отношусь к контексту как к бюджету внимания, а не к объёму диска
- Системная инструкция на рабочей «высоте»
- Устойчивые правила лежат в файле правил проекта
- Данные загружаются по требованию, а не целиком заранее
- Инструментов немного, они не пересекаются, вывод компактный
- При компактизации явно переносятся решения и ограничения
- Промежуточные выводы пишутся во внешнюю память
- Отдельные подзадачи уходят в субагентов со сжатым результатом
- Есть правило, когда начать новую сессию вместо продолжения
- Содержимое файлов и тикетов трактуется как данные, не как инструкции
- Есть способ посмотреть фактический вход модели на проблемном шаге
- Изменения контекстной схемы проверяются на наборе задач
Как читать результат. Меньше половины отмеченного — начинайте с части 5, а не с чтения документации: без воспроизведённого отказа приёмы не запоминаются. Больше половины, но провалы в контекстном разделе — типичный профиль разработчика, который хорошо пишет промпты и ещё не работал с длинными агентными сессиями.
2. Диагностика отказа
Ищите свой симптом, проверяйте гипотезу, делайте первое действие. Подробные примеры каждого отказа — в справочнике.
| Симптом | Вероятная причина | Первое действие |
|---|---|---|
| Результат формально корректен и бесполезен | Недоопределённая задача | Перенести критерии приёмки в текст промпта |
| Поведение «плавает» между одинаковыми запусками | Конфликт инструкций | Найти, где правила проекта спорят с промптом, и решить, что сильнее |
| Непонятно, стало ли лучше после правки | Нет наблюдаемого результата | Добавить в инструкцию то, что можно посчитать или запустить |
| Уверенный ответ про ваш код, не соответствующий коду | Нет основания во входе | Дать файл и разрешить ответ «в материале этого нет» |
| Ломается на первом исключении | Инструкция слишком детальна | Заменить скрипт на обязательные результаты |
| Каждый запуск делает по-своему | Инструкция слишком обща | Добавить два–три жёстких ограничения |
| На большом объёме материала качество хуже, чем на малом | Деградация на длинном входе | Сократить вход до необходимого; замерить порог |
| Агент правит не тот файл из нескольких похожих | Отвлекающий материал | Убрать legacy и черновики из области поиска |
| Ограничение из середины задачи проигнорировано | Потеря середины | Вынести ограничения отдельным блоком в конец |
| Агент много шагов чинит несуществующую проблему | Загрязнение контекста ошибкой | Остановить сессию, начать новую с переносом фактов |
| После долгой работы забыта ранняя договорённость | Слепая компактизация | Записать решения во внешнюю память до переполнения окна |
| Контекст кончается, а работа едва началась | Дорогие инструменты | Сократить вывод инструментов до значимой части |
| Поиск «не находит» существующий код | Пересекающиеся инструменты | Оставить один поисковый инструмент с внятным описанием |
| Завтра всё объясняется заново | Нет внешней памяти | Завести файл решений рядом с кодом |
| Агент сделал действие, которого вы не просили | Инъекция через данные | Ограничить полномочия; отделить данные от инструкций |
Порядок разбора. Воспроизвести отказ хотя бы дважды — однократный сбой ещё не отказ. Посмотреть фактический вход модели на проблемном шаге, а не только промпт. Изменить одно, прогнать три раза. Если помогло — записать приём туда, где он переживёт сессию.
3. Шаблон промпта
Разметка условна: важно, что части разделены и модель не принимает ваши данные за инструкции. Разделители подбирайте под своего вендора — рекомендации по разметке у моделей различаются. Заполненный шаблон держите в репозитории и правьте как код: через ревью и историю изменений.
<задача>
Что нужно сделать и для кого предназначен результат.
Одно предложение, без «сделай хорошо».
</задача>
<материал>
Файлы, тикет, логи, ссылки. Только то, что нужно для этой задачи.
Устаревшие и черновые версии сюда не попадают.
</материал>
<ограничения>
2–3 жёстких запрета или обязательства. Например:
— не менять публичные интерфейсы;
— не добавлять зависимости;
— если данных для вывода нет, написать об этом, а не предполагать.
</ограничения>
<формат>
Структура результата. Для машинной обработки — схема,
а не просьба «верни JSON».
</формат>
<критерии приёмки>
3–5 признаков, по которым результат будет принят.
Каждый признак можно посчитать, запустить или сверить.
</критерии приёмки>
<примеры>
1–2 канонических примера ожидаемого результата, из них один пограничный.
Не набор всех возможных случаев.
</примеры>
Проверка перед запуском: критерии написаны до промпта, а не подогнаны под первый ответ; ограничения ближе к концу, а не в середине материала; в материале нет legacy и черновиков, похожих на актуальный код; явно разрешено сообщить о нехватке данных; промпт можно запустить трижды и сравнить по критериям.
4. Инвентаризация контекста
Разбор одного шага агента — проблемного, а не удачного.
Задача:
Шаг (номер и что агент делал):
| Что попало во вход | Источник | Примерный объём | Нужно / мешает |
|---|---|---|---|
| Системная инструкция | |||
| Файл правил проекта | |||
| Описания инструментов | |||
| Формулировка задачи | |||
| Найденные файлы | |||
| Вывод команд и инструментов | |||
| История предыдущих шагов | |||
| Внешние данные (тикеты, страницы) |
Доля «мешает» от общего объёма:
Что делать с найденным:
| Находка | Действие |
|---|---|
| Файлы, похожие на нужный, но неактуальные | Исключить директорию из области поиска |
| Вывод инструмента длиннее его пользы | Сократить формат вывода или добавить фильтрацию |
| Два инструмента с похожими описаниями | Оставить один |
| Ограничение затерялось в середине | Вынести отдельным блоком в конец |
| История содержит ранний ошибочный вывод | Начать новую сессию, перенеся только факты |
| Внешний текст читается как инструкция | Пометить как данные, ограничить полномочия агента |
Результат до чистки:
Результат после:
5. Вечер практикума
Поля к шести шагам практикума. Пустые поля в конце вечера — тоже результат: они показывают, где вы остановились.
Задача: Репозиторий: Модель и инструмент: Дата:
Шаг 1. Критерии приёмки до промпта
1. 2. 3.
Шаг 2. Промпт и три прогона
| Прогон | Что получилось | Каких критериев не хватило |
|---|---|---|
| 1 | ||
| 2 | ||
| 3 |
Разброс между прогонами: большой / средний / нет
Шаг 3. Один воспроизводимый отказ
Отказ:
Тип (по таблице из части 2):
Что изменил (одно):
Результат трёх прогонов после правки:
Шаг 4. Разбор контекста
Заполняется по части 4.
Что выбросил:
Что стало лучше:
Шаг 5. Вынос устойчивого наружу
В файл правил проекта добавил:
В файл решений добавил:
Что сознательно не стал добавлять и почему:
Шаг 6. Длинная задача
Что пережило компактизацию, а что нет:
Была ли ранняя ошибка, повлиявшая на поздние шаги:
Моё правило остановки сессии:
Итог вечера
- Критерии приёмки формулирую до открытия агента
- Есть воспроизведённый отказ и снявшая его правка
- Знаю, что лежит во входе модели, и умею это посмотреть
- Правила и решения лежат в репозитории
- Есть момент, когда я прекращаю сессию, а не спорю с агентом
Что отработать на следующей задаче: