84 lines
8.4 KiB
Markdown
84 lines
8.4 KiB
Markdown
# 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. Прочитать [`targets/DEVELOPMENT_ROADMAP.md`](targets/DEVELOPMENT_ROADMAP.md) и соответствующий subsystem plan из `targets/roadmap/`.
|
|
4. Прочитать [`docs/README.md`](docs/README.md) и связанные с задачей нормативные документы.
|
|
5. Прочитать обязательный [`docs/CODING_STANDARD.md`](docs/CODING_STANDARD.md): явные имена и KISS имеют приоритет.
|
|
6. Прочитать обязательный [`docs/DOCUMENTATION_STANDARD.md`](docs/DOCUMENTATION_STANDARD.md) и определить, какие API docs, module spec и diagrams затрагивает задача.
|
|
7. Для renderer-задач прочитать [`RENDER.md`](RENDER.md).
|
|
8. Проверить рабочее дерево и не перезаписывать чужие изменения.
|
|
9. Перед созданием сложной подсистемы или добавлением dependency проверить [`docs/TOOLING_CATALOG.md`](docs/TOOLING_CATALOG.md), зарегистрировать найденные готовые решения и провести bounded evaluation вместо немедленного вендоринга.
|
|
10. При командной работе прочитать [`docs/TEAM_WORKFLOW.md`](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 -->` — все критерии и проверки выполнены.
|
|
|
|
Завершение подтверждается второй меткой:
|
|
|
|
```text
|
|
<!-- 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 созданы или обновлены.
|