Files
TMSHandDevin a1ce4bdb8a 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>
2026-11-08 17:14:44 +03:00

60 lines
5.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Сверка с дорожной картой
Дорожная карта — единственный трекер задач команды: 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): …`.