Контекст и харнесс: AGENTS.md, спеки, sensors

Контекст и харнесс: AGENTS.md, спеки, sensors

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

Формула простая: агент = модель + харнесс. Модель одна и та же у всех; разница в харнессе — том, что подаётся вперёд (guides) и что возвращается назад (sensors).

AGENTS.md — память проекта

Файл в корне репозитория, который агент читает перед работой. Индустриальный стандарт 2026: его понимают Claude Code, Codex, Vibe и остальные.

# AGENTS.md

## О проекте
Тренажёр к экзамену: студент загружает материалы, получает вопросы.
Use cases — в `docs/use-cases/`, архитектура — `docs/diagrams/`.

## Стек и правила
- Python 3.13, uv, FastAPI. Форматирование ruff, типы ty.
- Всё поднимается через `docker compose up`; секреты только из `.env`.
- Диаграммы — PlantUML as-code, без mermaid.

## Соглашения команды
- Ветки `lab<N>-<role>-<тема>`, PR обязателен, ревью — от человека.
- Новая зависимость обсуждается, а не добавляется молча.
- Промпты к модели живут в `prompts/`, версионируются вместе с кодом.

## Глоссарий
- **Материал** — загруженный студентом файл курса.
- **Набор** — сгенерированные по теме вопросы (это не «тест»).

## Грабли
- Langfuse требует шести контейнеров; на слабой машине берём облако.
- Модель любит выдумывать вопросы не по материалу — проверяем ссылку
  на фрагмент источника.

## Всегда
- Непонятен API или версия — ищи в интернете, не угадывай.
- Не трогай миграции без явной просьбы.

Три раздела здесь работают сильнее остальных: глоссарий (агент перестаёт называть одну сущность тремя словами), грабли (перестаёт повторять уже пройденные ошибки) и «всегда» (постоянные правила, которые иначе приходится диктовать каждую сессию).

AGENTS.md — живой файл. Поймал агента на системной ошибке — правило дописывается туда, а не проговаривается в двадцатый раз.

Спеки вместо вайб-кодинга

Следующий уровень — Specs Driven Development: источник истины не код, а спецификация. Изменение продукта начинается с правки спеки, из неё следуют тесты и код.

Что это даёт на практике: проект передаётся другому человеку и другому агенту без «расскажи, как оно тут устроено»; маленькое контекстное окно перестаёт быть проблемой (агент читает нужный фрагмент, а не весь репозиторий); стейкхолдер видит требования, а не диффы.

Держится это на треугольнике: спеки ↔ тесты ↔ код. Разъехалась любая сторона — расхождение чинится в том же PR, а не «потом». У нас это уже встроено: из use cases пишутся evals, и только потом код, а aact check следит, чтобы диаграмма не врала.

Progressive disclosure: не вываливай всё сразу

Промпт не должен содержать весь контекст — он должен ссылаться на артефакты: спеку use case, AGENTS.md, нужный файл, заметки. Агент «ныряет» глубже только там, где ему это действительно нужно.

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

Sensors: обратная связь без человека в каждой мелочи

Guides подаются вперёд, sensors возвращаются назад. Sensors — это всё, что даёт агенту машинный вердикт о его же работе:

Ключевой принцип, общий с мультиагентными системами: жёсткое ограничение — это код, а не абзац в промпте. «Не добавляй зависимости» в промпте соблюдается через раз; тот же запрет в pre-commit — всегда.

База знаний для ресёрча

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

Смысл не в инструментах, а в правиле: агент отвечает из корпуса и называет источник. Ответ без ссылки на конкретный документ считается неподтверждённым — ровно как в лабе 1 при проверке гипотез.