sindoring/open-wc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
0eef72a2c2ac9540320f32f1a39d6f1bc8006cd5
open-wc/docs/TEAM_WORKFLOW.md
T

13 KiB
Raw Blame History

Командная разработка 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:

<human>-<machine>-codex

Примеры:

sindo-main-codex
alex-laptop-codex

ID записывается в claim, ветке, PR/MR и handoff. Нельзя использовать просто codex, потому что таких агентов несколько.

Work Package ID

<TARGET>-<PROGRAM>-<SHORT-NAME>-<NNN>

Примеры:

M01-FND-COORDS-001
M03-RND-SCHEDULER-001
M08-NET-SRP-001
M12-UIA-LUA-SPIKE-001

Program codes определены в ../targets/DEVELOPMENT_ROADMAP.md.

Claim protocol

Предпочтительный канал координации — issue + ранний draft PR/MR на общем Git forge. Если forge недоступен, используется отдельный файл в coordination/claims/, который сначала публикуется в общей ветке.

Claim marker:

<!-- 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

Имя ветки:

work/<agent-id>/<target>-<short-name>

Пример:

work/sindo-main-codex/m01-coordinate-mapper

Начало работы:

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.

Пример:

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

Формат заголовка:

<program>(<target>): <imperative summary>

Примеры:

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 содержит:

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:

<!-- 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.

Если работа частичная:

<!-- 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-ом:
<!-- 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 краткий:

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:

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 запускать:

.\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 и требует человеческого решения, но не удаляется автоматически.

Reference in New Issue View Git Blame Copy Permalink