From 6395680344654ca1c800da6cdfe67f27e270b75c Mon Sep 17 00:00:00 2001 From: MpakobecEx Date: Sat, 24 Oct 2026 19:42:16 +0500 Subject: [PATCH] docs: add DeepSeek to Kimi implementation workflow --- .opencode/skills/vanguard-remaster/SKILL.md | 7 +- .../workflow-and-decisions.md | 5 + AGENTS.md | 20 +++ README.md | 5 +- docs/Development/AGENT-WORKFLOW.md | 148 ++++++++++++++++++ docs/Development/IMPLEMENTATION_PLAN.md | 122 +++++++++++++++ docs/HANDOFF.md | 14 +- docs/SESSION-STATE.md | 3 + 8 files changed, 321 insertions(+), 3 deletions(-) create mode 100644 docs/Development/AGENT-WORKFLOW.md create mode 100644 docs/Development/IMPLEMENTATION_PLAN.md diff --git a/.opencode/skills/vanguard-remaster/SKILL.md b/.opencode/skills/vanguard-remaster/SKILL.md index e35be09..ea713d7 100644 --- a/.opencode/skills/vanguard-remaster/SKILL.md +++ b/.opencode/skills/vanguard-remaster/SKILL.md @@ -48,6 +48,10 @@ description: Use for any work in the Vanguard ReMaster repository: Cardfight!! V движок или флаг данных. Текст без реализации — баг. - **После блока:** клиентские EditMode, серверные тесты (на home), `validate`, `translations check`, коммит и push. +- **Сначала план, потом код:** новые изменения проходят анализ DeepSeek с + записью в `docs/Development/IMPLEMENTATION_PLAN.md`, затем реализацию Kimi. + Передача — через файлы и Git, не через память модели. Детали — + `docs/Development/AGENT-WORKFLOW.md`. ## Быстрая карта проекта @@ -120,4 +124,5 @@ Smoke: `Vanguard.Editor.SceneSmoke.Run` / `RunPlaymat`; сборка: Связанные документы репозитория: `docs/game-rules.md`, `docs/ability-implementation.md`, `docs/protocol.md`, `docs/server-api.md`, `docs/client-visual-direction.md`, -`docs/translation-rules.md`. +`docs/translation-rules.md`, `docs/Development/IMPLEMENTATION_PLAN.md`, +`docs/Development/AGENT-WORKFLOW.md`. diff --git a/.opencode/skills/vanguard-remaster/workflow-and-decisions.md b/.opencode/skills/vanguard-remaster/workflow-and-decisions.md index b37fef8..3f4b24c 100644 --- a/.opencode/skills/vanguard-remaster/workflow-and-decisions.md +++ b/.opencode/skills/vanguard-remaster/workflow-and-decisions.md @@ -112,6 +112,11 @@ ## 4. Процесс разработки +Формальный двухэтапный процесс DeepSeek → Kimi описан в +`docs/Development/AGENT-WORKFLOW.md`; активный план задачи — в +`docs/Development/IMPLEMENTATION_PLAN.md`. Ниже — краткие правила, без +дублирования шаблона плана. + 1. Прочитай Skill и связанные docs; найди существующую реализацию. 2. Проверь, не решён ли вопрос в коде/истории. Не спрашивай о том, что уже установлено. diff --git a/AGENTS.md b/AGENTS.md index 6f4075e..ac119e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,26 @@ - Не спрашивай о том, что уже однозначно установлено кодом, документацией или историей. Не прерывай работу ради мелочей. +## Двухэтапная разработка + +- Любое пожелание, требующее изменения игры/кода, сначала проходит **анализ и + план DeepSeek**, затем **реализацию Kimi**. Не начинай код без плана, кроме + явно тривиальной правки, которую пользователь разрешил сделать сразу. +- Активный план и журнал задач — `docs/Development/IMPLEMENTATION_PLAN.md`; + подробный процесс — `docs/Development/AGENT-WORKFLOW.md`. +- DeepSeek на этапе анализа не меняет игровой код, сцены, префабы, SO и + конфиги; можно читать, задавать вопросы и обновлять план/документацию. +- Kimi перед реализацией читает `AGENTS.md`, Skill и раздел задачи, проверяет + Git и актуальность файлов/методов. Устаревший план не является разрешением на + изменения. +- Передача контекста — только через файлы репозитория и Git, не через память + модели. Если агенты в разных ветках/копиях, это фиксируется в плане. +- Статусы пунктов: `[ ]`, `[x]`, `[!]`, `[-]`; отдельно указывается + «Реализация» и «Проверка». `[x]` без проверки запрещён. +- Kimi не расширяет объём, не делает необязательный рефакторинг и не удаляет + чужие изменения. При новом существенном решении пользователя — вопрос и + остановка зависимой части. + ## Изменения - Сначала найди существующую реализацию и связанные зависимости. diff --git a/README.md b/README.md index 076840a..da79303 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,10 @@ dotnet run --project server/src/Vanguard.Cli -- translations check - `plan.md` — исходный дизайн-документ. - `DEVELOPMENT_CHECKLIST.md` — решения, механики, экономика, риски. -- `IMPLEMENTATION_CHECKLIST.md` — план реализации по блокам и гейтам. +- `IMPLEMENTATION_CHECKLIST.md` — исторический план по блокам и гейтам. +- `docs/Development/IMPLEMENTATION_PLAN.md` — активный журнал задач и шаблон + плана. +- `docs/Development/AGENT-WORKFLOW.md` — двухэтапный процесс DeepSeek → Kimi. - `docs/HANDOFF.md` — состояние на конец сессии и порядок следующих шагов. - `docs/protocol.md` — протокол матча: кадры, интенты, события, таймеры, реконнект. - `docs/game-rules.md` — конспект правил и сверка с текущей реализацией. diff --git a/docs/Development/AGENT-WORKFLOW.md b/docs/Development/AGENT-WORKFLOW.md new file mode 100644 index 0000000..d18ef90 --- /dev/null +++ b/docs/Development/AGENT-WORKFLOW.md @@ -0,0 +1,148 @@ +# Процесс DeepSeek → Kimi + +Двухэтапный процесс для задач, которые меняют игру, клиент, сервер, контент или +инфраструктуру. Он нужен, потому что анализ и реализация могут выполняться +разными моделями и в разных сессиях OpenCode. Общий контекст — только файлы +репозитория и Git, не память модели. + +## 1. Роли + +### DeepSeek — анализ и план + +- Читает `AGENTS.md`, Skill `vanguard-remaster`, `docs/SESSION-STATE.md`, + `docs/HANDOFF.md` и связанный код. +- Изучает историю, договорённости и существующую реализацию. +- Задаёт вопросы через инструмент `question`, если без ответа нельзя + корректно спланировать изменение. +- Создаёт или обновляет раздел задачи в `docs/Development/IMPLEMENTATION_PLAN.md`. +- **Не изменяет игровой код, сцены, префабы, ScriptableObject и конфиги.** +- Может обновлять только документацию и план. + +### Kimi — реализация + +- Читает `AGENTS.md`, Skill и раздел задачи по её ID. +- Проверяет актуальное состояние Git и кода; сверяет план с реальными + классами/методами. +- Реализует только согласованный объём. +- Запускает доступные проверки. +- Обновляет статусы пунктов и результат проверки в плане. +- Обновляет Skill, если пользователь согласовал новое постоянное правило. +- **Не придумывает новые правила/архитектуру и не расширяет задачу.** + +## 2. Как модели получают инструкции и доступ + +- Оба этапа используют **тот же репозиторий** и те же `AGENTS.md`/Skill. + Отдельные копии правил не создаются. +- Оператор выбирает модель в OpenCode. В текущей установке доступны Kimi-модели + (подтверждено каталогом моделей): `opencode/kimi-k3`, + `opencode/kimi-k2.7-code`, `opencode-go/kimi-k3.1-pro`, + `opencode-go/kimi-k2.7-code`. Конкретную модель выбирает пользователь. +- Передача работы — через: + 1. план задачи в `docs/Development/IMPLEMENTATION_PLAN.md`; + 2. текущий Git-коммит/ветку/рабочую копию; + 3. `docs/SESSION-STATE.md` и `docs/HANDOFF.md` для состояния. +- Не полагайся на «предыдущий чат» как на единственный источник: если чего-то + нет в файлах, это неизвестно. +- Если агенты работают в разных ветках/копиях, это должно быть явно указано в + плане; не создавай ветки и не делай merge без разрешения. + +## 3. Этап 1 — DeepSeek + +1. **Пожелание:** сформулируй ожидаемый результат, ограничения и критерии + готовности. Не пересказывай задачу в плане длиннее, чем нужно. +2. **Правила:** найди применимые разделы Skill. Отметь обязательные ограничения. +3. **Код:** проследи существующие классы, методы, вызовы, подписки, состояние, + UI и данные. Не ограничивайся файлами из сообщения пользователя. +4. **Пробелы:** проверь историю и документацию; если правило не подтверждено, + пометь `[O]`. Не выдумывай. +5. **Вопросы:** если неизвестность влияет на реализацию, задай вопрос через + `question` с 2–4 вариантами. +6. **План:** добавь раздел `TASK-YYYY-NNN` в `IMPLEMENTATION_PLAN.md` по шаблону: + цель, текущее состояние, чек-лист, последовательность, проверки, риски. +7. **Проверка плана:** каждый пункт должен быть выполним другим агентом; + зависимости и ожидаемый результат должны быть явными. +8. **Стоп:** после анализа не переходи к коду. + +## 4. Этап 2 — Kimi + +1. **Подготовка:** прочитай `AGENTS.md`, Skill, нужный раздел плана. +2. **Git:** `git status`, `git log -1`, при необходимости `git diff`; не + присваивай чужие незакоммиченные изменения. +3. **Актуальность:** сверь файлы/методы плана с кодом. Если код изменился: + - план остаётся верным — продолжай; + - появились новые зависимости — обнови план с причиной; + - требования/архитектура неоднозначны — останови зависимую часть и спроси. +4. **Реализация:** выполняй пункты по порядку, минимальными изменениями, без + необязательного рефакторинга и без несвязанных файлов. +5. **Проверки:** тесты, сборка/компиляция, smoke, `validate`, + `translations check`, `git diff` — только доступные и подтверждённые. +6. **Статусы:** обнови каждый пункт: + - `[x]` — реализовано и проверено; + - `[!]` — блокер/вопрос с причиной; + - `[-]` — отменено после согласованного изменения. + Если код есть, а проверки не было — не ставь `[x]`; пиши + «Реализация: выполнена. Проверка: не выполнена — причина». +7. **Skill:** если появилось постоянное правило — обнови существующий раздел, + не создавай дубликат; временные решения в Skill не писать. +8. **Итог:** краткий отчёт: что сделано, файлы, проверки, незавершённое, + вопросы, обновлялся ли Skill. + +## 5. Защита от устаревших планов и конфликтов + +- План — не безусловное разрешение на изменение кода. +- Перед каждым блоком проверяй актуальный файл и Git, а не только текст плана. +- Не перезаписывай разделы других задач; не удаляй невыполненные пункты. +- Если два плана затрагивают один класс/систему, проверь пересечение и + зафиксируй порядок. +- Если план противоречит Skill/подтверждённому требованию — остановись, + зафиксируй противоречие и задай вопрос. +- Не смешивай анализ, реализацию и приёмку в один непроверенный статус. + +## 6. Границы + +### Можно на этапе анализа + +- читать код, конфиги, тесты, историю; +- создавать/обновлять план и только документацию; +- задавать вопросы. + +### Нельзя на этапе анализа + +- менять игровой код, сцены, префабы, ScriptableObject, YAML-контент и + настройки; +- «попутно» исправлять найденные баги без отдельной задачи/плана; +- объявлять реализацию начатой. + +### Можно на этапе реализации + +- менять только файлы, перечисленные в плане (или обоснованно добавленные с + обновлением плана); +- добавлять тесты для изменённой механики; +- обновлять план и Skill по правилам выше. + +### Нельзя на этапе реализации + +- менять несвязанные системы; +- переписывать архитектуру без решения пользователя; +- удалять чужую работу; +- выдавать непроверенный результат за проверенный; +- проходить геймплей за пользователя и называть это приёмкой. + +## 7. Проверки и окружение + +- Серверные тесты, `validate`, `translations check` — только `ssh home` / + Docker, не локальный `dotnet`/Docker. +- Unity batch/EditMode/smoke — в копии проекта без `Library`; не открывать + второй Unity с тем же проектом. +- Перед коммитом: `git diff --check`, просмотр `git diff`, проверка отсутствия + несвязанных файлов. +- После блока: коммит/push, если пользователь не запретил. +- Геймплей вручную проверяет пользователь; агент фиксирует, что именно + осталось на ручную проверку. + +## 8. Исторические документы + +`IMPLEMENTATION_CHECKLIST.md` и `DEVELOPMENT_CHECKLIST.md` — исторические +планы/решения. Новые задачи ведутся только в +`docs/Development/IMPLEMENTATION_PLAN.md`; не добавляй новые задачи в старые +чек-листы. diff --git a/docs/Development/IMPLEMENTATION_PLAN.md b/docs/Development/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..0a42647 --- /dev/null +++ b/docs/Development/IMPLEMENTATION_PLAN.md @@ -0,0 +1,122 @@ +# Implementation Plan + +Активный журнал задач и планов изменений. Постоянные правила проекта хранятся +в Skill `vanguard-remaster`; история старых блоков — в `IMPLEMENTATION_CHECKLIST.md`, +`DEVELOPMENT_CHECKLIST.md` и `docs/HANDOFF.md`. Этот файл не заменяет их и не +является источником игровых правил. + +## Процесс + +1. **DeepSeek** анализирует пожелание, код и зависимости, задаёт вопросы и + создаёт/обновляет раздел задачи. Игровой код на этом этапе не меняется. +2. **Kimi** читает `AGENTS.md`, Skill и раздел задачи, сверяет план с текущим + кодом, реализует, проверяет и обновляет статусы. +3. Передача — только через файлы репозитория и Git. Память модели и чат не + считаются общим контекстом. +4. Если план устарел или требования изменились, Kimi останавливает зависимую + часть, фиксирует причину и при необходимости возвращает задачу на анализ. +5. Нельзя удалять чужие задачи, невыполненные пункты и историю статусов. + +Подробный процесс — `docs/Development/AGENT-WORKFLOW.md`. + +## Статусы + +- `[ ]` — не выполнено; +- `[x]` — выполнено и подтверждено доступными проверками; +- `[!]` — заблокировано или ждёт решения; +- `[-]` — больше не требуется после согласованного изменения плана. + +Для каждого пункта храни отдельно: + +- **Реализация:** выполнена / не выполнена / не требуется. +- **Проверка:** выполнена (что именно) / не выполнена (почему). + +`[x]` нельзя ставить, если реализация есть, а проверка не запускалась. + +## Журнал задач + +| ID | Статус | Название | Фаза | Проверка | +|---|---|---|---|---| +| — | — | Нет активных задач | — | — | + +Новые задачи добавляются в конец файла отдельными разделами. Не используй один +раздел для нескольких независимых задач. + +--- + +## Шаблон задачи (не является активной задачей) + +### TASK-YYYY-NNN — краткое название + +- **Статус:** `[ ]` +- **Создано:** YYYY-MM-DD +- **Анализ:** DeepSeek +- **Реализация:** Kimi +- **Затронутые системы:** ... + +#### A. Цель и требования + +- Что просит пользователь. +- Ожидаемое поведение. +- Обязательные правила Skill. +- Ограничения, которые нельзя нарушать. +- Критерии готовности. + +#### B. Текущее состояние + +- Как работает сейчас. +- Какие системы и файлы проверены. +- Существующие механики, которые нужно сохранить. +- Подтверждённые факты и открытые вопросы. + +#### C. Чек-лист изменений + +Каждый пункт: + +- `[ ]` `MODIFY` / `CREATE` / `DELETE` / `TEST` / `VERIFY` +- путь к файлу (если известен); +- класс/метод (если существует); +- конкретная логика; +- причина изменения; +- ожидаемый результат; +- зависимости от других пунктов; +- **Реализация:** не выполнена; +- **Проверка:** не выполнена. + +Пример формата: + +```text +- [ ] MODIFY `client/Assets/.../BattleView.cs` — `BattleView.SomeMethod` + Логика: ... + Причина: ... + Результат: ... + Зависит от: ... + Реализация: не выполнена + Проверка: не выполнена +``` + +#### D. Последовательность выполнения + +Нумерованный порядок с обязательными зависимостями. Разделяй работу по системам +на небольшие шаги. + +#### E. Проверки + +- Какие тесты/команды доступны и подтверждены проектом. +- Какие механики проверить на регрессию. +- Критерии готовности. +- Что остаётся на ручную проверку пользователя. + +#### F. Риски и неизвестные вопросы + +- Противоречия и побочные эффекты. +- Вопросы, требующие ответа пользователя. +- Что нельзя реализовывать до ответа. + +#### G. Результат + +- **Реализовано:** ... +- **Проверки:** ... +- **Не завершено/заблокировано:** ... +- **Skill обновлён:** да/нет, почему. +- **Git:** commit hash, изменённые файлы. diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 04e7956..e9b50fc 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1133,4 +1133,16 @@ Battle; Boot и общие сервисы остаются персистент панели «Действия» — промежуточная реализация. - Исправлен порядок отображения урона в `docs/protocol.md`: сначала открытые, затем закрытые. -- Код, сцены и префабы в рамках аудита не менялись. \ No newline at end of file +- Код, сцены и префабы в рамках аудита не менялись. + +## 2026-10-24 — двухэтапный процесс DeepSeek → Kimi + +- Добавлены `docs/Development/AGENT-WORKFLOW.md` и + `docs/Development/IMPLEMENTATION_PLAN.md` (пустой журнал + шаблон, без + фиктивной задачи). +- DeepSeek: анализ, вопросы, план; код не меняет. Kimi: реализация по плану, + проверки, обновление статусов и Skill. +- Передача — через файлы/Git; доступные Kimi-модели подтверждены каталогом + OpenCode. Конкретную модель выбирает пользователь. +- `AGENTS.md` и Skill дополнены ссылками и статусами `[ ]/[x]/[!]/[-]`. +- Код, сцены, префабы и конфиги не менялись. \ No newline at end of file diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index 77a4876..b7c3a27 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -11,6 +11,9 @@ - Любое сомнение/вопрос — диалог: 2–4 варианта с рекомендацией, выбор за пользователем (или его свободный ответ). Не угадывать. - Полный свод правил — `AGENTS.md`. +- Новые изменения: анализ DeepSeek → план в + `docs/Development/IMPLEMENTATION_PLAN.md` → реализация Kimi. Код на этапе + анализа не меняется; процесс — `docs/Development/AGENT-WORKFLOW.md`. ## Сервер