Протокол работы 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>
5.2 KiB
Сверка с дорожной картой
Дорожная карта — единственный трекер задач команды: 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.
Если сервер недоступен
- Попросить пользователя: «Настройки → Сводка для AI» → скопировать и вставить в чат (или скачать
.md). - Работать по
roadmap/data.jsиdocs/status/*, явно предупредив, что статусы могут быть устаревшими.
Раскрытие следующего шага
В конце шага пользователь передаёт ассистенту «Сводку для AI» и комментарий. Ассистент обновляет roadmap/data.js по правилам из шапки файла: новые пункты получают следующий свободный номер, «свои пункты» из custom переносятся в план новыми ID, meta.current и meta.changelog обновляются. Это отдельный PR docs(roadmap): ….