# Протокол AI-ассистента: контекст и документирование Обязателен для любого AI-ассистента в репозитории «Штиль» (Devin, Windsurf, Cursor, Claude Code и др.) у обоих разработчиков. Читается сразу после `AGENTS.md`. Цель: ассистент в любой новой сессии за 1–2 минуты понимает, где проект, что сделано на Frontend и Backend, что делать дальше, и **сам поддерживает эту память в актуальном виде**. --- ## 1. Где что хранится (источники истины) | Что | Где | Кто пишет | |---|---|---| | План, задачи, статусы, исполнители, обсуждения, решения команды | Дорожная карта (`docs/ai/roadmap.md`) | Люди в интерфейсе карты. **AI только читает** | | Правила проекта, стек, запреты | `AGENTS.md` | Люди; AI предлагает правки | | Как работает AI с памятью проекта | `docs/ai/` (этот файл) | Люди; AI предлагает правки | | Текущее состояние «здесь и сейчас» | `docs/status/{shared,frontend,backend}.md` | AI в каждом PR | | История: что сделано, почему, что осталось | `docs/journal/` — одна запись на ветку/PR | AI в каждом PR | | Значимые решения | `docs/adr/NNNN-*.md` | AI готовит, люди принимают | | Как устроена каждая часть системы | `docs/architecture/`, `docs/frontend/`, `docs/backend/`, `docs/ux/`, `docs/testing/` | AI при появлении нового модуля/паттерна | | Контракты | `api/openapi.yaml`, `proto/`, `migrations/` | Отдельный PR, обсуждение с обоими | | Термины | `docs/glossary.md` | Сначала словарь, потом код | **Приоритет при расхождении:** код и контракты (как сделано) → ADR (как решили) → дорожная карта (статусы и решения команды) → `docs/status` → `docs/journal` → память чата. Нашёл расхождение — сообщи пользователю и предложи исправление, не выбирай молча. **Не дублировать.** Дорожная карта отвечает на «что и в каком статусе», `docs/` — на «как сделано и почему». В `docs/` ссылайся на задачи по ID (`#2.11`, `#2.11.4`), не переписывай их текст. --- ## 2. Зоны ответственности | Зона | Владелец | Пути | Что документируется | |---|---|---|---| | `frontend` | Frontend-разработчик | `apps/console/src/`, `apps/helper/src/`, `apps/*/src-tauri/`, `packages/ui/`, `docs/frontend/` | Дизайн-система, токены, компоненты, вёрстка, состояние, роутинг, i18n, слой `src/platform/`, Tauri-оболочка | | `backend` | Backend-разработчик | `cmd/`, `internal/`, `deploy/`, `tools/` (кроме `roadmap-context`), `docs/backend/` | Сервер, агент, БД, NATS, безопасность, сборка, окружение | | `shared` | Оба | `api/`, `proto/`, `migrations/`, `packages/api-client/`, `docs/adr/`, `docs/architecture/`, `docs/ux/`, `docs/glossary.md`, `docs/features.md`, `docs/status/shared.md`, `AGENTS.md`, `docs/ai/`, `tools/roadmap-context/`, `roadmap/`, `Taskfile.yml`, `.gitea/`, `.mise.toml` | Всё, что видит или от чего зависит другая сторона | Правила зон: - **Читаешь:** `shared` + свою зону. Чужую зону — только если задача её касается (например, Frontend подключает эндпоинт и смотрит `docs/backend/` по нему). - **Пишешь:** свою зону + `shared`. Документы чужой зоны не редактируешь. Нашёл в них ошибку или нужна правка у другой стороны — запись в «Запросы между зонами» в `docs/status/shared.md`. - Чисто внутренние вещи зоны (дизайн-правила, вёрстка, внутренняя организация сервиса) остаются в документах зоны и **не попадают** в `shared`. Ассистент другой стороны их не читает и не тратит на них контекст. - **Личные заметки — `docs/private/`.** Папка в `.gitignore`: она есть только на компьютере владельца, в Gitea не попадает, второй разработчик и его AI её не видят. Это внутренний «чат» разработчика с AI: черновые мысли, личные договорённости с ассистентом, заметки по текущей работе, контекст между сессиями. Файлы: `docs/private/notes.md` (основной), при необходимости другие. Правила: - ассистент читает `docs/private/` в начале сессии и дописывает туда то, что нужно помнить только владельцу; - всё, что нужно другой стороне или проекту (решения, изменения поведения, договорённости), идёт в `docs/status`, `docs/journal` или ADR, а не только в `private`; - ассистент не переносит текст из `private` в файлы под git без согласия владельца; - секреты и пароли не хранятся и здесь — только в менеджере паролей. Резервную копию папки владелец делает сам. - **Как определить зону сессии:** 1) пользователь назвал её («зона: frontend»); 2) она задана в личных правилах разработчика (раздел 8); 3) по путям файлов задачи. Задача затрагивает обе зоны — работай как `shared` и спроси, кто делает вторую часть. ### Что обязательно идёт в `shared` (impact: shared) - изменения `api/openapi.yaml`, `proto/`, `migrations/`, сгенерированного клиента; - права, роли, области, каталог функций и лимитов, коды ошибок и формат ответов; - новые или изменённые переменные окружения, конфиг, порты, команды `task`, CI, зависимости уровня репозитория; - поведение, которое видит другая сторона (новый эндпоинт готов, поле стало обязательным, формат даты изменился, эндпоинт нужен фронту); - безопасность: аутентификация, токены, CSP и capabilities Tauri, хранение секретов, аудит; - новые термины, ADR, решения из чата, отклонения от плана дорожной карты, блокеры для другой стороны. --- ## 3. Начало сессии Выполни по порядку и **не начинай писать код, пока не сделал шаги 1–5**: 1. `AGENTS.md` (обычно подгружается сам) и этот файл. 2. `docs/status/shared.md`, `docs/status/<зона>.md` и личные заметки `docs/private/` (если папка есть; если нет — создай `docs/private/notes.md` по шаблону `docs/ai/templates/private-notes.md`). 3. Журнал: последние 5 записей своей зоны и все записи `impact: shared` новее твоей последней записи (`docs/journal/`, имена файлов сортируются по дате). 4. Дорожная карта: `node tools/roadmap-context/roadmap-context.mjs` (текущий шаг) и `... ` для задачи сессии. Подробности и запасные варианты — `docs/ai/roadmap.md`. 5. Git: текущая ветка, `git status`, `git log --oneline -15 origin/main`. Есть ли смерженные PR другой стороны после последнего обновления статуса. 6. Отчитайся пользователю (не больше 10 строк): - где мы: фаза, шаг, задача и её статус в карте; - что изменилось с прошлой сессии, в том числе у другой стороны; - открытые вопросы, блокеры, запросы к этой зоне; - расхождения между картой, документами и кодом; - что предлагаешь сделать сейчас. Задача вне текущего шага, без ID или в статусе «Выполнено» — предупреди и предложи: взять задачу текущего шага, добавить «свой пункт» в карту или записать в бэклог. --- ## 4. Во время работы - Работа идёт в ветке `feat/-кратко` (`AGENTS.md`, раздел 6). Запись журнала этой ветки создаётся в первом же коммите и дополняется по ходу. - **Решение принято в чате** — сразу в раздел «Решения» записи журнала. Значимое (влияет на архитектуру, контракт, безопасность, другую сторону, его дорого отменить) — черновик ADR по шаблону и текст для поля «Решение» в карте. - **Отклонился от плана** (пункт сделан иначе, не нужен, нужен новый) — раздел «Отклонения от плана» и предложение для карты. - **Нашёл что-то вне шага** — раздел «Идеи и бэклог», не реализуй. - **Нужно что-то от другой стороны** — запрос в `docs/status/shared.md` и текст сообщения типа «Вопрос» или «Блокер» для карты. - **Контракт меняется** — отдельный PR (только контракт + запись `shared`), потом реализация. - Не держи важное только в чате: если завтра сессия начнётся с нуля, всё нужное должно быть в файлах. --- ## 5. Перед коммитом и в конце сессии Документация — часть PR. PR без обновлённой документации не готов к ревью. Чек-лист: - [ ] Запись журнала ветки обновлена: сделано, решения, проверка, что осталось (`docs/ai/templates/journal-entry.md`). - [ ] Личное (черновые мысли, на чём остановились, что обсудить с собой) — в `docs/private/notes.md`. - [ ] `docs/status/<зона>.md` отражает текущее состояние: заменить устаревшее, а не дописать снизу. - [ ] Если есть impact `shared` — обновлён `docs/status/shared.md` (раздел «Готово для другой стороны» или «Запросы между зонами»). - [ ] Новый модуль, экран, компонент, паттерн, эндпоинт — описание в документах зоны (`docs/ai/templates/module.md`). - [ ] Значимое решение — `docs/adr/NNNN-*.md` (`docs/ai/templates/adr.md`), статус «Предложено» до одобрения людьми. - [ ] Новый термин — `docs/glossary.md`. Новая команда или правило — предложение правки `AGENTS.md`. - [ ] Секретов, паролей, токенов, внутренних адресов стенда и персональных данных в документах нет. - [ ] Блок **«Для дорожной карты»** выведен пользователю в чат: ``` Задача: #2.11 → статус: На проверке Отметить пункты: 2.11.4, 2.11.6 Сообщение (Комментарий/Вопрос/Блокер/Решение): <текст> Поле «Решение»: <текст, если есть> Ссылка: PR (после открытия) ``` Человек переносит это в карту сам. Описание PR можно взять кнопкой «Для PR» в задаче карты. Документы коммитятся в той же ветке, что и код (`docs(<область>): …` или вместе с кодом), с той же строкой `Refs: `. **Коммиты, названия и описания PR — только на русском** (правило в `AGENTS.md`, раздел 6): `тип(область): что сделано`, тип и область латиницей, остальное по-русски, понятно и конкретно. Ассистент сам предлагает сообщение коммита в этом формате и не использует английские шаблоны своего инструмента. --- ## 6. Форматы и размеры - Язык — русский, термины по `docs/glossary.md`, идентификаторы кода — как в коде. - Пиши факты: что сделано, где лежит (относительный путь), как проверить. Без воды, пересказа кода и мотивационных фраз. - `docs/status/*.md` — до 120 строк. Это снимок, не история: выполненное старше одного шага удаляется (оно есть в журнале). - Запись журнала — до 60 строк. Одна запись на ветку/PR, не на каждый чат. - Имя записи журнала: `docs/journal/YYYY-MM-DD-<зона>--<кратко>.md`, дата — день создания ветки. Пример: `2026-11-20-frontend-2.13-design-tokens.md`. - Описание модуля — в документах зоны или `docs/architecture/`, если его используют обе стороны. - Ссылки на задачи — `#ID`, на код — относительный путь, на ADR — `ADR-0008`. - Дата — `YYYY-MM-DD`, время, если нужно, — UTC. --- ## 7. Конфликты и совместная работа - Свою зону и свой журнал правит только её владелец, поэтому конфликты возможны только в `shared`-файлах. При конфликте в `docs/status/shared.md` сохраняются записи обеих сторон. - Пункт в «Запросах между зонами» закрывает тот, кто выполнил: удаляет строку и добавляет запись в «Готово для другой стороны». - В конце шага (ритм «Конец шага» в карте) один из разработчиков просит ассистента: «подведи итог шага» → ассистент сверяет карту, журнал и код, чистит `docs/status/*`, выдаёт список несовпадений и текст для ретро. --- ## 8. Личные правила разработчика (не в git) Каждый добавляет в правила своего AI-инструмента (глобальные правила Windsurf/Devin, `~/.config/devin/`, User Rules в Cursor и т.п.) короткий блок. Пример для Frontend: ``` Проект «Штиль». Я — Frontend-разработчик, моя зона: frontend. В начале каждой сессии выполняй docs/ai/PROTOCOL.md (раздел 3), в конце — раздел 5. Backend-документацию читай только когда задача касается API/контрактов. ``` Для Backend — то же с зоной `backend`. Стартовая фраза новой сессии, если правила не настроены: ``` Зона: frontend. Задача: #2.13. Выполни начало сессии по docs/ai/PROTOCOL.md. ``` Конец сессии: `Заверши сессию по docs/ai/PROTOCOL.md (раздел 5).`