<!-- Название PR: «[ID] Что сделано», по-русски. Например: [2.11] Изоляция организаций --> **Задача:** #<!-- ID задачи в дорожной карте --> **Пункты:** <!-- 2.11.4, 2.11.6 --> ## Что сделано - ## Как проверить 1. ## Скриншоты <!-- Для изменений интерфейса. Иначе удалить раздел. --> ## Чек-лист - [ ] Коммиты и название PR по-русски, в каждом коммите есть `Refs:` - [ ] Ветка свежая: `git rebase origin/main`, конфликтов нет - [ ] Запросы к данным организации — с `tenant_id` и через `WithTenantTx` - [ ] Права проверяются на сервере (`access.Require` / `ScopesFor`), интерфейс только скрывает - [ ] Новая функция — за флагом из каталога функций - [ ] Миграции только новые, смерженные не изменены; контракты (`api/`, `proto/`, `migrations/`) — отдельным PR - [ ] Тесты добавлены или обновлены; для новой таблицы организации — тест изоляции - [ ] Секретов и персональных данных в коде, логах и документах нет - [ ] Документация обновлена: запись журнала, `docs/status/`, ADR при значимом решении - [ ] Ссылка на этот PR добавлена в «Ссылки» задачи в дорожной карте Reviewed-on: #5 Co-authored-by: BrowenSiz <top.timashevsky@gmail.com>
159 lines
17 KiB
Markdown
159 lines
17 KiB
Markdown
# Протокол 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`. Ассистент другой стороны их не читает и не тратит на них контекст.
|
|
- **Личные заметки — `docs/private/`.** Папка в `.gitignore`: она есть только на компьютере владельца, в Gitea не попадает, второй разработчик и его AI её не видят. Это внутренний «чат» разработчика с AI: черновые мысли, личные договорённости с ассистентом, заметки по текущей работе, контекст между сессиями. Файлы: `docs/private/notes.md` (основной), при необходимости другие. Правила:
|
|
- ассистент читает `docs/private/` в начале сессии и дописывает туда то, что нужно помнить только владельцу;
|
|
- всё, что нужно другой стороне или проекту (решения, изменения поведения, договорённости), идёт в `docs/status`, `docs/journal` или ADR, а не только в `private`;
|
|
- ассистент не переносит текст из `private` в файлы под git без согласия владельца;
|
|
- секреты и пароли не хранятся и здесь — только в менеджере паролей. Резервную копию папки владелец делает сам.
|
|
- **Как определить зону сессии:** 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` и личные заметки `docs/private/` (если папка есть; если нет — создай `docs/private/notes.md` по шаблону `docs/ai/templates/private-notes.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/private/notes.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>`.
|
|
|
|
**Коммиты, названия и описания PR — только на русском** (правило в `AGENTS.md`, раздел 6): `тип(область): что сделано`, тип и область латиницей, остальное по-русски, понятно и конкретно. Ассистент сам предлагает сообщение коммита в этом формате и не использует английские шаблоны своего инструмента.
|
|
|
|
---
|
|
|
|
## 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).`
|