Skip to content

AGENTS.md

Latest commit

 

History

History
121 lines (98 loc) · 10.6 KB

AGENTS.md

File metadata and controls

121 lines (98 loc) · 10.6 KB
Raw

AGENTS Rules

Этот файл фиксирует правила разработки и внесения изменений. Правила устанавливаются только здесь, без CI-guard.

Обязательное правило фиксации

  • Все ограничения и договорённости фиксируются исключительно в AGENTS.md.
  • Добавление CI-проверок (CI-guard) для принудительного контроля этих правил запрещено.

Toolchain target

  • Проект таргетит актуальную установленную версию Zig, доступную как zig.
  • Поддержка старых Zig toolchain не является обязательной целью, если это мешает чистому использованию текущих Zig API.
  • Для Zig-facing интерфейсов запрещены libc fallbacks как способ обойти изменения Zig stdlib: нельзя использовать fopen/fread/argv-хаки через libc вместо штатных Zig API.
  • Если текущий Zig предоставляет нативный интерфейс (std.process.Init, std.fs, std.Io и т.п.), агент обязан использовать его напрямую.

Жёсткие запреты

  • Запрещён match по имени файла/скрипта/чанка и диапазонам строк: любые проверки вида source_name, endsWith("coroutine.lua"), line_defined in [x..y], line-range для смены семантики выполнения.
  • Запрещены любые *_probe, synthetic_*, special_case_*, *_workaround режимы, которые активируют альтернативное поведение VM/IR только для конкретного теста/сценария.
  • Запрещены runtime-hotfix по отладочным именам: нельзя менять семантику по local_names, upvalue_names, function.name, debug.getinfo-полям, тексту сообщения ошибки, имени переменной в тесте.
  • Запрещены костыли в тестовой обвязке/harness для скрытия расхождений: нормализация вывода, удаляющая семантические различия; подмена поведения через флаги вида --engine=ref для прохождения failing-кейсов; изменение upstream-тестов как способ фикса.
  • Запрещено добавлять новые replay-ветки и replay-поля для реализации coroutine-семантики.
  • Запрещены "временные" фиксы без плана удаления: если добавлен compatibility-слой, в том же PR должен быть TODO с критерием удаления и сроком.

Разрешённая область изменений

  • Разрешены только архитектурные и семантические фиксы на уровне parser/codegen/IR/VM/runtime.
  • Разрешены изменения stdlib-реализаций, если они приближают поведение к PUC Lua.
  • Разрешены диагностические логи/трейсы только если:
    1. отключены по умолчанию,
    2. не влияют на поведение исполнения,
    3. не участвуют в ветвлении семантики.

Принцип выбора решений (PUC-first)

  • По умолчанию агент обязан выбирать путь, максимально близкий к референсной реализации PUC Lua (семантика, модель данных, инварианты runtime), даже если это требует более крупных архитектурных изменений.
  • Если есть выбор между быстрым локальным оптимизационным костылём и PUC-подобным архитектурным решением, приоритет у PUC-подобного решения.
  • Отступление от PUC-first допустимо только при явных признаках, что прямое копирование подхода PUC в нашей архитектуре ведёт к заведомо худшему решению (по корректности, сопровождаемости, сложности или perf).
  • В случае отступления агент обязан явно зафиксировать в описании шага:
    1. почему PUC-путь хуже в данном контексте,
    2. какую альтернативу выбрали,
    3. как эта альтернатива сохраняет/улучшает parity с PUC Lua.

Архитектура vs. инструменты реализации

  • "PUC-first" означает архитектурную близость: структура алгоритмов, инварианты runtime, модель данных, семантика codegen/IR/VM должны следовать PUC Lua.
  • При этом языковые инструменты реализации должны быть максимально родными для Zig (хост-языка), а не для C (языка-источника архитектуры). Компилятор Zig лучше оптимизирует идиоматичный Zig-код.
  • Например: вместо C-style tagged union (enum + union с ручным switch) использовать Zig tagged union; вместо ручного управления памятью через указатели — Zig-аллокаторы и slices; вместо #define констант — const и comptime.
  • Цель: архитектурная parity с PUC Lua + максимальная нативность для Zig toolchain.

Архитектура важнее быстрых выигрышей

  • При выборе между быстрым локальным оптимизационным выигрышем (fast-path patch, guard, workaround) и PUC-faithful архитектурным решением, приоритет — у архитектурного решения, даже если это требует больше времени и больших переработок.
  • Быстрый выигрыш допустим только как временная мера с явным TODO и планом замены на архитектурное решение в том же PR.
  • Запрещено оставлять fast-path patch как финальное решение, если существует PUC-faithful альтернатива.

Критерий принятия изменений

  • Каждый шаг должен либо:
    1. убрать один костыль, либо
    2. закрыть один реальный блокер parity.
  • После шага обязателен прогон релевантных suite и явный список: что улучшилось, какие регрессии появились.
  • Регрессии допустимы только как временная цена архитектурного шага, но не маскируются тестовыми обходами/нормализаторами.

Обновление README по фазам

  • После каждой фазы работ агент обязан обновлять README.md.
  • В обновлении README.md обязательно фиксируются:
    1. какие шаги выполнены,
    2. какие шаги закрыты,
    3. какие шаги остаются открытыми (если применимо).
  • Пропуск обновления README.md после завершения фазы считается нарушением процесса.

Итерационный прогресс (обязательно)

  • Каждая итерация разработки должна закрывать минимум один пункт (чекбокс) в README.md.
  • Итерация без закрытого пункта в README.md считается незавершённой.
  • Перед переходом к следующей итерации агент обязан явно отметить, какой именно пункт закрыт.
  • Запрещено в той же итерации добавлять новый пункт и тут же закрывать его как способ формального прогресса.
  • В каждой итерации количество открытых чекбоксов в README.md должно уменьшаться минимум на 1.
  • В конце каждой итерации обязательно необходимо выполнять регрессионное тестирование:
    1. Запускать python3 tools/testes_matrix.py -- регрессий быть не должно Запуск необходимо выполнять без _soft и _port
    2. запускать все тесты в tests/smoke/ -- они все должны выполняться
    3. Для правильного сравнения перед тестированием необходимо проводить компиляцию в режиме ReleaseFast

Стиль кода и наглядность

  • При написании кода агент обязан стремиться к наглядности: итоговый код должен быть хорошо структурированным и понятным, как в учебнике по программированию.
  • Требование наглядности не должно ухудшать производительность: запрещены рефакторинги "для красоты", если они делают runtime/IR/VM заметно медленнее.
  • По возможности функции должны сопровождаться избыточными и понятными комментариями, объясняющими не только "что", но и "почему" сделано именно так.