Files
shtil/docs/ai/PROTOCOL.md
T
TMSHandDevin b1d27877c9 docs: добавлены личные заметки разработчика вне git
Папка docs/private/ в .gitignore: внутренние заметки каждого разработчика с AI, которые не видит напарник. Общий контекст по-прежнему в status, journal и ADR.

Refs: 1.2

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-11-09 16:26:27 +03:00

17 KiB

Протокол 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).