Перейти к содержанию

Контекстные файлы KODA.md и AGENTS.md

По своей сути это README для AI-агентов, которые хранятся в корне проекта в формате Markdown. Внутри может быть описан технический конспект о проекте и базовые правила для работы с ним.

Некоторую информацию об этом можно также почитать на сайте https://agents.md

Файлы, которые Koda считывает автоматически, добавляя их содержимое в контекст сессии:

  • KODA.md (приоритет)
  • AGENTS.md
  • agents.md
  • AGENT.md

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

Файлы во вложенных директориях

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

Файл в корне рабочей области загружается при старте сессии. Файлы подкаталогов подключаются по мере работы агента с их файлами и каталогами:

  • при чтении файла агент получает инструкции всех каталогов на пути к нему — от корня рабочей области до его папки;
  • при просмотре каталога — инструкции этого каталога и его родителей;
  • соседние каталоги не сканируются;
  • повторные чтения не дублируют уже загруженные инструкции;
  • после сжатия контекста инструкции загружаются снова при следующем чтении в их каталоге.

Подробнее о поведении в плагине — в разделе «Инструкции во вложенных директориях», в CLI — в разделе «Файлы инструкций проекта».

Чтобы временно отключить файл, добавьте в его начало префикс # [DISABLED]. Такой файл не загружается, но занимает свой каталог: другой файл инструкций в этом каталоге не подставится вместо него.

Как создать

Автоматически

В режиме агента отправить команду /kodamd в плагине или /init в cli.

Если файл KODA.md уже существует, он будет обновлён.

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

Подсказка

Итоговый файл рекомендуется проверить самостоятельно и скорректировать при необходимости.

Вручную

Конечно, такой файл можно написать и самостоятельно. Это позволит

Для файла нет никаких сложных спецификаций и строгих правил. Главное, что следует соблюдать:

  • имя файла KODA.md или AGENTS.md;
  • содержимое в формате markdown, поскольку он позволяет легко структурировать документ и использовать простое форматирование текста.

Такой файл понимает любая модель и она будет следовать тем правилам, которые описаны внутри.

Подсказка

Если во время работы агента в файл вносились правки, рекомендуется начать новую сессиию или попросить агента перечитать файл, чтобы изменения появились в контексте.

Другие файлы, безусловно влияющие на контекст

.gitignore

Это файл, в котором задаются маски путей и имён файлов для игнорирования git. Такой файл обычно есть в любом проекте.

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

Koda учитывает содержимое .gitignore. Агент следует правилам, которые описаны там, и не читает запрещённые файлы.

.kodaignore

Это дополнительный файл правил игнорирования, который определяет те файлы и пути, которые агенту не следует изучать.

Он может дополнять правила .gitignore.

.kodarules

Пока только в плагинах.

Может использоваться для постоянной установки системного промпта, который описан внутри.

Содержимое файла не разбирается: оно целиком становится одним блоком правил и попадает в системное сообщение перед файлами памяти (KODA.md / AGENTS.md).

Файл ищется в корне рабочей области, а если CLI запущен из вложенной директории git-репозитория — по пути вверх до корня репозитория; применяется первый найденный файл.