kvs/AGENTS.md

```markdown
# AGENTS.md

## Правила для агентов и участников проекта КВС

КВС — русскоязычный ассемблер x86-64, написанный на Python, генерирующий ELF-файлы.

### Ограничения

1. **Никаких регулярных выражений (`re`).**  
   Разбор строк — только посимвольно, через циклы и сравнения. Это делает код переносимым на другие языки без изменений логики.

2. **Минимум ООП.**
   - Классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные.

3. **Изоляция логики важнее DRY.**  
   Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: кодировщики фиксированного и переменного размера содержат копии функций, чтобы не импортировать их и оставаться полностью самостоятельными.

4. **Русские названия везде, кроме ELF.**  
   - Внутри компилятора — русские имена секций, директив, регистров, инструкций.
   - В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`).
   - Имена файлов, переменных и функций в коде — **английские** (кроме русифицированных скриптов верхнего уровня).

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

```
квс_сборка.py               — Главный сборочный скрипт (запускает все проходы по порядку)
квс_лексер.py               — Лексер (исходник → токены)
квс_парсер.py               — Парсер (токены → AST)
квс_проход1.py              — Первый проход: генерация CSV с заглушками для неизвестных меток
квс_проход2.py              — Второй проход: разрешение меток (замена заглушек на реальные адреса)
квс_проход3.py              — Третий проход: подстановка констант в команды
квс_проход4.py              — Четвёртый проход: перекодирование инструкций с подставленными значениями
квс_проход5.py              — Пятый проход: генерация корректных таблиц секций для совместимости с toolchain
квс_проход6.py              — Шестой проход: постобработка и сортировка CSV для визуального анализа
квс_финсбор.py              — Сборщик ELF (CSV → исполняемый файл)
kvs_data.py                 — Общие константы и данные (регистры, инструкции, функции)
kvs_encoder.py              — Фасад кодировщика (реэкспорт из fixsize + mutsize)
kvs_encoder_fixsize.py      — Кодировщик инструкций фиксированного размера
kvs_encoder_mutsize.py      — Кодировщик инструкций переменного размера + диспетчер
```

### Русификация

**Русифицированы (пользовательская часть):**
- Имена скриптов верхнего уровня: `квс_*.py` (кроме `квс_финсбор.py`, `квс_сборка.py`)
- Комментарии и документация в большинстве файлов
- Пользовательский синтаксис: инструкции, регистры, директивы

**Остались на английском:**
- Имена файлов: `kvs_data.py`, `kvs_encoder.py`, `kvs_encoder_fixsize.py`, `kvs_encoder_mutsize.py`
- Внутренние имена переменных, констант и функций внутри этих файлов
- Технические идентификаторы в коде (ключи словарей, имена функций)

### Стиль

- Комментарии и документация — на русском (в русифицированных файлах).
- Имена функций — `snake_case`, осмысленные.
- Размеры инструкций — явные числа, никаких `suffix`-трюков.
- Каждая директива резервирования — отдельная ветка `if`, а не словарь.
- Для файлов, оставшихся на английском (`kvs_*.py`), комментарии допустимы на русском или английском — по усмотрению автора.

### Важно

- `kvs_build.py` переименован в `квс_сборка.py` — используйте актуальное имя.
- `kvs_builder.py` переименован в `квс_финсбор.py`.
- Все проходы (`kvs_pass*.py`) переименованы в `квс_проход*.py`.
- Кодировщики и `kvs_data.py` **не переименованы** — их имена остались на английском.
```