feat: Add presence heartbeat for Matrix online status
- matrix-gateway: POST /internal/matrix/presence/online endpoint - usePresenceHeartbeat hook with activity tracking - Auto away after 5 min inactivity - Offline on page close/visibility change - Integrated in MatrixChatRoom component
This commit is contained in:
Apple
544
CURSOR_WORKFLOW.md
Normal file
544
CURSOR_WORKFLOW.md
Normal file
@@ -0,0 +1,544 @@
|
||||
# 🎯 Гайд по роботі з Cursor для MicroDAO проєкту
|
||||
|
||||
**Організація ефективної роботи з AI асистентом над великим проєктом**
|
||||
|
||||
---
|
||||
|
||||
## 📋 Зміст
|
||||
|
||||
1. [Початкове налаштування](#початкове-налаштування)
|
||||
2. [Структура проєкту](#структура-проєкту)
|
||||
3. [Робочий процес](#робочий-процес)
|
||||
4. [Ефективні промпти](#ефективні-промпти)
|
||||
5. [Оптимізація контексту](#оптимізація-контексту)
|
||||
6. [Найкращі практики](#найкращі-практики)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Початкове налаштування
|
||||
|
||||
### 1. Файли конфігурації
|
||||
|
||||
Проєкт вже має:
|
||||
- ✅ `.cursorrules` - правила для Cursor
|
||||
- ✅ `.cursorignore` - виключення файлів з контексту
|
||||
- ✅ **INFRASTRUCTURE.md** - центральний файл інфраструктури ⭐
|
||||
- ✅ **docs/infrastructure_quick_ref.ipynb** - швидкий довідник ⭐
|
||||
- ✅ `PROJECT_CONTEXT.md` - швидкий контекст
|
||||
- ✅ `docs/cursor/` - 72 документи з документацією
|
||||
|
||||
### 2. Налаштування Cursor
|
||||
|
||||
**Відкрити проєкт:**
|
||||
```
|
||||
File → Open Folder → /Users/apple/github-projects/microdao-daarion
|
||||
```
|
||||
|
||||
**Перевірити налаштування:**
|
||||
- Settings → Features → Composer: увімкнено
|
||||
- Settings → Features → Chat: увімкнено
|
||||
- Settings → AI → Model: вибрати потрібну модель
|
||||
|
||||
### 3. Перший запуск (ОБОВ'ЯЗКОВО)
|
||||
|
||||
**Для нового діалогу з Cursor:**
|
||||
|
||||
1. **Відкрити центральні файли інфраструктури:**
|
||||
- `INFRASTRUCTURE.md` - повна інфраструктура проєкту
|
||||
- `docs/infrastructure_quick_ref.ipynb` - швидкий довідник
|
||||
|
||||
2. **Додати в контекст:**
|
||||
```
|
||||
@INFRASTRUCTURE.md
|
||||
@docs/infrastructure_quick_ref.ipynb
|
||||
```
|
||||
|
||||
3. **Додатково (за потреби):**
|
||||
- `PROJECT_CONTEXT.md` - швидкий контекст проєкту
|
||||
- `docs/cursor/README.md` - навігація по документації
|
||||
- Перевірити поточний статус в `STATUS.md` або `TODO.md`
|
||||
|
||||
---
|
||||
|
||||
## 📁 Структура проєкту
|
||||
|
||||
### Ключові папки
|
||||
|
||||
```
|
||||
microdao-daarion/
|
||||
├── src/ # Frontend (React + TypeScript)
|
||||
│ ├── components/ # React компоненти
|
||||
│ ├── pages/ # Сторінки
|
||||
│ ├── api/ # API клієнти
|
||||
│ ├── services/ # Бізнес-логіка
|
||||
│ └── types/ # TypeScript типи
|
||||
│
|
||||
├── backend/ # Backend сервіси
|
||||
│ ├── services/ # Мікросервіси
|
||||
│ └── microdao/ # Core сервіси
|
||||
│
|
||||
├── docs/ # Документація
|
||||
│ ├── cursor/ # 72 документи для Cursor ⭐
|
||||
│ ├── infrastructure/ # Інфраструктура
|
||||
│ └── integration/ # Інтеграції
|
||||
│
|
||||
├── services/ # Python сервіси
|
||||
│ ├── monitor-agent-service/
|
||||
│ ├── orchestrator/
|
||||
│ └── ...
|
||||
│
|
||||
├── PROJECT_CONTEXT.md # Швидкий контекст ⭐
|
||||
├── CURSOR_WORKFLOW.md # Цей файл
|
||||
├── .cursorrules # Правила для Cursor
|
||||
└── .cursorignore # Виключення з контексту
|
||||
```
|
||||
|
||||
### Важливі документи
|
||||
|
||||
**Для швидкого старту:**
|
||||
- `PROJECT_CONTEXT.md` - загальний огляд
|
||||
- `docs/cursor/00_overview_microdao.md` - детальний огляд
|
||||
- `docs/cursor/01_product_brief_mvp.md` - бізнес-логіка
|
||||
|
||||
**Для розробки:**
|
||||
- `docs/cursor/02_architecture_basics.md` - архітектура
|
||||
- `docs/cursor/03_api_core_snapshot.md` - API контракти
|
||||
- `docs/cursor/05_coding_standards.md` - стандарти коду
|
||||
|
||||
**Для агентів:**
|
||||
- `docs/cursor/08_agent_first_onboarding.md` - агентський онбординг
|
||||
- `docs/cursor/12_agent_runtime_core.md` - Agent Runtime
|
||||
- `docs/cursor/34_internal_services_architecture.md` - сервіси
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Робочий процес
|
||||
|
||||
### Етап 1: Підготовка контексту
|
||||
|
||||
**Перед початком роботи (ОБОВ'ЯЗКОВО для нового діалогу):**
|
||||
|
||||
1. **Додати центральні файли інфраструктури:**
|
||||
```
|
||||
@INFRASTRUCTURE.md
|
||||
@docs/infrastructure_quick_ref.ipynb
|
||||
```
|
||||
Ці файли містять актуальну інформацію про:
|
||||
- Ноди (Node #1, Node #2)
|
||||
- Сервіси та порти
|
||||
- Endpoints та health checks
|
||||
- Telegram боти
|
||||
- Deployment workflow
|
||||
|
||||
2. **Визначити область роботи:**
|
||||
```
|
||||
"Мені потрібно працювати з [компонент/сервіс/функція]"
|
||||
```
|
||||
|
||||
3. **Додати релевантні файли в контекст:**
|
||||
- Відкрити файли в редакторі (Cursor автоматично додасть їх)
|
||||
- Або явно вказати: "Використовуй файли X, Y, Z"
|
||||
|
||||
4. **Посилитися на документацію:**
|
||||
```
|
||||
"Використовуй документацію з docs/cursor/[номер]_[назва].md"
|
||||
```
|
||||
|
||||
### Етап 2: Формулювання задачі
|
||||
|
||||
**Добре сформульована задача:**
|
||||
|
||||
```
|
||||
Задача: Додати нову функцію [назва]
|
||||
|
||||
Контекст:
|
||||
- Компонент: src/components/[назва].tsx
|
||||
- API: docs/cursor/03_api_core_snapshot.md
|
||||
- Стандарти: docs/cursor/05_coding_standards.md
|
||||
|
||||
Вимоги:
|
||||
1. [Вимога 1]
|
||||
2. [Вимога 2]
|
||||
|
||||
Очікуваний результат:
|
||||
- [Що має працювати]
|
||||
```
|
||||
|
||||
**Погано сформульована задача:**
|
||||
```
|
||||
"Зроби щось з чатом"
|
||||
```
|
||||
|
||||
### Етап 3: Виконання та перевірка
|
||||
|
||||
1. **Перевірка коду:**
|
||||
- Чи відповідає стандартам?
|
||||
- Чи використовує існуючі типи?
|
||||
- Чи немає дублікатів?
|
||||
|
||||
2. **Тестування:**
|
||||
- Запустити локально
|
||||
- Перевірити згідно `docs/cursor/07_testing_checklist_mvp.md`
|
||||
|
||||
3. **Документування:**
|
||||
- Оновити статусні файли якщо потрібно
|
||||
- Додати коментарі до складного коду
|
||||
|
||||
---
|
||||
|
||||
## 💬 Ефективні промпти
|
||||
|
||||
### Шаблон 1: Створення нового компонента
|
||||
|
||||
```
|
||||
Створи React компонент [Назва] згідно специфікації:
|
||||
|
||||
Контекст:
|
||||
- UI/UX: docs/cursor/04_ui_ux_onboarding_chat.md
|
||||
- Стандарти: docs/cursor/05_coding_standards.md
|
||||
- Типи: src/types/[назва].ts
|
||||
|
||||
Вимоги:
|
||||
- [Вимога 1]
|
||||
- [Вимога 2]
|
||||
|
||||
Використай існуючі компоненти з src/components/ якщо можливо.
|
||||
```
|
||||
|
||||
### Шаблон 2: Виправлення бага
|
||||
|
||||
```
|
||||
Виправ баг в [компонент/сервіс]:
|
||||
|
||||
Проблема:
|
||||
- [Опис проблеми]
|
||||
- [Кроки для відтворення]
|
||||
|
||||
Очікуваний результат:
|
||||
- [Що має працювати]
|
||||
|
||||
Файли:
|
||||
- [Шлях до файлу]
|
||||
```
|
||||
|
||||
### Шаблон 3: Рефакторинг
|
||||
|
||||
```
|
||||
Рефактори [компонент/сервіс] для:
|
||||
|
||||
Мета:
|
||||
- [Мета рефакторингу]
|
||||
|
||||
Вимоги:
|
||||
- Зберегти існуючу функціональність
|
||||
- Покращити [що саме]
|
||||
- Дотриматися docs/cursor/05_coding_standards.md
|
||||
|
||||
Файли:
|
||||
- [Список файлів]
|
||||
```
|
||||
|
||||
### Шаблон 4: Інтеграція з API
|
||||
|
||||
```
|
||||
Інтегрируй [компонент] з API:
|
||||
|
||||
API специфікація:
|
||||
- docs/cursor/03_api_core_snapshot.md
|
||||
- Endpoint: [назва endpoint]
|
||||
|
||||
Компонент:
|
||||
- src/components/[назва].tsx
|
||||
|
||||
Використай існуючий API клієнт з src/api/ якщо можливо.
|
||||
```
|
||||
|
||||
### Шаблон 5: Робота з агентами
|
||||
|
||||
```
|
||||
Реалізуй [функцію агента] згідно специфікації:
|
||||
|
||||
Документація:
|
||||
- docs/cursor/[номер]_[назва]_agent.md
|
||||
- docs/cursor/12_agent_runtime_core.md
|
||||
|
||||
Сервіс:
|
||||
- services/[назва]-service/
|
||||
|
||||
Вимоги:
|
||||
- [Список вимог]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Оптимізація контексту
|
||||
|
||||
### Що включено автоматично
|
||||
|
||||
Cursor автоматично додає в контекст:
|
||||
- Відкриті файли в редакторі
|
||||
- Файли з `.cursorrules`
|
||||
- `PROJECT_CONTEXT.md` (якщо вказано)
|
||||
|
||||
### Центральні файли інфраструктури (ОБОВ'ЯЗКОВО)
|
||||
|
||||
**Для нового діалогу завжди додавати:**
|
||||
- `INFRASTRUCTURE.md` - повна інфраструктура проєкту
|
||||
- `docs/infrastructure_quick_ref.ipynb` - швидкий довідник
|
||||
|
||||
**Що міститься:**
|
||||
- Ноди (Node #1: Hetzner, Node #2: MacBook)
|
||||
- Сервіси та порти (17+ сервісів)
|
||||
- Endpoints та health checks
|
||||
- Telegram боти (DAARWIZZ, Helion)
|
||||
- Deployment workflow
|
||||
- Кабінети НОД та мікроДАО
|
||||
|
||||
### Що виключено через `.cursorignore`
|
||||
|
||||
- `node_modules/`, `venv/`, `__pycache__/`
|
||||
- Логи та тимчасові файли
|
||||
- Статусні файли (`*-COMPLETE.md`, `*-STATUS.md`)
|
||||
- SVG та PDF файли
|
||||
- Тестові дані та coverage
|
||||
|
||||
### Як додати контекст вручну
|
||||
|
||||
**В чаті:**
|
||||
```
|
||||
@filename - додати файл
|
||||
@folder - додати папку
|
||||
@codebase - пошук по коду
|
||||
```
|
||||
|
||||
**В Composer:**
|
||||
- Відкрити файли в редакторі перед викликом
|
||||
- Або вказати шляхи в промпті
|
||||
|
||||
### Рекомендації по контексту
|
||||
|
||||
✅ **Добре:**
|
||||
- **Завжди починати з `INFRASTRUCTURE.md` та `docs/infrastructure_quick_ref.ipynb`** (центральний контекст)
|
||||
- Додавати конкретні файли що потрібні
|
||||
- Посилатися на документацію за номером
|
||||
- Використовувати `PROJECT_CONTEXT.md` для швидкого контексту
|
||||
|
||||
❌ **Погано:**
|
||||
- Починати без центральних файлів інфраструктури
|
||||
- Додавати всю папку `src/` (занадто багато)
|
||||
- Додавати статусні файли (не потрібні)
|
||||
- Додавати `node_modules/` (виключено, але не треба)
|
||||
|
||||
---
|
||||
|
||||
## ✨ Найкращі практики
|
||||
|
||||
### 1. Робота з великим проєктом
|
||||
|
||||
**Розбивайте на підзадачі:**
|
||||
```
|
||||
Замість: "Зроби всю систему агентів"
|
||||
Краще: "Створи базовий Agent Runtime згідно docs/cursor/12_agent_runtime_core.md"
|
||||
```
|
||||
|
||||
**Використовуйте документацію:**
|
||||
- Завжди починайте з документації в `docs/cursor/`
|
||||
- Посилайтеся на конкретні документи в промптах
|
||||
|
||||
**Перевіряйте існуючий код:**
|
||||
- Перед створенням нового - шукайте існуюче
|
||||
- Використовуйте `codebase_search` для пошуку
|
||||
|
||||
### 2. Ефективне спілкування
|
||||
|
||||
**Будьте конкретні:**
|
||||
```
|
||||
Замість: "Покращ цей компонент"
|
||||
Краще: "Додай валідацію форми в OnboardingStep1 згідно docs/cursor/04_ui_ux_onboarding_chat.md"
|
||||
```
|
||||
|
||||
**Надавайте контекст:**
|
||||
- Які файли використовувати
|
||||
- Які стандарти дотримувати
|
||||
- Який очікуваний результат
|
||||
|
||||
**Задавайте уточнюючі питання:**
|
||||
- Якщо щось незрозуміло - питайте
|
||||
- Краще уточнити, ніж робити неправильно
|
||||
|
||||
### 3. Організація коду
|
||||
|
||||
**Структура компонентів:**
|
||||
```
|
||||
src/components/
|
||||
├── [module]/ # За модулями
|
||||
│ ├── [Component].tsx
|
||||
│ └── [Component].test.tsx
|
||||
```
|
||||
|
||||
**Типи:**
|
||||
```
|
||||
src/types/
|
||||
├── [module].ts # Типи для модуля
|
||||
└── api.ts # API типи
|
||||
```
|
||||
|
||||
**API клієнти:**
|
||||
```
|
||||
src/api/
|
||||
├── [module]Api.ts # API клієнт для модуля
|
||||
└── client.ts # Базовий клієнт
|
||||
```
|
||||
|
||||
### 4. Робота з документацією
|
||||
|
||||
**Навігація:**
|
||||
- `docs/cursor/README.md` - навігація по всіх документах
|
||||
- Нумерація документів: `00_`, `01_`, `02_`...
|
||||
|
||||
**Ключові документи:**
|
||||
- `00_overview_microdao.md` - загальний огляд
|
||||
- `02_architecture_basics.md` - архітектура
|
||||
- `03_api_core_snapshot.md` - API контракти
|
||||
- `05_coding_standards.md` - стандарти коду
|
||||
|
||||
**Для агентів:**
|
||||
- `08-13` - агентська система
|
||||
- `12_agent_runtime_core.md` - ядро runtime
|
||||
- `34_internal_services_architecture.md` - сервіси
|
||||
|
||||
### 5. Тестування та якість
|
||||
|
||||
**Перед комітом:**
|
||||
- Перевірити згідно `docs/cursor/07_testing_checklist_mvp.md`
|
||||
- Запустити локально
|
||||
- Перевірити TypeScript помилки
|
||||
|
||||
**Стандарти коду:**
|
||||
- Дотримуватися `docs/cursor/05_coding_standards.md`
|
||||
- Використовувати ESLint/Prettier
|
||||
- Додавати коментарі до складного коду
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Корисні команди
|
||||
|
||||
### Пошук по коду
|
||||
|
||||
```
|
||||
"Знайди де використовується [функція/компонент]"
|
||||
"Покажи всі місця де викликається [API endpoint]"
|
||||
"Знайди компоненти що роблять [функцію]"
|
||||
```
|
||||
|
||||
### Аналіз коду
|
||||
|
||||
```
|
||||
"Проаналізуй [файл] та запропонуй покращення"
|
||||
"Перевір [компонент] на відповідність стандартам"
|
||||
"Знайди потенційні проблеми в [код]"
|
||||
```
|
||||
|
||||
### Документація
|
||||
|
||||
```
|
||||
"Поясни як працює [компонент/сервіс]"
|
||||
"Створи документацію для [функції]"
|
||||
"Онови документацію в [файл]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Метрики ефективності
|
||||
|
||||
### Час на задачу
|
||||
|
||||
**Малий рефакторинг:** 5-15 хвилин
|
||||
**Новий компонент:** 15-30 хвилин
|
||||
**Інтеграція API:** 20-40 хвилин
|
||||
**Новий сервіс:** 1-2 години
|
||||
|
||||
### Якщо задача займає більше часу
|
||||
|
||||
1. Розбийте на підзадачі
|
||||
2. Перевірте чи є вся необхідна документація
|
||||
3. Уточніть вимоги
|
||||
4. Перевірте чи немає конфліктів з існуючим кодом
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Приклади успішної роботи
|
||||
|
||||
### Приклад 1: Створення нового компонента
|
||||
|
||||
**Промпт:**
|
||||
```
|
||||
Створи компонент AgentCard згідно специфікації:
|
||||
|
||||
Документація:
|
||||
- docs/cursor/23_agent_cards_and_console.md
|
||||
- docs/cursor/04_ui_ux_onboarding_chat.md
|
||||
|
||||
Вимоги:
|
||||
- Відображає інформацію про агента
|
||||
- Підтримує клік для відкриття консоли
|
||||
- Використовує Tailwind CSS
|
||||
- TypeScript strict mode
|
||||
|
||||
Використай існуючі типи з src/types/agents.ts
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- Створено компонент з правильними типами
|
||||
- Відповідає стандартам
|
||||
- Інтегровано з існуючим кодом
|
||||
|
||||
### Приклад 2: Виправлення бага
|
||||
|
||||
**Промпт:**
|
||||
```
|
||||
Виправ баг в MonitorChat компоненті:
|
||||
|
||||
Проблема:
|
||||
- Повідомлення не зберігаються після перезавантаження
|
||||
- Файл: src/components/monitor/MonitorChat.tsx
|
||||
|
||||
Очікуваний результат:
|
||||
- Повідомлення зберігаються в localStorage
|
||||
- Відновлюються при завантаженні
|
||||
|
||||
Використай існуючий паттерн з інших чатів.
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- Баг виправлено
|
||||
- Додано збереження в localStorage
|
||||
- Відповідає існуючим паттернам
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Корисні посилання
|
||||
|
||||
- **Документація Cursor:** https://docs.cursor.com
|
||||
- **Проєкт:** `/Users/apple/github-projects/microdao-daarion`
|
||||
- **API:** https://api.microdao.xyz/v1
|
||||
- **Документація проєкту:** `docs/cursor/README.md`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Чеклист перед початком роботи
|
||||
|
||||
- [ ] **Відкрито `INFRASTRUCTURE.md` (ОБОВ'ЯЗКОВО для нового діалогу)**
|
||||
- [ ] **Відкрито `docs/infrastructure_quick_ref.ipynb` (ОБОВ'ЯЗКОВО для нового діалогу)**
|
||||
- [ ] Відкрито правильну папку проєкту
|
||||
- [ ] Переглянуто `PROJECT_CONTEXT.md`
|
||||
- [ ] Визначено область роботи
|
||||
- [ ] Знайдено релевантну документацію
|
||||
- [ ] Перевірено існуючий код
|
||||
- [ ] Сформульовано конкретну задачу
|
||||
|
||||
---
|
||||
|
||||
**Останнє оновлення:** 2025-01-XX
|
||||
**Версія:** 1.0.0
|
||||
|
||||
Reference in New Issue
Block a user