open-wc/AGENTS.md

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.
2. Прочитать файл текущей цели, указанный там как Current target.
3. Прочитать targets/DEVELOPMENT_ROADMAP.md и соответствующий subsystem plan из targets/roadmap/.
4. Прочитать docs/README.md и связанные с задачей нормативные документы.
5. Прочитать обязательный docs/CODING_STANDARD.md: явные имена и KISS имеют приоритет.
6. Прочитать обязательный docs/DOCUMENTATION_STANDARD.md и определить, какие API docs, module spec и diagrams затрагивает задача.
7. Для renderer-задач прочитать RENDER.md.
8. Проверить рабочее дерево и не перезаписывать чужие изменения.
9. Перед созданием сложной подсистемы или добавлением dependency проверить docs/TOOLING_CATALOG.md, зарегистрировать найденные готовые решения и провести bounded evaluation вместо немедленного вендоринга.
10. При командной работе прочитать docs/TEAM_WORKFLOW.md, проверить активные claims/draft PRs и объявить стабильный Agent ID до изменений.

Если задача пользователя противоречит 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, когда это технически возможно.
• Не писать крупную подсистему с нуля до поиска готовых libraries, reference implementations, fixtures и tooling; результат исследования фиксируется в docs/TOOLING_CATALOG.md.
• Не начинать claimed work package другого агента и не редактировать его exclusive paths без явного handoff.
• Не работать двум агентам в одном worktree. Каждый агент использует собственную ветку и clone/worktree.
• Статус milestone, Evidence и OPENWC_TARGET_DONE изменяет только назначенный интегратор.
• Каждый новый/существенно изменённый модуль обязан иметь актуальную specification в docs/modules/, inline documentation публичного API и data-flow diagram по docs/DOCUMENTATION_STANDARD.md.
• Stateful/async/cross-layer работа обязана документировать state/sequence diagram, ownership, threading, failure и recovery paths.
• Документация обновляется в том же work package, что код. Handoff без обязательной документации имеет статус только PARTIAL.
• Не сокращать имена ради краткости. Variable/function/type должен явно описывать назначение, domain context, units и coordinate space, когда они неоднозначны.
• Следовать KISS: использовать самое простое корректное решение, не вводить premature abstractions/frameworks/optimizations и изолировать неизбежную сложность.
• Имена manager, helper, utils, data, info, process, handle без точного контекста считаются design smell и требуют переименования или обоснования.

Метки состояния

В каждом исполняемом target-файле targets/[0-9][0-9]-*.md присутствует ровно одна метка. Справочные документы targets/DEVELOPMENT_ROADMAP.md и targets/roadmap/*.md меток состояния не имеют:

• <!-- OPENWC_TARGET:OPEN --> — цель ещё не начата.
• <!-- OPENWC_TARGET:ACTIVE --> — единственная текущая цель.
• <!-- OPENWC_TARGET:BLOCKED --> — продолжение невозможно; причина записана в Evidence/Blockers.
• <!-- OPENWC_TARGET:DONE --> — все критерии и проверки выполнены.

Завершение подтверждается второй меткой:

<!-- OPENWC_TARGET_DONE:M00:<git-commit-or-worktree>:YYYY-MM-DD -->

Правила метки DONE:

1. Все обязательные checklist-пункты отмечены.
2. Выполнены команды Verification.
3. В Evidence записаны команды, результаты и изменённые файлы.
4. Не осталось обязательных незакрытых пунктов или скрытых заглушек.
5. Обновлены targets/README.md и матрица функций, если применимо.
6. Публичный API, module spec, input/output tables и обязательные diagrams соответствуют фактической реализации.
7. Код соответствует docs/CODING_STANDARD.md: понятные имена, простой data flow и обоснованная сложность.

Агент НЕ ДОЛЖЕН ставить DONE только потому, что код компилируется. Если пользователь явно принял частичный результат, статус остаётся ACTIVE, а принятое ограничение записывается в Evidence.

Формат отчёта агента

Финальный отчёт должен содержать:

• Target ID и статус;
• что изменено;
• какие проверки выполнены;
• fidelity evidence для поведения 3.3.5a;
• оставшиеся риски или следующий незакрытый checklist item;
• какие API/module docs и diagrams созданы или обновлены.