# Протокол 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`), не переписывай их текст.
| `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, зависимости уровня репозитория;
- поведение, которое видит другая сторона (новый эндпоинт готов, поле стало обязательным, формат даты изменился, эндпоинт нужен фронту);
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` (текущий шаг) и `... <ID задачи>` для задачи сессии. Подробности и запасные варианты — `docs/ai/roadmap.md`.
5. Git: текущая ветка, `git status`, `git log --oneline -15 origin/main`. Есть ли смерженные PR другой стороны после последнего обновления статуса.
6. Отчитайся пользователю (не больше 10 строк):
- где мы: фаза, шаг, задача и её статус в карте;
- что изменилось с прошлой сессии, в том числе у другой стороны;
- открытые вопросы, блокеры, запросы к этой зоне;
- расхождения между картой, документами и кодом;
- что предлагаешь сделать сейчас.
Задача вне текущего шага, без ID или в статусе «Выполнено» — предупреди и предложи: взять задачу текущего шага, добавить «свой пункт» в карту или записать в бэклог.
---
## 4. Во время работы
- Работа идёт в ветке `feat/<ID>-кратко` (`AGENTS.md`, раздел 6). Запись журнала этой ветки создаётся в первом же коммите и дополняется по ходу.
- **Решение принято в чате** — сразу в раздел «Решения» записи журнала. Значимое (влияет на архитектуру, контракт, безопасность, другую сторону, его дорого отменить) — черновик ADR по шаблону и текст для поля «Решение» в карте.
- **Отклонился от плана** (пункт сделан иначе, не нужен, нужен новый) — раздел «Отклонения от плана» и предложение для карты.
- **Нашёл что-то вне шага** — раздел «Идеи и бэклог», не реализуй.
- **Нужно что-то от другой стороны** — запрос в `docs/status/shared.md` и текст сообщения типа «Вопрос» или «Блокер» для карты.
- **Контракт меняется** — отдельный PR (только контракт + запись `shared`), потом реализация.
- Не держи важное только в чате: если завтра сессия начнётся с нуля, всё нужное должно быть в файлах.
---
## 5. Перед коммитом и в конце сессии
Документация — часть PR. PR без обновлённой документации не готов к ревью.
Чек-лист:
- [ ] Запись журнала ветки обновлена: сделано, решения, проверка, что осталось (`docs/ai/templates/journal-entry.md`).
**Коммиты, названия и описания PR — только на русском** (правило в `AGENTS.md`, раздел 6): `тип(область): что сделано`, тип и область латиницей, остальное по-русски, понятно и конкретно. Ассистент сам предлагает сообщение коммита в этом формате и не использует английские шаблоны своего инструмента.
- Язык — русский, термины по `docs/glossary.md`, идентификаторы кода — как в коде.
- Пиши факты: что сделано, где лежит (относительный путь), как проверить. Без воды, пересказа кода и мотивационных фраз.
- `docs/status/*.md` — до 120 строк. Это снимок, не история: выполненное старше одного шага удаляется (оно есть в журнале).
- Запись журнала — до 60 строк. Одна запись на ветку/PR, не на каждый чат.
- Имя записи журнала: `docs/journal/YYYY-MM-DD-<зона>-<ID>-<кратко>.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).`