From ea01681c81e387cac1f0a08d25bfc8b3a608a5c8 Mon Sep 17 00:00:00 2001
From: mzhoot <artrades_kz@mail.ru>
Date: Sun, 17 May 2026 12:58:42 +0300
Subject: [PATCH] AGENTS.md

---
 AGENTS.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..59a45a3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,43 @@
+
+# AGENTS.md
+
+## Правила для агентов и участников проекта КВС
+
+КВС — русскоязычный ассемблер x86-64, написанный на Python, генерирующий ELF-файлы.
+
+### Ограничения
+
+1. **Никаких регулярных выражений (`re`).**  
+   Разбор строк — только посимвольно, через циклы и сравнения. Это делает код переносимым на другие языки без изменений логики.
+
+2. **Минимум ООП.**
+   - Существующие классы (`Pass1`, `Pass2`, `Parser`) **не переписывать** без явной команды. Они работают — не трогай.
+   - Новые классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные.
+
+3. **Изоляция логики важнее DRY.**  
+   Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: `kvs_pass2_encoder_mutsize.py` содержит копии функций из `kvs_pass2_encoder_fixsize.py`, чтобы не импортировать их и оставаться полностью самостоятельным.
+
+4. **Русские названия везде, кроме ELF.**  
+   Внутри компилятора — русские имена секций, директив, регистров. В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`).
+
+### Структура проекта
+
+```
+kvs_lexer.py          — лексер (исходник → токены)
+kvs_parser.py         — парсер (токены → AST)
+kvs_pass1.py          — первый проход (размеры секций, адреса меток)
+kvs_pass2.py          — второй проход (AST + pass1 → CSV с байтами)
+kvs_builder.py        — сборщик ELF (CSV + pass1 → исполняемый файл)
+kvs_data.py           — общие константы и данные
+kvs_build.py          — главный сборочный скрипт (вызывает всё по порядку)
+kvs_pass2_encoder_fixsize.py  — кодировщик инструкций фиксированного размера
+kvs_pass2_encoder_mutsize.py  — кодировщик инструкций переменного размера + диспетчер
+kvs_pass2_encoder.py          — реэкспорт из fixsize + mutsize (совместимость)
+```
+
+### Стиль
+
+- Комментарии и документация на русском.
+- Имена функций — `snake_case`, осмысленные.
+- Размеры инструкций — явные числа, никаких `suffix`-трюков.
+- Каждая директива резервирования — отдельная ветка `if`, а не словарь.