Правила агента¶

v0.1.5

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

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

Когда использовать правила¶

Правила хорошо подходят для устойчивых договорённостей:

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

Не стоит превращать правила в длинную спецификацию задачи. Если инструкция нужна только один раз, лучше написать её прямо в запросе агенту.

Где находятся правила¶

Koda собирает правила из нескольких источников.

Источник	Где настраивается	Как используется
Блок `rules`	В конфигурации Koda	Добавляется в системное сообщение
Файл `.kodarules`	В корне проекта	Добавляется в системное сообщение
Файлы инструкций проекта	В контекстном файле проекта	Корневой файл — в системное сообщение, вложенные — по мере чтения файлов

Подробнее о контекстных файлах рассказано в разделе Контекстные файлы KODA.md и AGENTS.md

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

Правила из конфигурации¶

Основной способ задать правило — добавить его в массив rules в конфигурации Koda. Правило может быть простой строкой или объектом с именем и текстом.

config.yaml

rules:
  - Отвечай на русском языке.
  - Не добавляй новые зависимости без явной необходимости.
  - name: Тесты для серверной логики
    rule: При изменении серверной логики добавляй или обновляй тесты.

Правила можно настроить довольно гибко

См. раздел о конфигурационном файле для подробностей: Конфигурация

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

Файл .kodarules¶

Файл .kodarules — это dot-файл в корне рабочей области, содержимое которого целиком добавляется как одно правило. Это удобный способ хранить правила в файле отдельно от конфигурации.

.kodarules

Отвечай на русском языке.
Используй pnpm для установки зависимостей.
Не коммить изменения без явного запроса.

Отличия от блока rules в конфигурации:

всё содержимое файла — одно правило без структуры YAML;
правило из .kodarules добавляется первым, раньше правил из блока rules;
в интерфейсе такое правило отображается как «Правила проекта»;
редактирование открывает сам файл, а не форму в интерфейсе;
отключить или удалить правило .kodarules из интерфейса нельзя — нужно редактировать или удалять сам файл.

.kodarules — это правило, а не файл инструкций проекта. Оно попадает в блок <important_rules>, как правила из конфигурации, и действует во всех режимах, а не только в агенте.

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

Включение и отключение правил¶

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

Это удобно, если правило временно не нужно, но вы не хотите удалять его окончательно.

Правила проекта¶

v0.6.2

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

В каждой директории Koda ищет файлы в таком порядке:

KODA.md
AGENTS.md
agents.md
AGENT.md

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

Файл в корне рабочей области¶

v0.5.0

Корневой файл добавляется в системное сообщение только в режиме агента и оборачивается как контекст проекта.

KODA.md

# Инструкции проекта

Проект использует pnpm.
Перед изменением API проверьте типы в packages/api.
Новые компоненты создавайте по паттернам из src/components.

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

Файл KODA.md можно создать или обновить командой /kodamd в режиме агента. Агент проанализирует проект и подготовит основу для будущих взаимодействий. Подробнее — в разделе Слеш-команды.

Инструкции во вложенных директориях¶

v1.2.7

Правила можно разложить по подкаталогам — например, отдельные соглашения для фронтенда и бэкенда. Такие файлы не загружаются все сразу: Koda подключает их по мере работы агента с файлами и директориями.

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

Например, если в проекте есть src/ui/KODA.md, то при чтении src/ui/Button.tsx агент получит и корневые правила, и правила из src/ui.

Перед первой правкой в новой области

Если агент пытается изменить или создать файл в директории, инструкции которой ещё не были загружены, инструмент не станет менять файл. Он вернёт ошибку File was not changed и попросит сначала прочитать применимые файлы инструкций. После чтения агент повторит правку — уже с учётом правил. Это защищает от изменений «вслепую», но не проверяет, насколько точно агент соблюдает текст правил.

Отключение проектных инструкций¶

Если нужно временно отключить файл инструкций, добавьте в его начало префикс # [DISABLED].

KODA.md

# [DISABLED] Инструкции проекта

Эти инструкции временно не будут добавляться в контекст агента.

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

Ограничения размера¶

Инструкции расходуют тот же лимит, что и результат чтения файла, — 2000 строк или 50 КиБ. Если файл кода и инструкции не помещаются вместе, Koda сокращает результат чтения и подсказывает, с какого места продолжить чтение через offset. Слишком большой файл инструкций передаётся началом с пометкой Project instruction truncated; остальное можно прочитать тем же способом. Подробнее об ограничении вывода — в разделе «Большой вывод инструментов».

Как правила попадают в запрос¶

Перед обращением к модели Koda собирает системное сообщение в несколько этапов:

Берёт базовое системное сообщение для текущего режима.
Добавляет базовое системное сообщение выбранной модели, если оно задано.
Проходит по списку правил: сначала из .kodarules, затем из блока rules.
Пропускает отключённые правила.
Проверяет условия if.
Добавляет подходящие правила в блоки <important_rules>.
В режиме агента добавляет корневой файл инструкций проекта в блок <project_context>.
По ходу работы подключает инструкции вложенных директорий к результатам чтения файлов и просмотра директорий.

Упрощённо итоговый системный контекст выглядит так:

Базовое системное сообщение режима

<important_rules>
Не меняй публичные API без отдельного согласования.
</important_rules>

<project_context>
Содержимое KODA.md или другого файла инструкций проекта
</project_context>

Чем больше правил и проектного контекста вы добавляете, тем больше токенов занимает системное сообщение. Оставляйте там только инструкции, которые действительно должны применяться регулярно.

Хорошие практики¶

Пишите конкретно¶

✅ Хорошо:

При изменении публичных TypeScript-интерфейсов обновляй связанные типы и тесты.

❌ Слишком расплывчато:

Пиши хороший код.

Не дублируйте одно и то же¶

Если инструкция уже есть в KODA.md или .kodarules, не обязательно повторять её отдельным правилом. Дубли могут сделать поведение модели менее предсказуемым.

Разделяйте глобальные и проектные инструкции¶

Глобальные правила храните в rules. Проектные детали, команды и архитектурные заметки лучше держать в KODA.md, .kodarules или совместимом файле инструкций.

Делайте правила короткими¶

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