Файл `.kodarules`¶

Файл .kodarules — это механизм определения системных правил для LLM в Koda. Он позволяет задавать инструкции, которым должна следовать модель при генерации ответов, редактировании кода и работе в режиме агента.

Обзор¶

.kodarules используется для:

Определения стандартов кода — стиль, соглашения, лучшие практики
Задания рабочих процессов — процессы разработки, тестирования, документирования
Указания предпочтений — предпочтительные паттерны, библиотеки, подходы
Ограничения поведения модели — что можно/нельзя делать
Контекстуализации проекта — специфика проекта, доменные знания

Расположение файлов¶

Koda ищет файл .kodarules в корне каждого workspace:

Уровень	Путь	Описание
Workspace	`.kodarules` в корне проекта	Применяется ко всему проекту

Примечание: В отличие от .kodaignore, .kodarules не поддерживает глобальный файл или вложенные файлы. Все правила определяются в одном файле в корне проекта.

Формат файла¶

.kodarules — это текстовый файл с инструкциями в свободной форме. Поддерживает:

Обычный текст
Markdown-разметку
Списки и заголовки
Примеры кода
Условные правила (через if)

Базовый пример¶

# Стандарты кода для этого проекта

1. Всегда используй TypeScript для нового кода
2. Пиши unit-тесты для всех новых функций
3. Следуй принципам SOLID
4. Используй функциональный стиль где возможно
5. Добавляй JSDoc комментарии для публичных API

# Стиль кода

- Используй 2 пробела для отступов
- Максимальная длина строки — 100 символов
- Названия переменных в camelCase
- Названия классов в PascalCase
- Названия констант в UPPER_SNAKE_CASE

# Тестирование

- Используй Jest для unit-тестов
- Покрытие кода должно быть не менее 80%
- Мокай внешние зависимости
- Тестируй крайние случаи

Интеграция с config.yaml¶

Правила из .kodarules автоматически добавляются к правилам из config.yaml:

~/.koda/config.yaml

rules:
  - Always use TypeScript
  - Write tests for new code
  - Follow company style guide

Приоритет:

Правила из .kodarules (workspace-уровень)
Правила из config.yaml (глобальный/пользовательский уровень)
Правила по умолчанию (из моделей)

Все правила объединяются и передаются в системное сообщение LLM.

Условные правила¶

Koda поддерживает условные правила с помощью свойства if в YAML-конфигурации. Это позволяет активировать правила только при определённых условиях.

Синтаксис условий¶

Условия используют выражения с поддержкой:

glob(pattern) — проверка соответствия пути шаблону
contains(str, substr) — проверка вхождения строки
current.model.model — текущая модель

Примеры условий¶

По типу файла¶

rules:
  - name: TypeScript Rules
    if: ${{ glob("**/*.ts") }}
    rule: |
      - Use strict TypeScript mode
      - Define explicit return types
      - Avoid 'any' type

По модели¶

rules:
  - name: Claude-specific
    if: ${{ current.model.model == "claude-3-7-sonnet" }}
    rule: |
      - Think step by step
      - Provide detailed explanations
      - Use chain of thought reasoning

По содержимому¶

rules:
  - name: API Rules
    if: ${{ contains(current.file, "api") }}
    rule: |
      - Validate all inputs
      - Return proper HTTP status codes
      - Document API endpoints

Комбинированные условия¶

rules:
  - name: Frontend Rules
    if: ${{ glob("**/*.tsx") && glob("src/**") }}
    rule: |
      - Use React hooks
      - Follow component composition
      - Avoid inline styles

Форматирование правил¶

Заголовки и секции¶

Используйте заголовки для организации правил:

# Архитектура

## Слои приложения

1. Presentation Layer (React components)
2. Business Logic Layer (services, hooks)
3. Data Layer (API clients, storage)

## Зависимости

- Зависимости направлены внутрь
- Внешние слои не зависят от внутренних

Списки¶

Используйте нумерованные и маркированные списки:

# Обязательные требования

1. Все функции должны иметь типы
2. Все компоненты должны быть функциональными
3. Все API вызовы должны обрабатывать ошибки

# Рекомендации

- Используй деструктуризацию
- Избегай мутаций
- Предпочитай композицию наследованию

Примеры кода¶

Добавляйте примеры для иллюстрации:

# Правильный стиль функций

✅ Хорошо:
const getUser = async (id: string): Promise<User> => {
  const response = await api.get(`/users/${id}`);
  return response.data;
};

❌ Плохо:
async function getUser(id) {
  return await api.get(`/users/${id}`).then(r => r.data);
}

Таблицы¶

Используйте таблицы для сравнений:

# Сравнение подходов

| Критерий | Классы | Функции | Хуки |
|----------|--------|---------|------|
| Переиспользование | Низкое | Среднее | Высокое |
| Тестируемость | Средняя | Высокая | Высокая |
| Сложность | Высокая | Низкая | Средняя |

Практические примеры¶

Для веб-разработки (React/TypeScript)¶

# React/TypeScript Project Rules

## Общие принципы

1. Используй функциональные компоненты с хуками
2. Пиши на TypeScript со строгой типизацией
3. Следуй принципам SOLID
4. Избегай мутаций состояния

## Стиль кода

- Отступы: 2 пробела
- Кавычки: одинарные в JSX, двойные в строках
- Максимальная длина строки: 100 символов
- Названия компонентов: PascalCase
- Названия хуков: camelCase с префиксом 'use'

## Компоненты

- Каждый компонент в отдельном файле
- Имя файла должно совпадать с именем компонента
- Экспортируй компоненты как default
- Используй TypeScript interfaces для props
- Добавляй displayName для отладки

## Управление состоянием

- Используй React Context для глобального состояния
- Применяй useReducer для сложной логики
- Избегай prop drilling
- Кэшируй данные с React Query

## Тестирование

- Пиши unit-тесты для всех компонентов
- Используй React Testing Library
- Тестируй поведение, не реализацию
- Покрытие: минимум 80%

## Производительность

- Мемоизируй тяжелые вычисления с useMemo
- Кэшируй функции с useCallback
- Ленивая загрузка компонентов
- Оптимизируй ре-рендеры

## Доступность

- Используй семантические HTML элементы
- Добавляй aria-атрибуты
- Поддерживай навигацию с клавиатуры
- Тестируй с скринридерами

Для Python-проектов¶

# Python Project Rules

## Общие принципы

1. Следуй PEP 8
2. Используй type hints
3. Пиши документацию
4. Тестируй код

## Стиль кода

- Отступы: 4 пробела
- Максимальная длина строки: 88 символов (Black)
- Названия переменных: snake_case
- Названия классов: PascalCase
- Названия констант: UPPER_CASE

## Структура проекта

src/
├── __init__.py
├── main.py
├── services/
├── models/
├── utils/
└── tests/

## Типизация

- Используй аннотации типов для всех функций
- Применяй Optional для nullable значений
- Используй Union для множественных типов
- Добавляй TypeAlias для сложных типов

## Документация

- Docstrings для всех публичных функций
- Формат: Google style или NumPy style
- Описывай параметры и возвращаемые значения
- Добавляй примеры использования

## Тестирование

- Используй pytest
- Пиши тесты для всех функций
- Мокай внешние зависимости
- Покрытие: минимум 90%

## Обработка ошибок

- Используй специфичные исключения
- Логируй ошибки с контекстом
- Избегай bare except
- Применяй контекстные менеджеры

Для бэкенд-разработки (Node.js/Express)¶

# Backend API Rules

## Архитектура

1. Следуй REST принципам
2. Разделяй логику по слоям
3. Используй dependency injection
4. Применяй middleware для кросс-задач

## Структура проекта

src/
├── controllers/    # Обработка запросов
├── services/       # Бизнес-логика
├── models/         # Данные и ORM
├── middleware/     # Промежуточное ПО
├── routes/         # Маршруты
├── utils/          # Утилиты
└── tests/          # Тесты

## API Design

- Используй глаголы для действий
- Применяй множественное число для ресурсов
- Возвращай правильные HTTP статусы
- Версионируй API (/api/v1/)

## Безопасность

- Валидируй все входные данные
- Используй HTTPS
- Применяй rate limiting
- Хэшируй пароли (bcrypt)
- Используй JWT для аутентификации

## Логирование

- Логируй все запросы и ответы
- Используй структурированное логирование
- Не логируй чувствительные данные
- Настрой уровни логирования

## База данных

- Используй миграции
- Применяй индексы для частых запросов
- Избегай N+1 проблем
- Кэшируй частые запросы

## Тестирование

- Unit-тесты для сервисов
- Integration-тесты для API
- Мокай внешние сервисы
- Покрытие: минимум 85%

Для мобильных проектов (React Native)¶

# React Native Project Rules

## Общие принципы

1. Используй функциональные компоненты
2. Пиши на TypeScript
3. Следуй гайдлайнам платформ
4. Оптимизируй производительность

## Стиль кода

- Отступы: 2 пробела
- Названия компонентов: PascalCase
- Названия файлов: PascalCase.tsx
- Стили: StyleSheet.create()

## Навигация

- Используй React Navigation
- Разделяй навигацию по фичам
- Обрабатывай deep links
- Сохраняй состояние навигации

## Управление состоянием

- Используй Zustand или Redux Toolkit
- Нормализуй состояние
- Применяй селекторы
- Избегай глобального состояния

## Производительность

- Мемоизируй компоненты
- Используй FlatList для списков
- Ленивая загрузка изображений
- Оптимизируй ре-рендеры

## Платформенные особенности

- Учитывай различия iOS/Android
- Используй Platform.OS
- Тестируй на обоих платформах
- Следуй Human Interface Guidelines

## Тестирование

- Unit-тесты для логики
- Component-тесты для UI
- E2E тесты для критических путей
- Используй Detox для E2E

Для проектов машинного обучения¶

# ML Project Rules

## Общие принципы

1. Воспроизводимость экспериментов
2. Версионирование данных и моделей
3. Документирование решений
4. Тестирование кода

## Структура проекта

project/
├── data/
│   ├── raw/          # Исходные данные
│   ├── processed/    # Обработанные данные
│   └── external/     # Внешние данные
├── notebooks/        # Jupyter ноутбуки
├── src/
│   ├── data/         # Загрузка и обработка
│   ├── features/     # Feature engineering
│   ├── models/       # Модели и обучение
│   └── utils/        # Утилиты
├── experiments/      # Эксперименты
├── models/           # Сохранённые модели
└── tests/            # Тесты

## Эксперименты

- Логируй все параметры
- Сохраняй метрики
- Версионируй модели (MLflow, DVC)
- Документируй результаты

## Данные

- Не изменяй исходные данные
- Создавай пайплайны обработки
- Валидируй данные
- Документируй схему данных

## Модели

- Разделяй train/validation/test
- Используй кросс-валидацию
- Сравнивай с baseline
- Интерпретируй результаты

## Код

- Пиши модульный код
- Тестируй функции
- Используй type hints
- Документируй API

## Развёртывание

- Контейнеризируй модели
- Создавай API для инференса
- Мониторь производительность
- Настрой CI/CD

Взаимодействие с другими функциями¶

Chat¶

Правила из .kodarules применяются ко всем запросам в чате:

Пользователь: "Рефактори этот код"

→ LLM учитывает правила из .kodarules:
  - Стиль кода
  - Требования к тестам
  - Принципы архитектуры

Edit¶

При редактировании кода правила влияют на предлагаемые изменения:

Пользователь: "Добавь обработку ошибок"

→ LLM применяет правила:
  - Типы исключений
  - Логирование
  - Паттерны обработки

Agent¶

В режиме агента правила направляют автономную работу:

Агент: "Создам новый компонент"

→ Следует правилам:
  - Структура файлов
  - Стиль кода
  - Требования к тестам

Отладка¶

Проверка применения правил¶

Откройте чат Koda
Задайте вопрос, связанный с правилом
Проверьте, учитывает ли модель правило

Логирование¶

Koda добавляет правила в системное сообщение:

System message includes:
<important_rules>
[содержимое .kodarules]
</important_rules>

Тестирование правил¶

Создайте тестовый сценарий:

# В .kodarules
- Always use TypeScript

# Тест
Запрос: "Создай функцию для сложения чисел"

Ожидаемый ответ:
const add = (a: number, b: number): number => a + b;

Миграция с Continue¶

Если вы переходите с Continue на Koda:

.continuerules → .kodarules
Синтаксис полностью совместим
Все правила переносятся автоматически

kodarules rules правила системные инструкции LLM

Файл `.kodarules`¶

Обзор¶

Расположение файлов¶

Формат файла¶

Базовый пример¶

Интеграция с config.yaml¶

Условные правила¶

Синтаксис условий¶

Примеры условий¶

По типу файла¶

По модели¶

По содержимому¶

Комбинированные условия¶

Форматирование правил¶

Заголовки и секции¶

Списки¶

Примеры кода¶

Таблицы¶

Практические примеры¶

Для веб-разработки (React/TypeScript)¶

Для Python-проектов¶

Для бэкенд-разработки (Node.js/Express)¶

Для мобильных проектов (React Native)¶

Для проектов машинного обучения¶

Взаимодействие с другими функциями¶

Chat¶

Edit¶

Agent¶

Рекомендации¶

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

Чего избегать¶

Отладка¶

Проверка применения правил¶

Логирование¶

Тестирование правил¶

Миграция с Continue¶

Файл .kodarules¶

Обзор¶

Расположение файлов¶

Формат файла¶

Базовый пример¶

Интеграция с config.yaml¶

Условные правила¶

Синтаксис условий¶

Примеры условий¶

По типу файла¶

По модели¶

По содержимому¶

Комбинированные условия¶

Форматирование правил¶

Заголовки и секции¶

Списки¶

Примеры кода¶

Таблицы¶

Практические примеры¶

Для веб-разработки (React/TypeScript)¶

Для Python-проектов¶

Для бэкенд-разработки (Node.js/Express)¶

Для мобильных проектов (React Native)¶

Для проектов машинного обучения¶

Взаимодействие с другими функциями¶

Chat¶

Edit¶

Agent¶

Рекомендации¶

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

Чего избегать¶

Отладка¶

Проверка применения правил¶

Логирование¶

Тестирование правил¶

Миграция с Continue¶

Файл `.kodarules`¶