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