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:
1 parent
699e6bbd57
commit
a1ce4bdb8a
15 files changed
+804
No files matched your search
@@ -0,0 +1,28 @@
|
||||
# Документация «Штиль»
|
||||
|
||||
Начните с `AGENTS.md` (правила проекта), затем `docs/ai/PROTOCOL.md` (как работать с контекстом и документировать).
|
||||
|
||||
## Порядок чтения для новой сессии
|
||||
1. `AGENTS.md`
|
||||
2. `docs/ai/PROTOCOL.md`
|
||||
3. `docs/status/shared.md` + `docs/status/<ваша зона>.md`
|
||||
4. Последние записи `docs/journal/`
|
||||
5. Дорожная карта: `node tools/roadmap-context/roadmap-context.mjs`
|
||||
|
||||
## Карта
|
||||
|
||||
| Папка / файл | Зона | Что внутри |
|
||||
|---|---|---|
|
||||
| `ai/` | shared | Протокол AI, сверка с дорожной картой, шаблоны |
|
||||
| `status/` | shared + зоны | Снимок текущего состояния: общее, Frontend, Backend |
|
||||
| `journal/` | все | История работы: одна запись на ветку/PR |
|
||||
| `adr/` | shared | Архитектурные решения `NNNN-название.md` |
|
||||
| `architecture/` | shared | ERD, правила БД, протокол агента, IPC Помощника |
|
||||
| `ux/` | shared | Информационная архитектура, макеты, сценарии |
|
||||
| `testing/` | shared | Тестовый стенд, сценарии доступа |
|
||||
| `research/` | shared | Интервью, исследования рынка |
|
||||
| `frontend/` | frontend | Внутренние правила Frontend: дизайн-система, компоненты, соглашения |
|
||||
| `backend/` | backend | Внутренние правила Backend: области сервера, агент, эксплуатация |
|
||||
| `glossary.md` | shared | Словарь терминов (#2.1) |
|
||||
| `features.md` | shared | Каталог функций и лимитов (#2.3) |
|
||||
| `contributing.md` | shared | Ветки, коммиты, PR, версии (#1.2.9) |
|
||||
@@ -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).`
|
||||
@@ -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): …`.
|
||||
@@ -0,0 +1,22 @@
|
||||
# ADR-NNNN: Название решения
|
||||
|
||||
- **Статус:** Предложено | Принято | Отклонено | Заменено ADR-NNNN
|
||||
- **Дата:** YYYY-MM-DD
|
||||
- **Задача:** #1.5
|
||||
- **Участники:** Имя, Имя
|
||||
- **Зоны:** shared | frontend | backend
|
||||
|
||||
## Контекст
|
||||
Какая проблема, какие ограничения и факты. 3–6 предложений.
|
||||
|
||||
## Решение
|
||||
Что решили, конкретно и проверяемо.
|
||||
|
||||
## Рассмотренные варианты
|
||||
| Вариант | Плюсы | Минусы |
|
||||
|---|---|---|
|
||||
| | | |
|
||||
|
||||
## Последствия
|
||||
- Что становится проще, что сложнее, что нужно сделать (с ID задач).
|
||||
- Как понять, что решение пора пересмотреть.
|
||||
@@ -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. Что изменилось для другой зоны и что ей нужно сделать. Иначе удалить раздел. -->
|
||||
|
||||
## Отклонения от плана
|
||||
<!-- Пункт сделан иначе / не нужен / появился новый. Иначе удалить раздел. -->
|
||||
|
||||
## Проверка
|
||||
- Какие тесты, линтеры, ручные проверки пройдены.
|
||||
|
||||
## Осталось
|
||||
- [ ] Что не доделано в этой ветке.
|
||||
|
||||
## Идеи и бэклог
|
||||
<!-- Найдено вне текущего шага, не делали. Иначе удалить раздел. -->
|
||||
@@ -0,0 +1,22 @@
|
||||
# Название модуля / экрана / компонента
|
||||
|
||||
- **Зона:** frontend | backend | shared
|
||||
- **Где в коде:** `путь/`
|
||||
- **Задачи:** #2.14, #3.2
|
||||
- **Связанные ADR и документы:** ADR-0008, `docs/architecture/...`
|
||||
|
||||
## Назначение
|
||||
Что делает и чего НЕ делает. 2–4 предложения.
|
||||
|
||||
## Как устроено
|
||||
Ключевые части, поток данных, точки расширения. Схема — если помогает.
|
||||
|
||||
## Контракт и зависимости
|
||||
- Эндпоинты / сообщения proto / таблицы / компоненты `packages/ui`, от которых зависит.
|
||||
- Права и функции (`perm.*`, `features.*`), которые проверяются.
|
||||
|
||||
## Правила и подводные камни
|
||||
- То, что нельзя нарушать, и то, на чём легко ошибиться.
|
||||
|
||||
## Как проверить
|
||||
- Тесты, команды, ручной сценарий.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Backend: документы зоны
|
||||
|
||||
Зона `backend` (`docs/ai/PROTOCOL.md`, раздел 2): сервер `shtil-server`, агент `shtil-agent`, БД, окружение, сборка.
|
||||
Здесь — внутренние правила Backend, которые не нужны Frontend. Всё, что влияет на API, протокол, права, функции, конфиг, — в `shared`.
|
||||
|
||||
## Документы
|
||||
|
||||
| Файл | О чём | Появится в |
|
||||
|---|---|---|
|
||||
| `conventions.md` | Структура `internal/server/<область>`, слои, ошибки, логи, тесты, транзакции | #2.10 |
|
||||
| `areas/<область>.md` | Область сервера (`access`, `sites`, `audit`…): таблицы, сервисные функции, права, события NATS | по мере появления |
|
||||
| `agent.md` | Устройство агента: транспорт, сборщики, очередь, исполнитель, платформенные части | шаг 4–5 |
|
||||
| `operations.md` | Запуск, конфиг, переменные окружения, миграции, диагностика | #2.8 |
|
||||
|
||||
Шаблон для областей и модулей — `docs/ai/templates/module.md`. Общая архитектура, ERD, правила БД, IPC — `docs/architecture/` (shared).
|
||||
@@ -0,0 +1,25 @@
|
||||
# Frontend: документы зоны
|
||||
|
||||
Зона `frontend` (`docs/ai/PROTOCOL.md`, раздел 2): приложение «Штиль» (`apps/console`), «Штиль Помощник» (`apps/helper`), дизайн-система `packages/ui`.
|
||||
Здесь — внутренние правила Frontend, которые не нужны Backend. Всё, что влияет на API, права, функции, безопасность Tauri, — в `shared`.
|
||||
|
||||
## Документы
|
||||
|
||||
| Файл | О чём | Появится в |
|
||||
|---|---|---|
|
||||
| `design-system.md` | Токены (цвета, отступы, радиусы, тени), темы, типографика, иконки, правила вёрстки | #2.13 |
|
||||
| `components.md` | Каталог компонентов `packages/ui`: назначение, варианты, когда какой использовать | #2.13 |
|
||||
| `conventions.md` | Структура `src/`, именование, состояние (Pinia / TanStack Query), роутинг, i18n, обработка ошибок API | #2.14 |
|
||||
| `platform-layer.md` | Слой `src/platform/`: Tauri API, хранилище ключей, профили серверов | #2.14 |
|
||||
| `screens/<экран>.md` | Экран: назначение, данные, права, состояния (загрузка, пусто, ошибка) | по мере появления |
|
||||
|
||||
Шаблон для экранов и модулей — `docs/ai/templates/module.md`. Информационная архитектура и макеты (общие для обеих сторон) — `docs/ux/`.
|
||||
|
||||
## Исходные данные из дорожной карты (до решений #1.11 и #2.13)
|
||||
|
||||
Это рекомендации карты, а не принятые решения. После решения перенести в `design-system.md` и удалить отсюда.
|
||||
- Шрифты Unbounded, Manrope, JetBrains Mono — локально, без CDN. Иконки — Lucide.
|
||||
- Темы светлая и тёмная, по умолчанию — системная. Минимальный размер окна 1280×720.
|
||||
- Меню ≤ 11 пунктов в 3 группах: Работа · Управление · Аналитика. Недоступное по правам или редакции скрыто.
|
||||
- Селектор области (подразделения) фильтрует весь экран. Карточки — в боковой панели. Ctrl+K — поиск и команды.
|
||||
- Помощник: при старте только иконка в трее, окно создаётся по клику и уничтожается при закрытии; цели ≤ 40 МБ ОЗУ в покое, ≤ 150 МБ с окном, открытие ≤ 1 с.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
date: 2026-11-08
|
||||
zone: shared
|
||||
task: "1.2"
|
||||
items: []
|
||||
branch: chore/1.2-ai-docs-protocol
|
||||
pr: —
|
||||
impact: shared
|
||||
status: в работе
|
||||
author: Frontend
|
||||
---
|
||||
|
||||
# [1.2] Система документирования для AI-ассистентов
|
||||
|
||||
## Сделано
|
||||
- Протокол работы AI: `docs/ai/PROTOCOL.md` — источники истины, зоны frontend/backend/shared, чек-листы начала и конца сессии.
|
||||
- Сверка с дорожной картой: `docs/ai/roadmap.md` и скрипт `tools/roadmap-context/roadmap-context.mjs` (Node 18+, без зависимостей, только чтение).
|
||||
- Шаблоны: `docs/ai/templates/` — запись журнала, ADR, описание модуля.
|
||||
- Снимки состояния: `docs/status/shared.md`, `frontend.md`, `backend.md`.
|
||||
- Индексы зон: `docs/frontend/README.md`, `docs/backend/README.md`; карта документации `docs/README.md`.
|
||||
- `AGENTS.md`: раздел 9 «Документирование и контекст».
|
||||
|
||||
## Решения
|
||||
- Дорожная карта остаётся единственным трекером; AI её только читает и готовит текст для людей.
|
||||
- Память проекта для AI — `docs/status` (снимок) + `docs/journal` (история по PR), документация коммитится в той же ветке, что и код.
|
||||
- Внутренние документы зоны в `docs/frontend` и `docs/backend`; ассистент другой зоны их не читает без необходимости.
|
||||
|
||||
## Для другой стороны
|
||||
- Backend: прочитать `docs/ai/PROTOCOL.md`, добавить личный блок правил с `зона: backend` (раздел 8).
|
||||
|
||||
## Проверка
|
||||
- `node tools/roadmap-context/roadmap-context.mjs` и `... 1.2` против https://locshare.ru/roadmap/ — сводка выводится.
|
||||
|
||||
## Осталось
|
||||
- [ ] Обсудить протокол вдвоём, при необходимости поправить.
|
||||
- [ ] Перенести в репозиторий Gitea вместе с остальными файлами (#1.2.3).
|
||||
- [ ] Включить пароль на roadmap-server (#1.1.2): сейчас `/api/progress` читается без авторизации.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Журнал работы
|
||||
|
||||
Одна запись на ветку/PR. Шаблон — `docs/ai/templates/journal-entry.md`, правила — `docs/ai/PROTOCOL.md`.
|
||||
|
||||
- Имя: `YYYY-MM-DD-<зона>-<ID>-<кратко>.md`, дата — день создания ветки.
|
||||
- `zone` — чья работа; `impact: shared` — запись обязательна к прочтению другой стороной.
|
||||
- Запись правит только её автор. Смерженную запись не переписывают; исправление — новой записью.
|
||||
- Ассистент в начале сессии читает последние 5 записей своей зоны и все `impact: shared` новее своей последней записи.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Состояние: Backend
|
||||
|
||||
Обновлено: 2026-11-08 · Владелец: Backend-разработчик
|
||||
|
||||
Снимок, а не история. Внутренние правила зоны — `docs/backend/`.
|
||||
|
||||
## Сейчас
|
||||
- Кода нет. Впереди в шаге 1: Gitea и правила Git (#1.2), решения 1.4–1.7, тестовый стенд (#1.12).
|
||||
|
||||
## Сделано в текущем шаге
|
||||
- —
|
||||
|
||||
## В работе
|
||||
<!-- - #ID · ветка · что осталось -->
|
||||
- —
|
||||
|
||||
## Ждём от Frontend
|
||||
- —
|
||||
|
||||
## Ближайшее
|
||||
- —
|
||||
|
||||
## Известные проблемы и долги
|
||||
- —
|
||||
@@ -0,0 +1,24 @@
|
||||
# Состояние: Frontend
|
||||
|
||||
Обновлено: 2026-11-08 · Владелец: Frontend-разработчик
|
||||
|
||||
Снимок, а не история. Внутренние правила зоны — `docs/frontend/`.
|
||||
|
||||
## Сейчас
|
||||
- Кода нет. Впереди в шаге 1: макеты и информационная архитектура (#1.11), окно Помощника (#1.9.7), PoC трея Tauri (#1.8.1–1.8.2).
|
||||
|
||||
## Сделано в текущем шаге
|
||||
- —
|
||||
|
||||
## В работе
|
||||
<!-- - #ID · ветка · что осталось -->
|
||||
- —
|
||||
|
||||
## Ждём от Backend
|
||||
- —
|
||||
|
||||
## Ближайшее
|
||||
- —
|
||||
|
||||
## Известные проблемы и долги
|
||||
- —
|
||||
@@ -0,0 +1,32 @@
|
||||
# Состояние: общее (shared)
|
||||
|
||||
Обновлено: 2026-11-08 · Шаг 1 «Решения и подготовка» · Версия —
|
||||
|
||||
Снимок, а не история. Правила — `docs/ai/PROTOCOL.md`, разделы 2 и 6.
|
||||
|
||||
## Сейчас
|
||||
- Продуктового кода нет. Идёт шаг 1: решения, Gitea, окружение, макеты.
|
||||
- Дорожная карта на сервере работает (#1.1 выполнено).
|
||||
- Введена система документирования для AI: `docs/ai/`, `docs/status/`, `docs/journal/`, `tools/roadmap-context/`.
|
||||
|
||||
## Контракты
|
||||
| Контракт | Состояние | Последнее изменение |
|
||||
|---|---|---|
|
||||
| `api/openapi.yaml` | нет, шаг 2 (#2.5) | — |
|
||||
| `proto/agent/v1`, `proto/helper/v1` | нет, шаг 2 (#2.6) | — |
|
||||
| `migrations/` | нет, шаг 2 (#2.11) | — |
|
||||
| Каталог функций `docs/features.md` | нет, шаг 2 (#2.3) | — |
|
||||
|
||||
## Принятые решения (кратко, со ссылкой)
|
||||
- —
|
||||
|
||||
## Готово для другой стороны
|
||||
<!-- Формат: - YYYY-MM-DD · зона → зона · что готово · где (путь, эндпоинт, ADR) -->
|
||||
- —
|
||||
|
||||
## Запросы между зонами
|
||||
<!-- Формат: - [ ] YYYY-MM-DD · от зоны → к зоне · что нужно · зачем · #ID -->
|
||||
- —
|
||||
|
||||
## Блокеры
|
||||
- —
|
||||
Reference in new issue
Block a user