Как дать ИИ-агенту контекст проекта, чтобы он не гадал
Агент приходит в каждый разговор с чистой памятью. Все, что он знает о проекте, он либо прочитал в файлах, либо угадал. Задача в том, чтобы угадывать было нечего.
Что агент знает о проекте на старте
Ничего, кроме того, что лежит в папке. Он не помнит вчерашний разговор, не знает, что этот сервис устарел, а тот сервер боевой, что вы не любите лишние зависимости. Если этого нет в файлах, агент выведет ответ из кода и может ошибиться.
Признаки того, что контекста не хватает:
- агент каждый раз заново изучает структуру проекта и тратит на это лимит;
- предлагает решения, которые в проекте давно запрещены;
- спрашивает то, что вы уже объясняли в прошлой сессии.
Положите главное в CLAUDE.md или AGENTS.md
Claude Code при запуске читает файл CLAUDE.md в корне проекта, Codex читает AGENTS.md. Это место для того, что нужно в любой задаче:
- что это за проект и для кого, в двух строках;
- как запустить, собрать и проверить: точные команды;
- куда смотреть: какие папки за что отвечают;
- запреты: чего не трогать и почему;
- где лежат подробные документы.
Держите файл коротким. Он целиком попадает в контекст каждого разговора, и лишняя страница в нем стоит токенов в каждом ходе. Подробности выносите в отдельные документы, а в главном файле оставляйте ссылки на них.
Если работаете с обоими агентами, удобно держать одно содержание в двух файлах или сделать один из них ссылкой на другой.
Не тратьте файл проекта на манеры агента
Частая ошибка: половина CLAUDE.md уходит на «отвечай коротко», «не выдумывай», «сначала делай, потом пиши». Это правила поведения, а не знания о проекте.
В Hedoq такие правила уже есть. Каждый агент получает стартовый набор: отвечать кратко, без приветствий, сначала делать, честно говорить, если не знает или не проверил. Набор включен сразу и выключается тумблером «Краткие ответы агентов» в настройках. Поэтому файл проекта можно отдать целиком под сам проект.
Держите подробные документы в репозитории
Описание архитектуры, решения и их причины, устройство деплоя лучше хранить в папке docs/ рядом с кодом, а не в чате или заметках. Тогда:
- агент читает их, когда нужно, а не каждый ход;
- документы обновляются в той же правке, что и код;
- новый человек или новый агент читает то же самое.
Хорошая привычка: в конце задачи просить агента обновить нужный документ. Писать, как работает сейчас, а не журнал по датам.
Тот же прием Hedoq использует в автоматизациях: агент кладет в папку описание устройства и итог сделанного, и следующий агент читает их первыми.
Давайте точные пути, а не описания
«Поправь форму на странице оплаты» заставляет агента искать. «Поправь src/pages/checkout/Form.tsx» сразу ведет к делу. В Hedoq путь вставляется без набора:
- перетащите файл из Finder на сессию: в поле встанет его путь;
- в дереве файлов у строки есть кнопка, которая вставляет путь в сессию;
- картинку из буфера (⌘V) Hedoq сохраняет файлом и вставляет путь;
- во встроенном браузере «Показать модели»: наведите на элемент страницы, нажмите и допишите записку. В сессию уйдет ссылка на описание элемента и снимок.
Сохраняйте контекст между сессиями
Разговор с агентом конечен, проект нет. Когда разговор становится длинным, важно не потерять то, что вы объяснили по ходу.
В Hedoq «Обновить сессию» перед очисткой просит агента записать сводку: проект и где он лежит, ваши постоянные правила и запреты из разговора, что сделано, что дальше и раздел «Прочесть» с полными путями нужных документов. Новый разговор начинается с этой сводки. Подробнее: длинные задачи без потери нити.
Где живут проекты: в Hedoq проект для новой сессии выбирается из папки Hedoq Space в домашней папке, или Hedoq заводит там новый. Держите там рабочие проекты, и в окне «Новая сессия» они будут под рукой.
Если правило из разговора пригодится и дальше, попросите агента перенести его в CLAUDE.md или AGENTS.md. Тогда его не придется повторять.