344 lines
13 KiB
Markdown
344 lines
13 KiB
Markdown
# Командная разработка OpenWC
|
|
|
|
## Цель
|
|
|
|
Этот workflow позволяет нескольким людям и Codex-агентам работать параллельно, не перезаписывая изменения друг друга и не разрушая архитектурные границы. Единица параллельной работы — не milestone целиком, а ограниченный `work package`.
|
|
|
|
## Основные правила
|
|
|
|
1. Каждый агент работает в отдельном clone или Git worktree и собственной ветке.
|
|
2. Никто не разрабатывает напрямую в `master`.
|
|
3. До изменений задача получает ID, владельца, claim и список затрагиваемых путей.
|
|
4. Один work package имеет только одного активного владельца.
|
|
5. Общие contracts согласуются до параллельной реализации producers/consumers.
|
|
6. Статус milestone и `OPENWC_TARGET_DONE` изменяет только интегратор.
|
|
7. Merge выполняется только после handoff, локальных проверок и синхронизации с актуальным `master`.
|
|
|
|
## Идентификаторы
|
|
|
|
### Agent ID
|
|
|
|
Каждый человек/агент выбирает стабильный ID на весь work package:
|
|
|
|
```text
|
|
<human>-<machine>-codex
|
|
```
|
|
|
|
Примеры:
|
|
|
|
```text
|
|
sindo-main-codex
|
|
alex-laptop-codex
|
|
```
|
|
|
|
ID записывается в claim, ветке, PR/MR и handoff. Нельзя использовать просто `codex`, потому что таких агентов несколько.
|
|
|
|
### Work Package ID
|
|
|
|
```text
|
|
<TARGET>-<PROGRAM>-<SHORT-NAME>-<NNN>
|
|
```
|
|
|
|
Примеры:
|
|
|
|
```text
|
|
M01-FND-COORDS-001
|
|
M03-RND-SCHEDULER-001
|
|
M08-NET-SRP-001
|
|
M12-UIA-LUA-SPIKE-001
|
|
```
|
|
|
|
Program codes определены в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md).
|
|
|
|
## Claim protocol
|
|
|
|
Предпочтительный канал координации — issue + ранний draft PR/MR на общем Git forge. Если forge недоступен, используется отдельный файл в `coordination/claims/`, который сначала публикуется в общей ветке.
|
|
|
|
Claim marker:
|
|
|
|
```text
|
|
<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-13 -->
|
|
```
|
|
|
|
Последнее поле — дата истечения claim в UTC. Рекомендуемый срок — 48 часов; владелец продлевает его коротким status update. Истёкший claim нельзя забирать молча: сначала оставить сообщение владельцу и интегратору.
|
|
|
|
Claim содержит:
|
|
|
|
- target и work package;
|
|
- owner/agent ID;
|
|
- outcome и non-goals;
|
|
- exclusive paths;
|
|
- shared/hotspot paths;
|
|
- contracts/schema/format changes;
|
|
- dependencies и blockers;
|
|
- verification commands;
|
|
- expected fidelity evidence.
|
|
- documentation deliverables: inline API, module spec, diagrams и source map.
|
|
|
|
## Ветки и worktrees
|
|
|
|
Имя ветки:
|
|
|
|
```text
|
|
work/<agent-id>/<target>-<short-name>
|
|
```
|
|
|
|
Пример:
|
|
|
|
```text
|
|
work/sindo-main-codex/m01-coordinate-mapper
|
|
```
|
|
|
|
Начало работы:
|
|
|
|
```powershell
|
|
git fetch origin
|
|
git worktree add ..\open-wc-m01 -b work/sindo-main-codex/m01-coordinate-mapper origin/master
|
|
```
|
|
|
|
Правила:
|
|
|
|
- один worktree принадлежит одному агенту;
|
|
- не запускать двух агентов в одном dirty worktree;
|
|
- не менять и не удалять чужой worktree;
|
|
- generated caches и proprietary data не переносятся commit/cherry-pick;
|
|
- перед handoff ветка синхронизируется с актуальным `origin/master`.
|
|
|
|
## Разделение задач
|
|
|
|
Хороший work package:
|
|
|
|
- даёт один наблюдаемый результат;
|
|
- принадлежит преимущественно одной подсистеме;
|
|
- имеет явные входы/выходы;
|
|
- меняет не более одного публичного contract одновременно;
|
|
- имеет собственные tests/diagnostics;
|
|
- может быть review и merged независимо либо после одной явно указанной dependency.
|
|
|
|
Плохое разделение:
|
|
|
|
- «сделать сеть»;
|
|
- один агент меняет protocol и UI напрямую;
|
|
- два агента одновременно рефакторят один monolithic file;
|
|
- задача зависит от незаписанного устного соглашения;
|
|
- work package оставляет временный второй источник истины.
|
|
|
|
## Parallelization patterns
|
|
|
|
### Contract first
|
|
|
|
Для cross-layer feature сначала отдельным маленьким work package фиксируются:
|
|
|
|
- domain types;
|
|
- commands/events/read models;
|
|
- version/capabilities;
|
|
- failure states;
|
|
- contract tests.
|
|
|
|
После merge независимо работают producer и consumers.
|
|
|
|
Пример:
|
|
|
|
```text
|
|
WP-A: MovementSnapshot contract
|
|
├─ WP-B: network movement decoder
|
|
├─ WP-C: gameplay reconciliation
|
|
└─ WP-D: character/camera presentation
|
|
```
|
|
|
|
### Fixtures in parallel
|
|
|
|
Пока один агент реализует pure logic, второй может готовить:
|
|
|
|
- synthetic fixtures;
|
|
- original-client comparison procedure;
|
|
- server-core matrix;
|
|
- visual checkpoints;
|
|
- documentation/reference analysis.
|
|
|
|
Fixture agent не изменяет production contract без согласования.
|
|
|
|
### Adapter split
|
|
|
|
После merge canonical interface допустимо параллельно реализовать TrinityCore и AzerothCore adapters, если у каждого разные файлы и общая contract suite.
|
|
|
|
### Hotspot extraction first
|
|
|
|
Если работа требует одного большого файла, сначала один владелец извлекает стабильный seam. Параллельная работа начинается только после merge seam, а не внутри разных участков монолита.
|
|
|
|
## Hotspot-файлы
|
|
|
|
Следующие пути требуют явного указания в claim и согласования с интегратором:
|
|
|
|
- `project.godot`;
|
|
- `AGENTS.md`, `docs/README.md`, `targets/README.md`;
|
|
- текущий `targets/[0-9][0-9]-*.md`;
|
|
- `RENDER.md`;
|
|
- `src/scenes/streaming/streaming_world_loader.gd` до декомпозиции;
|
|
- native registration/CMake/GDExtension manifests;
|
|
- editor `plugin.cfg` и root plugin lifecycle;
|
|
- shared schema/version/format constants;
|
|
- dependency lockfiles и submodules.
|
|
|
|
Два активных work packages не должны редактировать один hotspot. При необходимости интегратор выделяет serial integration window.
|
|
|
|
## Изменение contracts и форматов
|
|
|
|
Contract/schema change обязан иметь:
|
|
|
|
- owner и потребителей;
|
|
- backward compatibility или migration;
|
|
- old/new fixtures;
|
|
- version bump policy;
|
|
- rollout order;
|
|
- ADR для существенного решения.
|
|
|
|
Merge order:
|
|
|
|
1. contract + compatibility layer;
|
|
2. producers;
|
|
3. consumers;
|
|
4. removal deprecated path отдельным work package.
|
|
|
|
Нельзя одновременно удалить старый API и ожидать, что незамердженная ветка другого агента уже использует новый.
|
|
|
|
## Commits
|
|
|
|
Формат заголовка:
|
|
|
|
```text
|
|
<program>(<target>): <imperative summary>
|
|
```
|
|
|
|
Примеры:
|
|
|
|
```text
|
|
fnd(M01): add canonical coordinate mapper
|
|
net(M08): decode auth challenge safely
|
|
rnd(M03): extract streaming target planner
|
|
test(M00): add paired checkpoint manifest
|
|
```
|
|
|
|
Описание commit/PR содержит:
|
|
|
|
```text
|
|
Work-Package: M01-FND-COORDS-001
|
|
Agent: sindo-main-codex
|
|
Tests: <commands/results>
|
|
Fidelity: <evidence/gap>
|
|
```
|
|
|
|
Не смешивать formatting unrelated files, generated artifacts и функциональное изменение в одном commit.
|
|
|
|
## Handoff protocol
|
|
|
|
Готовый work package получает marker:
|
|
|
|
```text
|
|
<!-- OPENWC_HANDOFF:READY:M01-FND-COORDS-001:<commit> -->
|
|
```
|
|
|
|
Handoff обязан содержать:
|
|
|
|
- точный commit/branch;
|
|
- outcome и изменённые paths;
|
|
- публичные contracts/schema changes;
|
|
- verification commands и результаты;
|
|
- fidelity evidence/known gaps;
|
|
- migration/cache/rebuild requirements;
|
|
- unresolved risks;
|
|
- recommended merge order;
|
|
- updated API/module documentation и перечень diagrams.
|
|
|
|
Если работа частичная:
|
|
|
|
```text
|
|
<!-- OPENWC_HANDOFF:PARTIAL:M01-FND-COORDS-001:<commit> -->
|
|
```
|
|
|
|
`PARTIAL` не считается завершением и не разрешает ставить target `DONE`.
|
|
|
|
## Integration protocol
|
|
|
|
Интегратор:
|
|
|
|
1. Проверяет claim и отсутствие overlapping ownership.
|
|
2. Проверяет diff на unrelated/user changes.
|
|
3. Синхронизирует branch с `master` без уничтожения чужой истории.
|
|
4. Запускает package verification и затронутые общие gates.
|
|
5. Проверяет docs, migrations, cache versions и fidelity statement.
|
|
6. Проверяет documentation gate из `docs/DOCUMENTATION_STANDARD.md`: API docs, inputs/outputs, diagrams, ownership и recovery.
|
|
7. Merge/squash выполняет в соответствии с историей work package.
|
|
8. После merge запускает post-merge smoke.
|
|
9. Закрывает claim marker-ом:
|
|
|
|
```text
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M01-FND-COORDS-001:<merge-commit> -->
|
|
```
|
|
|
|
Только после интеграции всех обязательных work packages интегратор обновляет target Evidence/status.
|
|
|
|
## Конфликты
|
|
|
|
При обнаружении overlapping edits агент должен остановить изменение затронутого файла и связаться с владельцем. Запрещено:
|
|
|
|
- разрешать конфликт через слепое `ours/theirs`;
|
|
- копировать чужой файл поверх своего;
|
|
- делать `reset --hard` или checkout чужих изменений;
|
|
- «временно» дублировать contract без migration plan.
|
|
|
|
Порядок разрешения:
|
|
|
|
1. определить semantic owner;
|
|
2. выбрать merge order;
|
|
3. первый владелец публикует минимальный contract/seam;
|
|
4. второй rebase и адаптирует свою ветку;
|
|
5. integration tests подтверждают совместимость.
|
|
|
|
## Status updates и stale work
|
|
|
|
Владелец обновляет claim после значимого результата или не реже срока lease. Status краткий:
|
|
|
|
```text
|
|
State: active | waiting | ready | partial
|
|
Done: ...
|
|
Next: ...
|
|
Blocked by: ...
|
|
Touched paths: ...
|
|
```
|
|
|
|
Если работа прекращена, claim явно освобождается. Незавершённую ветку не удаляют до handoff с описанием пригодных commits и известных проблем.
|
|
|
|
## Минимальная схема для двух разработчиков
|
|
|
|
- Один человек назначается интегратором текущего milestone.
|
|
- Второй берёт work package без пересечения файлов либо готовит fixtures/reference/adapter.
|
|
- Роль интегратора можно менять после каждого milestone.
|
|
- Перед началом дня оба выполняют `git fetch` и сверяют claims/draft PRs.
|
|
- Перед merge второй агент не начинает работу поверх непроверенного commit, если dependency не опубликована как contract branch.
|
|
|
|
Пример для M01:
|
|
|
|
```text
|
|
Developer A / integrator:
|
|
M01-FND-COORDS-001 — coordinate types and mapper
|
|
|
|
Developer B:
|
|
M01-QAR-COORD-FIXTURES-001 — known ADT/server points and tests
|
|
|
|
После merge contract:
|
|
A — StreamingFocus migration
|
|
B — placement/SQL conversion audit
|
|
```
|
|
|
|
## Автоматическая проверка
|
|
|
|
Перед handoff и merge запускать:
|
|
|
|
```powershell
|
|
.\tools\verify_coordination.ps1
|
|
.\tools\verify_documentation.ps1
|
|
```
|
|
|
|
Первая проверка требует ровно один `ACTIVE` numbered target, соответствие `Current target`, валидные и уникальные fallback claim markers. Вторая проверяет обязательные documentation files, структуру module specs, наличие data-flow diagram и относительные ссылки. Истёкший claim выдаёт warning и требует человеческого решения, но не удаляется автоматически.
|