Агенты считывают содержимое вашего репозитория. Этого достаточно для большинства их нужд — но не для тех решений, которые хранятся в головах людей, в wiki или в переписке двухлетней давности.
Контекст проекта — это место, где вы указываете остальное.
Что Coroid определяет самостоятельно
Только на основе данных репозитория агенты могут увидеть:
- используемые языки программирования, фреймворки и библиотеки
- как собирается, тестируется и запускается проект
- существующие шаблоны — как обрабатываются ошибки, как структурируются модули, как называются элементы
- какие компоненты зависят друг от друга
Вам не нужно документировать всё это. Повторное изложение — пустая трата времени, к тому же оно быстро устаревает по сравнению с самим кодом, который и является более авторитетным источником.
Что агенты не могут определить самостоятельно
Код показывает что вы сделали, но никогда не показывает почему:
- причину, по которой была выбрана одна библиотека вместо очевидной альтернативы, и почему это решение до сих пор актуально
- шаблон, который выглядит как дублирование, но на самом деле является осознанным разделением логики
- модуль, с которым нельзя работать без предварительной консультации с определённой командой
- согласованные, но пока не закреплённые нигде правила оформления
- ограничения, исходящие извне кода — требования к соответствию нормативам, контракты, текущая миграция
Именно это и должно быть указано в контексте проекта. Проверка проста: сможет ли человек, читая только репозиторий, всё это понять? Если да — не включайте это в контекст. Если нет — запишите.
Добавление контекста
Прикрепляйте документы, политику и ссылки в разделе «Контекст» вашего Контекст Примечания к архитектуре, протоколы принятых решений, руководства по стилю и контракты API — всё это подходит.
Хороший контекст — краткий и конкретный. 40-страничное руководство по онбордингу, написанное для людей, в основном состоит из описательного текста; важны лишь три абзаца в нём, где указаны реальные ограничения. Выделите их.
Контекст для отдельных задач
Контекст, прикреплённый к проекту, относится ко всему. Если какая-то информация актуальна лишь для одной задачи — тикета, технического задания или отчёта клиента — прикрепляйте её к самой задаче.
Оставляйте контекст проекта для того, что остаётся актуальным надолго. Заметка, относящаяся к конкретной задаче, попадёт в контекст проекта и станет мешающим элементом для всех последующих задач.
Сохранение актуальности контекста
Устаревший контекст хуже отсутствия контекста, так как агенты воспринимают его как достоверный источник. При изменении правил оформления обновляйте контекст в той же правке, что и код.
Если вы постоянно исправляете одно и то же в комментариях к доработкам, это сигнал о том, что в контексте чего-то не хватает или что-то в нём указано неверно.