Aloha Browser · AI-first Documentation System

Документация,
которую ведут AI‑агенты

Единый источник правды для всех команд. Один файл — все роли. Привязка к фичам, экранам и ClickUp. Автоматическая генерация, синхронизация с кодом, тест-кейсы в Qase.

8
AI‑агентов в системе
~40 мин
от идеи до документа
4 роли
один файл для всех
0
шаблонов заполнять вручную
Claude API + GitHub Actions Git + Markdown ClickUp MCP Docusaurus портал Qase тест-кейсы Amplitude метрики
01
Раздел первый

Архитектура системы

Три слоя: хранилище, AI‑агенты, ролевые представления. Каждый слой независим и может развиваться отдельно.

💡
Ключевой принцип: один файл feature.md содержит всё — продуктовое описание, спеку, тест-кейсы, маркетинг. Разделение через секции и frontmatter, а не через отдельные файлы. AI‑агенты читают и обновляют этот файл автоматически.
1
Хранилище — единый источник правды
Git репозиторий + Markdown файлы + публичный Docusaurus портал
Git + Markdown
📁
docs/features/
Одна папка на фичу. Имя = slug. Привязка к ClickUp task ID через frontmatter.
📄
feature.md
Один файл — все роли. Frontmatter управляет видимостью секций. Версионируется в Git.
🗺
_index.yaml
Реестр всех фич для AI‑агентов. Содержит id, path, status, tags, screens.
🌐
Docusaurus портал
Публичный сайт с SSO. Фильтрует контент по роли. Деплой автоматически из main.
🏗
decisions/ (ADR)
Архитектурные решения. Нумерованные файлы. Объясняют почему, не только что.
AI‑агенты читают и пишут
⇅
2
AI‑агенты — автоматизация
Claude API внутри GitHub Actions. Триггеры: PR, merge, schedule, ClickUp webhook.
Claude API
✍️
Doc Writer
Вольный текст PM → структурированный feature.md. Триггер: ClickUp webhook при создании задачи.
🔍
Code Reader
Читает существующий код → генерирует документацию. Заполняет секции spec и implementation.
✅
Doc Reviewer
При открытии PR проверяет полноту документа. Задаёт вопросы команде. Не блокирует merge.
🔄
Doc Sync
При merge смотрит diff кода. Предлагает обновления в /docs. Dev апрувит одним кликом.
🧪
Test Generator
Из каждого AC → позитивный + негативный + edge case тест. Пушит напрямую в Qase.
📊
Metrics Writer
После релиза берёт данные из Amplitude. Дописывает ## results с реальными показателями.
ролевые представления
⇅
3
Ролевые представления — один документ, разные виды
RBAC через frontmatter. Один URL — разный контент в зависимости от роли.
RBAC
🎯
PM — продуктовый вид
Цели, user stories, behaviour, метрики успеха, roadmap связи с другими фичами.
⚙️
Dev — технический вид
Спека, API, data models, entry points, constraints, ADR. Видит все секции.
🧪
QA — тестовый вид
Acceptance criteria, тест-кейсы в Qase, edge cases, regression checklist.
📣
Marketing — контентный вид
App Store copy, release notes, соцсети, блог. Без технических деталей.
02
Раздел второй

Процесс создания документации

От вольной идеи PM до маркетинговых материалов. Максимум автоматизации, минимум ручного труда.

1
PM описывает фичу в вольном формате
Голосовая заметка, Slack, черновик — любой формат. Минимум: что делает, зачем, для кого. Никаких шаблонов.
👤 PM · 10–15 мин
→ raw_input.txt
2
AI создаёт черновик feature.md
Агент структурирует входной текст: заполняет все секции, создаёт frontmatter, ищет конфликты с существующими документами.
🤖 Claude API⚡ авто-триггер
→ feature.md (draft)→ conflicts-report
3
Doc Review — AI задаёт конкретные вопросы
Агент находит пробелы: нет AC, нет метрик, вольный текст вместо Given/When/Then. Задаёт вопросы с объяснением. Команда только отвечает.
🤖 Doc Reviewer👤 PM+Dev ответы
→ questions.md→ ClickUp задачи
4
Финализация и создание задач в ClickUp
AI вносит ответы, финализирует секции, создаёт задачи из acceptance criteria, линкует документ через clickup_id.
🤖 автоматически
→ feature.md (final)→ ClickUp tasks
5
Разработка — doc живёт рядом с кодом
При каждом PR Doc Sync смотрит diff и предлагает обновления документации. Разработчик апрувит или отклоняет — одним кликом.
⚡ при каждом PR👤 Dev апрув
→ feature.md (synced)
6
Генерация тест-кейсов в Qase
Test Generator читает каждый AC → позитивный сценарий + негативный + edge case. QA получает готовый чеклист без написания.
🤖 Test Generator⚡ авто
→ Qase test cases
7
После релиза — doc обновляется реальными данными
Metrics Writer читает Amplitude. Дописывает ## results с реальными показателями vs плановыми. Документ становится историческим артефактом.
🤖 Metrics Writer⚡ после релиза
→ ## results→ Amplitude dashboard
8
Маркетинговые материалы из документа
AI генерирует App Store заголовок, user story → выгода, метрики → social proof. 2–3 варианта каждого текста. Маркетолог только выбирает.
🤖 Content Generator👤 Marketing апрув
→ App Store copy→ release notes→ social posts
Участие команды
Шаги 1, 3 PM · ~25 мин
Шаг 5 Dev · ~5 мин/PR
Шаг 6 QA · 0 мин
Шаг 8 Mkt · ~10 мин
Всё остальное AI · авто
Триггеры автоматизации
ClickUp webhook → новая задача → Doc Writer
GitHub PR opened → Doc Reviewer
GitHub PR merged → Doc Sync + Test Generator
Release tag → Metrics Writer + Content Generator
03
Раздел третий

Анатомия документа фичи

Один файл feature.md содержит все роли. Frontmatter управляет видимостью. Пример на основе реальной задачи из вашего ClickUp.

docs/features/tabs/tab-manager-redesign.md
--- # FRONTMATTER — машиночитаемый id: tab-manager-redesign status: stable platform: [ios, android] clickup_id: 86er2gdk8 owner: @Andrey Palagichev screens: [TabManager, SpeedDial] tags: [tabs, ui, navigation] visible_to:   product: [pm, dev, qa]   spec: [dev]   qa: [dev, qa]   marketing: [marketing, pm] ---   ## summary Изменён способ отображения табов — двухколоночная сетка вместо списка.   ## product # PM, Dev, QA Цели, user story, context...   ## behaviour Given / When / Then сценарии...   ## acceptance-criteria 1. Табы рендерятся в 2 колонки (portrait) 2. Минимум 136px, максимум 240px   ## spec # только Dev Технические требования, API...   ## implementation entry: src/tabs/TabManagerViewController figma: figma.com/file/...   ## qa # Dev + QA Edge cases, regression checklist... test-cases: qase.io/ALOHA-1084   ## marketing # Marketing + PM App Store copy, release notes...   ## results # после релиза DAU: +12% vs baseline. Crash: 0.02%
Все роли
Frontmatter машиночитаемый. AI‑агенты используют id, clickup_id, screens для навигации и маршрутизации задач.
PM
Видит: product, behaviour, acceptance-criteria, marketing. Не видит: spec, implementation details.
Dev
Видит всё. Секции spec и implementation — только для разработчика. Entry points помогают AI при генерации из кода.
QA
Acceptance criteria → автоматически в Qase. Ссылка на тест-кейсы хранится в документе вместе с edge cases.
Marketing
Секция marketing — готовые тексты. AI генерирует из summary и user story. Маркетолог только апрувит.
После релиза
Секция results — фактические метрики из Amplitude. Документ становится историческим артефактом со всей жизнью фичи.
04
Раздел четвёртый

Ролевой доступ к документации

Один URL на фичу — разный контент. Запрос «покажи документацию по экрану TabManager для QA» возвращает только нужные секции.

PM
Product Manager
Создаёт и редактирует требования
✓
Продуктовое описание
Цели, user stories, контекст
✓
Behaviour сценарии
Given/When/Then флоу
✓
Acceptance criteria
Список критериев приёмки
✓
Success metrics
KPI, целевые показатели
—
Технические спеки
Скрыто — только Dev
DEV
Developer
Реализует, синхронизирует с кодом
✓
Технические спеки
API, data models, constraints
✓
Implementation pointers
Entry points, key files, Figma
✓
Edge cases
Граничные условия и платформы
✓
ADR — решения
Почему выбрано это решение
✓
Все секции
Dev имеет полный доступ
QA
QA Engineer
Тестирует по готовому чеклисту
✓
Acceptance criteria
Пронумерованный список
✓
Тест-кейсы (авто)
Ссылки на Qase, созданные AI
✓
Edge cases
0 табов, 100+ табов, landscape
✓
Regression checklist
Что проверить при изменениях
—
Маркетинговые тексты
Скрыто — только Marketing
MKT
Marketing
Апрувит готовый контент
✓
App Store copy
Заголовок и описание — авто
✓
Release notes
Что нового для пользователей
✓
Соцсети и блог
Черновики из summary и метрик
✓
User-facing описание
Польза для пользователя
—
Тех. спеки и реализация
Скрыто — только Dev
05
Раздел пятый

Миграция из ClickUp

У вас уже есть MCP-коннектор к ClickUp. Миграция — это не переезд, а создание второго слоя. ClickUp остаётся трекером задач.

⚠️
Важно: ClickUp не заменяется. Он остаётся для спринтов, трекинга и workflow. Система /docs — отдельный слой знаний, связанный с ClickUp через clickup_id в frontmatter каждого документа.
Сейчас в ClickUp
962-страничный монолитный PDF
Задачи без AC и Given/When/Then
Figma-ссылки в описаниях задач
Кастомные поля: Test case link, branch
Комментарии и история изменений
~10 пространств, 50+ листов
Нет структуры для AI‑агентов
Нет ролевого доступа к контенту
→
AI
парсит
&
структурирует
После миграции в /docs
Один feature.md на фичу
Frontmatter с clickup_id (двусторонняя связь)
Figma → секция ## implementation
Тест-кейсы → Qase (ссылка в документе)
Changelog из истории задач
_index.yaml — карта для AI‑агентов
Ролевые секции через frontmatter
Docusaurus портал с поиском
Шаги миграции
1
Экспорт задач через ClickUp MCP (уже подключён)
Читаем все spaces: Aloha iOS, Aloha Android, Aloha Desktop. Приоритет: задачи со статусом done и in progress.
2
AI‑агент парсит каждую задачу → feature.md
Quill-формат → Markdown. Кастомные поля → frontmatter. Figma-ссылки → ## implementation. Комментарии → ## changelog.
3
Организация по доменам
vpn/ · wallet/ · tabs/ · downloads/ · news-feed/ · ai-features/ · premium/ · security/ · browser-core/ — на основе листов ClickUp.
4
Генерация _index.yaml
Реестр всех фич с id, path, status, tags, screens. AI‑агенты находят документ по экрану или фиче за один запрос.
5
Ревью-пасс — AI проверяет полноту
Doc Reviewer пробегает по всем файлам. Создаёт задачи в ClickUp с приоритетами: критично (нет AC) vs желательно (нет метрик).
6
Пилот на 5–10 фичах, потом полная миграция
Рекомендуется начать с VPN и Tabs — хорошо знакомые фичи с реальными задачами в ClickUp которые уже исследовались.
06
Раздел шестой

Вопросы для обсуждения

Ключевые решения, которые нужно принять команде перед запуском. Нет правильных ответов — зависит от приоритетов.

01 · Стратегия
С какой фичи начать пилот?
VPN и Tabs — хорошо знакомые домены с реальными задачами. Или выбрать новую фичу в разработке, чтобы протестировать весь процесс с нуля?
02 · Ответственность
Кто owner документации по фиче?
PM создаёт, Dev поддерживает, Tech Writer следит за качеством? Или PM — единственный owner, а Dev только комментирует технические секции?
03 · Инструменты
Где PM редактирует документы?
Docusaurus inline-editor (требует настройки)? Notion с синхронизацией в Git? Или напрямую в GitHub через веб-интерфейс?
04 · Миграция
Мигрировать весь архив или только активные фичи?
Все 962 страницы дадут полноту, но займут время. Можно начать только с фич в активной разработке и Current Releases.
05 · Интеграция
Как связать с Figma и Qase?
Figma-ссылки уже есть в задачах ClickUp — перенести в ## implementation. Qase — создавать тесты из существующих AC или только для новых фич?
06 · Культура
Как убедить команду обновлять документы?
Doc Sync предлагает обновления автоматически — трение минимально. Но нужен ли периодический ревью? Кто следит за актуальностью?
07 · AI агенты
Какой агент запускать первым?
Doc Writer даёт быстрый результат — создание из ClickUp задач. Doc Sync меняет процесс разработки. Что важнее сейчас?
08 · Контент
Нужен ли публичный портал?
Docusaurus можно использовать только внутри команды (private). Или сделать публичную документацию для разработчиков и партнёров?
09 · Метрики
Как измерить успех системы?
% фич с заполненными AC? Время от задачи до готового документа? Скорость онбординга? Количество вопросов «где это в коде?»