Модуль 02 — Контекст-инжиниринг
Время: 4 часа · Формат: теория 80 мин + практика 160 мин
Теория
1. Контекст — это рабочая память, а не склад
Каждый запрос к модели собирается заново из:
системная политика → инструкции проекта → открытые файлы → история → ваш вопрос
Всё это — бюджет. Чем больше мусора, тем меньше остаётся на важное.
Ментальная модель: у агента не «память проекта», а стол, на который вы каждый раз выкладываете бумаги. Что не положили — того нет.
2. Три уровня инструкций
| Уровень | Файл | Область |
|---|---|---|
| Глобальный | ~/.config/opencode/opencode.jsonc |
ваши привычки, модели, права |
| Проектный | <проект>/AGENTS.md |
стек, команды, конвенции |
| Сессионный | ваш запрос | конкретная задача |
AGENTS.md — самый недооценённый файл в вайбкодинге. Он читается автоматически
в каждой сессии, поэтому 20 строк там экономят часы объяснений.
3. Что писать в AGENTS.md
Хороший AGENTS.md отвечает на вопросы, которые иначе агент выясняет наугад:
# Проект: <название>
## Стек
Python 3.12, FastAPI, pytest, Ruff
## Команды
- тесты: `pytest -q`
- линтер: `ruff check .`
- запуск: `uvicorn app.main:app --reload`
## Конвенции
- типизация обязательна, `mypy` строгий
- никаких новых зависимостей без обсуждения
- ошибки — через `AppError`, не `raise ValueError`
## Запрещено
- трогать `migrations/` руками
- менять `.env`
- коммитить в `main`
Правила: коротко, императивно, только то, что нельзя угадать.
4. Гигиена сессии
| Признак | Действие |
|---|---|
| Агент забыл требование из начала | напомнить в вопросе, не искать в истории |
| 3+ неудачные попытки подряд | новая сессия + точное описание |
| Смешались две задачи | разделить на две сессии |
| Контекст почти полон | компакция или новая сессия |
Компакция (сжатие истории) помогает, но сжимает не всё одинаково — важные детали
могут потеряться. Надёжнее — вынести результат в файл (план, TODO.md) и начать заново.
5. Ссылки вместо пересказа
| Плохо | Хорошо |
|---|---|
| «У нас есть модуль авторизации, он такой…» | src/auth/session.py, функция refresh_token |
| «Вставлю код сюда» (500 строк) | «смотри файл, правь только parse_date» |
| «Как в нашем проекте?» | «как в services/billing.py» |
Модель умеет читать файлы инструментом. Дайте путь — сэкономите токены и получите актуальную версию, а не ваш пересказ.
6. Структура запроса, которая работает
1. Контекст: где мы, что уже сделано (2–3 строки)
2. Задача: одно предложение
3. Ограничения: что нельзя, что обязательно
4. Критерий готовности: как проверим
5. Формат ответа: план / дифф / только файл X
Пункт 5 недооценён: «сначала план, без кода» экономит больше всего времени.
7. Компакция и память
В OpenCode есть настройка compaction — автоматическое сжатие истории.
Полезно, но не бесплатно: сжатие — это ещё один вызов модели.
Практическое правило: держать в контексте только текущую задачу, а долговременные
знания хранить в файлах репозитория (AGENTS.md, docs/, TODO.md).
Чек-лист понимания
- Почему «модель запомнит наш разговор» — опасное заблуждение?
- Что эффективнее: пересказать модуль словами или дать путь к файлу? Почему?
- Назовите три признака, что сессию пора закрыть.
- Почему «сначала план» экономит контекст?
Практика
См. practice.md.