архитектура и цели для агентов

2026-07-10 10:28:37 +04:00
parent f561e52aa9
commit 93bfe114c0
46 changed files with 2826 additions and 55 deletions
@@ -0,0 +1,65 @@
+# OpenWC Agent Guide
+
+Эти инструкции действуют для всего репозитория, кроме поддеревьев с собственным `AGENTS.md`.
+
+## Миссия
+
+Реализовать клиент World of Warcraft 3.3.5a build 12340 с максимально точным поведением оригинального клиента (`1:1`) и расширяемый набор инструментов авторинга внутри Godot Editor. TrinityCore/AzerothCore являются целевыми server backends. Улучшения допускаются как отдельные настраиваемые режимы; они НЕ ДОЛЖНЫ незаметно менять профиль совместимости `Blizzlike335`.
+
+## Обязательное чтение перед работой
+
+Каждый агент ДОЛЖЕН:
+
+1. Прочитать [`targets/README.md`](targets/README.md).
+2. Прочитать файл текущей цели, указанный там как `Current target`.
+3. Прочитать [`docs/README.md`](docs/README.md) и связанные с задачей нормативные документы.
+4. Для renderer-задач прочитать [`RENDER.md`](RENDER.md).
+5. Проверить рабочее дерево и не перезаписывать чужие изменения.
+
+Если задача пользователя противоречит target-порядку, прямое указание пользователя имеет приоритет, но агент обязан сохранить архитектурные границы и отметить влияние на roadmap.
+
+## Правила выполнения целей
+
+- Работать только над текущей целью или явно указанной пользователем задачей.
+- Не начинать следующий milestone, пока текущий не имеет доказательств завершения.
+- Не объявлять совместимость `1:1` без fixture, сравнения с оригинальным клиентом или подтверждённого protocol/server behavior.
+- Не смешивать render, gameplay, UI, network и server-data adapters.
+- Не добавлять прямую запись в production DB.
+- Интерактивный authoring UI реализуется только через Godot `EditorPlugin`.
+- Любой новый формат, публичный контракт или несовместимое решение требует обновления документации и при необходимости ADR.
+- Исправление дефекта должно получать regression test, когда это технически возможно.
+
+## Метки состояния
+
+В каждом `targets/*.md` присутствует ровно одна метка:
+
+- `<!-- OPENWC_TARGET:OPEN -->` — цель ещё не начата.
+- `<!-- OPENWC_TARGET:ACTIVE -->` — единственная текущая цель.
+- `<!-- OPENWC_TARGET:BLOCKED -->` — продолжение невозможно; причина записана в Evidence/Blockers.
+- `<!-- OPENWC_TARGET:DONE -->` — все критерии и проверки выполнены.
+
+Завершение подтверждается второй меткой:
+
+```text
+<!-- OPENWC_TARGET_DONE:M00:<git-commit-or-worktree>:YYYY-MM-DD -->
+```
+
+Правила метки `DONE`:
+
+1. Все обязательные checklist-пункты отмечены.
+2. Выполнены команды Verification.
+3. В Evidence записаны команды, результаты и изменённые файлы.
+4. Не осталось обязательных незакрытых пунктов или скрытых заглушек.
+5. Обновлены `targets/README.md` и матрица функций, если применимо.
+
+Агент НЕ ДОЛЖЕН ставить `DONE` только потому, что код компилируется. Если пользователь явно принял частичный результат, статус остаётся `ACTIVE`, а принятое ограничение записывается в Evidence.
+
+## Формат отчёта агента
+
+Финальный отчёт должен содержать:
+
+- Target ID и статус;
+- что изменено;
+- какие проверки выполнены;
+- fidelity evidence для поведения 3.3.5a;
+- оставшиеся риски или следующий незакрытый checklist item.