docs: AI documentation protocol and roadmap context tool

Протокол работы AI-ассистентов, зоны frontend/backend/shared, статусы, журнал, шаблоны и скрипт сводки дорожной карты.

Refs: 1.2.3

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
TMSHandDevin committed 2026-11-08 17:14:44 +03:00
1 parent 699e6bbd57
commit a1ce4bdb8a
15 files changed
+804

No files matched your search

+150
View File
@@ -0,0 +1,150 @@
# Протокол 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`. Ассистент другой стороны их не читает и не тратит на них контекст.
- **Как определить зону сессии:** 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`.
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`).
- [ ] `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 <URL> (после открытия)
```
Человек переносит это в карту сам. Описание PR можно взять кнопкой «Для PR» в задаче карты.
Документы коммитятся в той же ветке, что и код (`docs(<область>): …` или вместе с кодом), с той же строкой `Refs: <ID>`.
---
## 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).`
+59
View File
@@ -0,0 +1,59 @@
# Сверка с дорожной картой
Дорожная карта — единственный трекер задач команды: https://locshare.ru/roadmap/
AI-ассистент **только читает** её. Изменения в карту вносят люди через интерфейс; ассистент готовит для них текст (блок «Для дорожной карты», `PROTOCOL.md`, раздел 5).
## Основной способ
```
node tools/roadmap-context/roadmap-context.mjs # текущий шаг, статусы задач, последние изменения
node tools/roadmap-context/roadmap-context.mjs 2 # обзор шага 2
node tools/roadmap-context/roadmap-context.mjs 2.11 # задача полностью: описание, вопросы и ответы, решение, пункты, обсуждение, ссылки
node tools/roadmap-context/roadmap-context.mjs --all # всё подробно (много текста, только при подведении итогов шага)
```
План (`data.js`) берётся из `roadmap/data.js` в репозитории, если файл есть, иначе с сервера. Если локальная копия отличается от сервера, скрипт выводит предупреждение — сообщи об этом пользователю. Прогресс всегда берётся с сервера.
Переменные окружения (задаются локально, в git не попадают):
| Переменная | По умолчанию | Назначение |
|---|---|---|
| `ROADMAP_URL` | `https://locshare.ru/roadmap` | Адрес roadmap-server |
| `ROADMAP_AUTH` | — | `логин:пароль` для Basic Auth, когда на сервере включён пароль |
| `ROADMAP_DATA` | `roadmap/data.js` | Путь к локальному плану |
## Что проверять
В начале сессии:
- текущий шаг (`meta.current`) и есть ли задача сессии в этом шаге;
- статус задачи и исполнители: не делает ли её уже другой человек;
- ответы на вопросы `В1…Вn` и поле «Решение» — это решения команды, они обязательны к исполнению;
- незакрытые сообщения «Блокер» и «Вопрос» по задаче;
- «свои пункты» команды — работа, которой нет в плане, но она согласована.
Расхождения, о которых нужно сказать пользователю:
- в коде/журнале пункт сделан, а в карте не отмечен (или наоборот);
- решение в карте противоречит ADR или коду;
- задача «В работе» у другого человека, а мы её трогаем;
- работа идёт по задаче вне текущего шага.
## Как устроены данные (для разбора вручную)
| Запрос | Что возвращает |
|---|---|
| `GET {ROADMAP_URL}/api/health` | `{"revision": N}` — номер ревизии, растёт при каждом изменении |
| `GET {ROADMAP_URL}/api/progress` | JSON `shtil-roadmap-progress/2` — работа команды |
| `GET {ROADMAP_URL}/roadmap/data.js` | Содержание плана: `window.SHTIL_ROADMAP = { meta, areas, types, phases[].steps[].tasks[] }` |
Разделы `progress`: `members` (id → имя, роль), `tasks` (статус `todo/doing/review/done/blocked`, `assignees`, `priority`, `due`), `items` (ID пункта → `done`), `decisions` (статус `open/discuss/accepted/postponed`, `text`), `answers` (ключ `<задача>~<номер вопроса>`), `comments` (`task`, `kind`: `comment/question/proposal/blocker/decision`, `resolved`, `deleted`), `notes`, `custom` (свои пункты), `links`.
**Запрещено:** `POST /api/ops` и любые другие запросы на запись, правка `progress.json`, перенумерация ID в `data.js`.
## Если сервер недоступен
1. Попросить пользователя: «Настройки → Сводка для AI» → скопировать и вставить в чат (или скачать `.md`).
2. Работать по `roadmap/data.js` и `docs/status/*`, явно предупредив, что статусы могут быть устаревшими.
## Раскрытие следующего шага
В конце шага пользователь передаёт ассистенту «Сводку для AI» и комментарий. Ассистент обновляет `roadmap/data.js` по правилам из шапки файла: новые пункты получают следующий свободный номер, «свои пункты» из `custom` переносятся в план новыми ID, `meta.current` и `meta.changelog` обновляются. Это отдельный PR `docs(roadmap): …`.
+22
View File
@@ -0,0 +1,22 @@
# ADR-NNNN: Название решения
- **Статус:** Предложено | Принято | Отклонено | Заменено ADR-NNNN
- **Дата:** YYYY-MM-DD
- **Задача:** #1.5
- **Участники:** Имя, Имя
- **Зоны:** shared | frontend | backend
## Контекст
Какая проблема, какие ограничения и факты. 3–6 предложений.
## Решение
Что решили, конкретно и проверяемо.
## Рассмотренные варианты
| Вариант | Плюсы | Минусы |
|---|---|---|
| | | |
## Последствия
- Что становится проще, что сложнее, что нужно сделать (с ID задач).
- Как понять, что решение пора пересмотреть.
+34
View File
@@ -0,0 +1,34 @@
---
date: YYYY-MM-DD
zone: frontend | backend | shared
task: "2.13"
items: ["2.13.1", "2.13.2"]
branch: feat/2.13-design-tokens
pr: —
impact: none | shared
status: в работе | на проверке | смержено
author: Имя
---
# [2.13] Кратко, что делаем
## Сделано
- Что сделано и где лежит (`путь/к/файлу`). Отмеченный пункт карты — с его ID.
## Решения
- Что решили и почему. Значимое → ADR-NNNN.
## Для другой стороны
<!-- Только при impact: shared. Что изменилось для другой зоны и что ей нужно сделать. Иначе удалить раздел. -->
## Отклонения от плана
<!-- Пункт сделан иначе / не нужен / появился новый. Иначе удалить раздел. -->
## Проверка
- Какие тесты, линтеры, ручные проверки пройдены.
## Осталось
- [ ] Что не доделано в этой ветке.
## Идеи и бэклог
<!-- Найдено вне текущего шага, не делали. Иначе удалить раздел. -->
+22
View File
@@ -0,0 +1,22 @@
# Название модуля / экрана / компонента
- **Зона:** frontend | backend | shared
- **Где в коде:** `путь/`
- **Задачи:** #2.14, #3.2
- **Связанные ADR и документы:** ADR-0008, `docs/architecture/...`
## Назначение
Что делает и чего НЕ делает. 2–4 предложения.
## Как устроено
Ключевые части, поток данных, точки расширения. Схема — если помогает.
## Контракт и зависимости
- Эндпоинты / сообщения proto / таблицы / компоненты `packages/ui`, от которых зависит.
- Права и функции (`perm.*`, `features.*`), которые проверяются.
## Правила и подводные камни
- То, что нельзя нарушать, и то, на чём легко ошибиться.
## Как проверить
- Тесты, команды, ручной сценарий.