Files
shtil/docs/ai/roadmap.md
T
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

5.2 KiB
Raw Blame History

Сверка с дорожной картой

Дорожная карта — единственный трекер задач команды: 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): ….