Папка 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>
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:
AGENTS.md(обычно подгружается сам) и этот файл.docs/status/shared.md,docs/status/<зона>.mdи личные заметкиdocs/private/(если папка есть; если нет — создайdocs/private/notes.mdпо шаблонуdocs/ai/templates/private-notes.md).- Журнал: последние 5 записей своей зоны и все записи
impact: sharedновее твоей последней записи (docs/journal/, имена файлов сортируются по дате). - Дорожная карта:
node tools/roadmap-context/roadmap-context.mjs(текущий шаг) и... <ID задачи>для задачи сессии. Подробности и запасные варианты —docs/ai/roadmap.md. - Git: текущая ветка,
git status,git log --oneline -15 origin/main. Есть ли смерженные PR другой стороны после последнего обновления статуса. - Отчитайся пользователю (не больше 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. - Секретов, паролей, токенов, внутренних адресов стенда и персональных данных в документах нет.
- Блок «Для дорожной карты» выведен пользователю в чат:
Человек переносит это в карту сам. Описание PR можно взять кнопкой «Для PR» в задаче карты.
Задача: #2.11 → статус: На проверке Отметить пункты: 2.11.4, 2.11.6 Сообщение (Комментарий/Вопрос/Блокер/Решение): <текст> Поле «Решение»: <текст, если есть> Ссылка: PR <URL> (после открытия)
Документы коммитятся в той же ветке, что и код (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).