Skip to content

AGENTS.md

Latest commit

 

History

History
167 lines (141 loc) · 13.6 KB

AGENTS.md

File metadata and controls

167 lines (141 loc) · 13.6 KB
Raw

AGENTS Rules

AGENTS.md, документ активной роли, его явно указанные процедуры и, для ролей с правом менять код, CODING_RULES.md — единственный источник процессных правил проекта. Добавлять CI-guards для их enforcement запрещено. prompt.md и report.md — task/handoff-артефакты, а не замена базовым инструкциям.

Выбор роли

Сначала определи роль текущей сессии и полностью прочти соответствующий файл:

  • Ревьювер-архитектор — Codex, который сначала принимает или отклоняет результат итерации, затем при полном принятии выбирает следующую задачу. Прочти REVIEWER.md: он направит в REVIEW.md для ревью кода или, после принятого вердикта, в PLANNING.md для постановки задачи. Не читай IMPLEMENTER.md, SUBAGENT.md и CODING_RULES.md, кроме задачи по изменению самих process-документов.
  • Имплементер — агент, которому ревьювер передал корневой prompt.md для research, implementation или correction. Прочти IMPLEMENTER.md, CODING_RULES.md, затем prompt.md. Каждый новый prompt.md для этой роли начинается фразой: Ты имплементер, твои базовые инструкции записаны в IMPLEMENTER.md.
  • Сабагент — агент, получивший ограниченную подзадачу от имплементера. Прочти SUBAGENT.md и CODING_RULES.md. Не читай REVIEWER.md, REVIEW.md, PLANNING.md, IMPLEMENTER.md, prompt.md или report.md: весь необходимый контекст обязан содержаться в сообщении задачи.

Если роль уже явно названа координатором, не переопределяй её по характеру работы. Один агент не совмещает роли внутри этапа.

Цель проекта

  • Цель — полноценная, наблюдаемо совместимая с PUC Lua реализация, а не subset. Отсутствующий тип, API или механизм реализуется архитектурно, а не имитируется другим типом или неверной заглушкой.
  • PUC Lua задаёт семантику, модель владения и runtime-инварианты. Не требуется построчный перевод C: реализация должна быть идиоматичной для Zig (tagged union, slices, allocators, comptime и актуальные Zig API).
  • Между локальным guard/fast-path и общим PUC-подобным механизмом выбирай архитектурное решение, даже если оно требует каскадного изменения сигнатур и всех call sites. Нельзя маскировать RuntimeError как OOM ради меньшего diff.
  • Отступление от PUC допустимо только с зафиксированным объяснением: почему PUC-механизм здесь хуже, какое решение выбрано и как сохраняется parity.
  • Каждый законченный этап должен убрать костыль или закрыть реальный parity blocker, не ухудшая скрытно корректность или архитектуру. Для затрагивающего hot path этапа изменение производительности измеряется и раскрывается, но для архитектурной миграции без цели ускорения допустима обоснованная регрессия: сохранение прежнего уровня не является автоматическим acceptance gate.
  • Проект использует актуальный установленный zig. Для Zig-facing кода нельзя обходить изменения stdlib через libc (fopen, fread, argv-хаки), если Zig предоставляет нативный интерфейс.

Общие архитектурные принципы

  • У изменяемого состояния должен быть один канонический владелец. Кэши и views допустимы только с явным lifetime и правилами синхронизации.
  • Fallible publication строится как reserve/prepare -> allocate -> initialize -> infallible commit; rollback удаляет все registrations, откатывает accounting и уничтожает объект в обратном порядке.
  • Error kind/status и error object сохраняются через protected boundary, continuation и resume. Ошибку нельзя распознавать по тексту или превращать в другой класс ради удобства интерфейса.
  • Raw pointer/slice не переживает realloc или освобождение владельца. Любой GC-visible payload имеет доказанный root/barrier на всём окне жизни.
  • Утверждённый архитектурный roadmap важнее случайных локальных findings. Нельзя расширять legacy-механизм, который ближайший milestone должен удалить, или откладывать архитектурный blocker ради количества простых чекбоксов.
  • Pre-existing проблема не теряется, но не перехватывает этап автоматически. Она меняет текущий scope, только если делает продолжение небезопасным, обесценивает evidence, ломает обязательный gate или является предпосылкой утверждённого milestone.

Запреты

Нельзя менять семантику по имени файла, чанка, теста, функции или переменной, диапазону строк, debug-метаданным либо тексту ошибки. Запрещены test-specific *_probe, synthetic_*, special_case_*, *_workaround, новые replay-поля для coroutine-семантики и benchmark-specific ветки без настоящего семантического класса PUC.

Нельзя скрывать расхождения изменением upstream-тестов, нормализацией вывода, --engine=ref, _soft, _port или другим harness-обходом. Совместимость достигается исправлением parser/codegen/IR/VM/runtime или stdlib.

Временный compatibility-слой допустим только в том же этапе, где определены его критерий и срок удаления. Диагностика должна быть default-off, не участвовать в runtime-ветвлении и не менять observable behavior; временные traces и probes удаляются до завершения этапа.

Findings: общий словарь

Severity определяется эффектом, а не размером исправления:

  • BLOCKER — неверная семантика валидной Lua-программы, crash, потеря continuation, UAF/corruption/double-free/потеря данных, провал обязательного gate или недостоверность заявленного финального измерения.
  • HIGH — общий инвариант заменён special case, дублировано mutable ownership, stale evidence определяет следующую фазу либо принят серьёзный необъяснённый perf regression, противоречащий цели или явно утверждённому бюджету этапа.
  • MEDIUM — stale/incomplete provenance, вводящий в заблуждение отчёт или комментарий, неполная проверка либо правдоподобная, но не доказанная проблема.
  • LOW — механическая чистота, naming и необязательная документация.

Каждому finding назначается одна судьба:

  • FIX-NOW — внесён этапом, нарушает его инвариант, ломает gate или создаёт crash/corruption в изменённом пути;
  • ARCHITECTURAL-BACKLOG — относится к утверждённому будущему milestone;
  • ORDINARY-BACKLOG — реальная, но не архитектурно приоритетная проблема;
  • UNCONFIRMED — гипотеза с уже выполненными проверками и следующим решающим экспериментом.

Нерешённый BLOCKER/HIGH становится отдельным открытым пунктом STATUS.md, но это само по себе не назначает его следующей задачей. Сабагент не меняет STATUS.md: он передаёт finding координатору для интеграции.

Handoff и владение файлами

  • prompt.md принадлежит ревьюверу как подробное задание имплементеру: после принятия итерации его готовят по PLANNING.md, а при непринятии — как ограниченную correction/research-задачу по REVIEW.md. В обоих случаях он содержит утверждённое направление, scope, evidence, stop conditions и acceptance.
  • report.md принадлежит имплементеру как подробный ответ ревьюверу: реально выполненные изменения, проверки, findings, regressions, blockers и residuals.
  • После передачи ревьюверу report.md является неизменяемым выводом завершённой итерации, а не документом для согласования. Неточности отчёта исправляются в выводах ревьювера и следующем prompt.md; отдельная задача на переписывание, нормализацию или дополнение прошлого report.md запрещена.
  • Только координатор-имплементер атомарно заменяет корневой report.md. Сабагенты не читают и не изменяют ни prompt.md, ни report.md. Следующая итерация заменяет корневой отчёт только своим новым выводом после содержательной research/implementation/correction работы.
  • Чат не заменяет handoff-файлы. Результаты сабагентов передаются координатору сообщением и не требуют собственного report.md.

Правила запуска тестов и скриптов оценки производительности

  • Тесты и скрипты оценки производительности могут исполнятся значительное количество времени. По возможности нужно отдавать предпочтение меньшему числу запусков тестов. Например, неправильно: 
    $ zig build test | grep foo
$ zig build test | grep bar
    Правильно: 
    $ zig build test > /tmp/working_dir/test_output
$ grep foo /tmp/working_dir/test_output
$ grep bar /tmp/working_dir/test_output
    Само собой исключением являются ситуации когда нужно выловить флуктуации в запусках

Worktree

  • Сначала установи состояние worktree и принадлежность незакоммиченных файлов. Чужие изменения сохраняются; несвязанные правки и косметический refactor запрещены.
  • Имплементер и сабагент при изменении и написании кода следуют CODING_RULES.md.
  • Документальная правка требует проверки diff, ссылок и согласованности, но не runtime battery. Правка только process-документов (AGENTS.md, REVIEWER.md, REVIEW.md, PLANNING.md, IMPLEMENTER.md, SUBAGENT.md, CODING_RULES.md) не является development-итерацией и не требует искусственного пункта STATUS.md.