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

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

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

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

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

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

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

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

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

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

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

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

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

Файл .kodarules¶

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

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

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

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

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

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

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

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

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

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

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

1. KODA.md
2. AGENTS.md
3. agents.md
4. AGENT.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

✅ Хорошо:

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

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

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

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

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

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

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

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

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