microdao-daarion/CURSOR_WORKFLOW.md

# 🎯 Гайд по роботі з 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