# Рабочий лист: промпт и контекст

Приложение к двум статьям:
[справочнику](/articles/prompt-and-context-engineering-basics.html) и
[практикуму](/articles/prompt-and-context-engineering-practice.html).
Статьи объясняют, этот файл заполняют. Образец заполнения —
[учебный пример](/prompt-and-context/example/); карта всего набора — [комплект](/prompt-and-context/).

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

| Часть | Когда нужна |
| --- | --- |
| [1. Самопроверка](#1-самопроверка) | Первый проход: что умею, что вижу впервые |
| [2. Диагностика отказа](#2-диагностика-отказа) | Что-то сломалось и непонятно почему |
| [3. Шаблон промпта](#3-шаблон-промпта) | Повторяемая задача, которую хочется стабилизировать |
| [4. Инвентаризация контекста](#4-инвентаризация-контекста) | Разобрать, что фактически попало во вход модели |
| [5. Вечер практикума](#5-вечер-практикума) | Пройти шесть шагов на своей задаче за один заход |

---

## 1. Самопроверка

Отмечайте пункт, только если можете объяснить его коллеге и показать в своём
проекте. «Слышал» не считается. Неотмеченное — ваш список обучения.

### Отказы, которые я встречал и узнаю

Уровень промпта:

- [ ] Недоопределённая задача: модель выбрала критерии приёмки сама
- [ ] Конфликт инструкций: правила проекта и промпт требуют разного
- [ ] Инструкция без наблюдаемого результата: улучшение нельзя проверить
- [ ] Галлюцинация при отсутствии основания: нужного факта не было во входе
- [ ] Неверная «высота» инструкции: жёсткий скрипт или «действуй разумно»
- [ ] Непроверяемость правок промпта: сравнение по последнему впечатлению

Уровень контекста:

- [ ] Деградация на длинном входе: качество падает внутри заявленного окна
- [ ] Отвлекающий материал: похожее, но нерелевантное вредит сильнее пустоты
- [ ] Потеря середины: факт из середины входа используется хуже
- [ ] Загрязнение контекста ошибкой: ранний неверный вывод влияет до конца
- [ ] Переполнение окна и слепая компактизация: сжатие съело договорённость
- [ ] Дорогие инструменты: вывод инструмента съедает бюджет контекста
- [ ] Пересекающиеся инструменты: модель выбирает не тот
- [ ] Отсутствие внешней памяти: состояние не переживает сессию
- [ ] Инъекция инструкций через данные: текст из тикета исполнен как команда

### Приёмы промпт-инжиниринга

- [ ] Критерии успеха сформулированы до написания промпта
- [ ] Явно названы задача, роль и аудитория результата
- [ ] Инструкция, данные и примеры структурно разделены
- [ ] Few-shot: два–пять канонических примеров, включая пограничный
- [ ] Длинный материал в начале, вопрос и ограничения в конце
- [ ] Осознанное управление рассуждением и его объёмом
- [ ] Контракт формата вывода (схема или структурированный вывод)
- [ ] Два–три жёстких ограничения вместо пошагового сценария
- [ ] Явно разрешено сказать «в материале этого нет»
- [ ] Большая задача разбита в цепочку проверяемых шагов
- [ ] Правки промпта идут от воспроизведённого отказа
- [ ] Промпт лежит в репозитории и проходит ревью
- [ ] Учтена модельная специфика используемого вендора

### Приёмы контекст-инжиниринга

- [ ] Могу перечислить всё, что попадает во вход агента на одном шаге
- [ ] Отношусь к контексту как к бюджету внимания, а не к объёму диска
- [ ] Системная инструкция на рабочей «высоте»
- [ ] Устойчивые правила лежат в файле правил проекта
- [ ] Данные загружаются по требованию, а не целиком заранее
- [ ] Инструментов немного, они не пересекаются, вывод компактный
- [ ] При компактизации явно переносятся решения и ограничения
- [ ] Промежуточные выводы пишутся во внешнюю память
- [ ] Отдельные подзадачи уходят в субагентов со сжатым результатом
- [ ] Есть правило, когда начать новую сессию вместо продолжения
- [ ] Содержимое файлов и тикетов трактуется как данные, не как инструкции
- [ ] Есть способ посмотреть фактический вход модели на проблемном шаге
- [ ] Изменения контекстной схемы проверяются на наборе задач

**Как читать результат.** Меньше половины отмеченного — начинайте с части 5, а
не с чтения документации: без воспроизведённого отказа приёмы не запоминаются.
Больше половины, но провалы в контекстном разделе — типичный профиль
разработчика, который хорошо пишет промпты и ещё не работал с длинными
агентными сессиями.

---

## 2. Диагностика отказа

Ищите свой симптом, проверяйте гипотезу, делайте первое действие. Подробные
примеры каждого отказа — в
[справочнике](/articles/prompt-and-context-engineering-basics.html).

| Симптом | Вероятная причина | Первое действие |
| --- | --- | --- |
| Результат формально корректен и бесполезен | Недоопределённая задача | Перенести критерии приёмки в текст промпта |
| Поведение «плавает» между одинаковыми запусками | Конфликт инструкций | Найти, где правила проекта спорят с промптом, и решить, что сильнее |
| Непонятно, стало ли лучше после правки | Нет наблюдаемого результата | Добавить в инструкцию то, что можно посчитать или запустить |
| Уверенный ответ про ваш код, не соответствующий коду | Нет основания во входе | Дать файл и разрешить ответ «в материале этого нет» |
| Ломается на первом исключении | Инструкция слишком детальна | Заменить скрипт на обязательные результаты |
| Каждый запуск делает по-своему | Инструкция слишком обща | Добавить два–три жёстких ограничения |
| На большом объёме материала качество хуже, чем на малом | Деградация на длинном входе | Сократить вход до необходимого; замерить порог |
| Агент правит не тот файл из нескольких похожих | Отвлекающий материал | Убрать legacy и черновики из области поиска |
| Ограничение из середины задачи проигнорировано | Потеря середины | Вынести ограничения отдельным блоком в конец |
| Агент много шагов чинит несуществующую проблему | Загрязнение контекста ошибкой | Остановить сессию, начать новую с переносом фактов |
| После долгой работы забыта ранняя договорённость | Слепая компактизация | Записать решения во внешнюю память до переполнения окна |
| Контекст кончается, а работа едва началась | Дорогие инструменты | Сократить вывод инструментов до значимой части |
| Поиск «не находит» существующий код | Пересекающиеся инструменты | Оставить один поисковый инструмент с внятным описанием |
| Завтра всё объясняется заново | Нет внешней памяти | Завести файл решений рядом с кодом |
| Агент сделал действие, которого вы не просили | Инъекция через данные | Ограничить полномочия; отделить данные от инструкций |

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

---

## 3. Шаблон промпта

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

```
<задача>
Что нужно сделать и для кого предназначен результат.
Одно предложение, без «сделай хорошо».
</задача>

<материал>
Файлы, тикет, логи, ссылки. Только то, что нужно для этой задачи.
Устаревшие и черновые версии сюда не попадают.
</материал>

<ограничения>
2–3 жёстких запрета или обязательства. Например:
— не менять публичные интерфейсы;
— не добавлять зависимости;
— если данных для вывода нет, написать об этом, а не предполагать.
</ограничения>

<формат>
Структура результата. Для машинной обработки — схема,
а не просьба «верни JSON».
</формат>

<критерии приёмки>
3–5 признаков, по которым результат будет принят.
Каждый признак можно посчитать, запустить или сверить.
</критерии приёмки>

<примеры>
1–2 канонических примера ожидаемого результата, из них один пограничный.
Не набор всех возможных случаев.
</примеры>
```

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

---

## 4. Инвентаризация контекста

Разбор одного шага агента — проблемного, а не удачного.

**Задача:**

**Шаг (номер и что агент делал):**

| Что попало во вход | Источник | Примерный объём | Нужно / мешает |
| --- | --- | --- | --- |
| Системная инструкция | | | |
| Файл правил проекта | | | |
| Описания инструментов | | | |
| Формулировка задачи | | | |
| Найденные файлы | | | |
| Вывод команд и инструментов | | | |
| История предыдущих шагов | | | |
| Внешние данные (тикеты, страницы) | | | |

**Доля «мешает» от общего объёма:**

Что делать с найденным:

| Находка | Действие |
| --- | --- |
| Файлы, похожие на нужный, но неактуальные | Исключить директорию из области поиска |
| Вывод инструмента длиннее его пользы | Сократить формат вывода или добавить фильтрацию |
| Два инструмента с похожими описаниями | Оставить один |
| Ограничение затерялось в середине | Вынести отдельным блоком в конец |
| История содержит ранний ошибочный вывод | Начать новую сессию, перенеся только факты |
| Внешний текст читается как инструкция | Пометить как данные, ограничить полномочия агента |

**Результат до чистки:**

**Результат после:**

---

## 5. Вечер практикума

Поля к шести шагам [практикума](/articles/prompt-and-context-engineering-practice.html).
Пустые поля в конце вечера — тоже результат: они показывают, где вы
остановились.

**Задача:**   **Репозиторий:**   **Модель и инструмент:**   **Дата:**

### Шаг 1. Критерии приёмки до промпта

1.
2.
3.

### Шаг 2. Промпт и три прогона

| Прогон | Что получилось | Каких критериев не хватило |
| --- | --- | --- |
| 1 | | |
| 2 | | |
| 3 | | |

**Разброс между прогонами:** большой / средний / нет

### Шаг 3. Один воспроизводимый отказ

**Отказ:**

**Тип** (по таблице из части 2):

**Что изменил (одно):**

**Результат трёх прогонов после правки:**

### Шаг 4. Разбор контекста

Заполняется по части 4.

**Что выбросил:**

**Что стало лучше:**

### Шаг 5. Вынос устойчивого наружу

**В файл правил проекта добавил:**

**В файл решений добавил:**

**Что сознательно не стал добавлять и почему:**

### Шаг 6. Длинная задача

**Что пережило компактизацию, а что нет:**

**Была ли ранняя ошибка, повлиявшая на поздние шаги:**

**Моё правило остановки сессии:**

### Итог вечера

- [ ] Критерии приёмки формулирую до открытия агента
- [ ] Есть воспроизведённый отказ и снявшая его правка
- [ ] Знаю, что лежит во входе модели, и умею это посмотреть
- [ ] Правила и решения лежат в репозитории
- [ ] Есть момент, когда я прекращаю сессию, а не спорю с агентом

**Что отработать на следующей задаче:**