Skip to main content

Repository Refactoring Methodology & Plan

Комплексная методология для решения проблем контекста и восстановления эффективности AI-агента

🎯 Проблемы, которые мы решаем​

  1. Потеря контекста AI-агентом - слишком много несвязанного кода в одном репо
  2. Снижение качества разработки - мелкие баги из-за неправильного контекста
  3. Медленное восстановление контекста - 10+ действий вместо 2-3
  4. Смешение приоритетов - продакшн код (Mercury) смешан с экспериментами
  5. Устаревшая FDD методология - не учитывает специфику AI workflow

🏆 Выбранное решение: Smart Monorepo с AI-контекстными Workspace'ами (Cursor 0.50.7 Edition)​

Источник: Изначальная концепция Gemini 2.5-pro, o3, deepthink r1, grok3, обновленная под реалии Cursor 0.50.7.

Почему именно этот подход?​

  • ✅ Сохраняет все преимущества pnpm monorepo (shared modules, единая сборка)
  • ✅ Минимальные изменения в структуре кода по сравнению с радикальным разделением
  • ✅ Максимальная эффективность для AI через:
    • Multi-root Workspaces: Изоляция доменов на уровне IDE.
    • @folders: Мгновенный полный контекст для домена.
    • AI-Manifest.md: Высокоуровневые инструкции и описание домена.
    • Path-based .cursor/rules: Автоматическое применение правил внутри домена.
    • Background Agents: Автономное выполнение задач в четко определенном контексте.
  • ✅ Постепенное внедрение без рисков для продакшна.
  • ✅ Масштабируемость - легко перейти к multi-repo при необходимости.
  • ✅ Обучающий компонент: Помогает освоить новые фичи Cursor.

📁 Новая структура репозитория​

ton-arcana/
├── products/                     # Основные продукты
│   ├── mercury/                  # 🥇 Приоритет #1
│   │   ├── backend/              # apps/mercury
│   │   ├── dashboard/            # apps/mercury-dashboard
│   │   ├── ai-manifest.md        # AI-навигация
│   │   └── package.json
│   ├── arcana/
│   │   ├── backend/              # apps/arcana-backend
│   │   ├── twa/                  # apps/arcana-twa
│   │   ├── ai-manifest.md
│   │   └── package.json
│   ├── anytracker/
│   │   ├── backend/              # apps/anytracker-backend
│   │   ├── mini-app/             # apps/anytracker-mini-app
│   │   └── ai-manifest.md
│   └── maschine/                 # Консолидированные фичи
├── shared/                       # Общие пакеты (packages/*)
│   ├── core/
│   │   ├── common-utils/
│   │   ├── types/
│   │   └── auth-utils/
│   ├── integrations/
│   │   ├── kaido-telegram/
│   │   ├── kaido-ton/
│   │   ├── kaido-ollama/
│   │   └── openai-utils/
│   └── domain/
│       ├── kaido-talib/          # TS wrapper для TA
│       └── curvinator/           # Legacy но используемый
├── platform/                    # Инфраструктура и документация
│   ├── infra/
│   │   ├── ansible/
│   │   ├── docker/
│   │   └── grafana/
│   ├── docs/
│   │   ├── mercury/              # Продукт-специфичная документация
│   │   ├── arcana/
│   │   └── platform/             # Общая документация, ADR
│   └── scripts/                  # Утилиты разработки
├── archive/                      # Deprecated код
│   ├── mercury-ta/               # Python TA API (deprecated)
│   ├── k8s/                      # Неактуальные k8s конфиги
│   ├── mcp-task-warrior/         # Эксперимент MCP
│   └── kaido.team/               # Пустой публичный блог
├── workspaces/                   # VS Code Multi-Root Workspace конфиги
│   ├── mercury.code-workspace    # Фокус на Mercury
│   ├── arcana.code-workspace     # Фокус на Arcana
│   ├── anytracker.code-workspace # Фокус на AnyTracker
│   └── platform.code-workspace   # Фокус на Platform/Infra
├── pnpm-workspace.yaml
└── package.json

🤖 AI-First Context Recovery Система (Cursor 0.50.7 Native)​

1. AI-Manifest файлы (Сохраняются)​

Каждый продукт (products/mercury/ai-manifest.md, products/arcana/ai-manifest.md и т.д.) по-прежнему содержит ai-manifest.md. Это высокоуровневое описание домена, его назначения, ключевых технологий, модулей и специфичных AI-инструкций. AI-Manifest НЕ ЗАМЕНЯЕТ Rules, а дополняет их, давая "человеческое" описание проекта.

# Mercury AI Manifest

## Назначение

Торговая система с мифологической архитектурой модулей для автоматического трейдинга.

## Статус: production (высокий приоритет)

## Ключевые технологии

- NestJS (backend)
- React (dashboard)
- TypeScript
- Redis (очереди)
- PostgreSQL + MicroORM

## Основные модули

- **APOLLO**: Анализ портфеля и метрики
- **DIKE**: Турнирная система сравнения рынков
- **TYCHE**: Ранжирование рынков и поиск sweet spots
- **KAIROS**: Исполнение стратегий в правильный момент

## Точки входа

- `backend/src/main.ts` - основное приложение
- `dashboard/src/main.tsx` - фронтенд

## AI-инструкции (Высокоуровневые, дополняют .cursor/rules)

- ИСПОЛЬЗУЙ `kaido-talib` (TS) вместо `mercury-ta` (Python) - _Это будет продублировано в .cursor/rules_
- НЕ используй дефолтные порты (dangerous*defaults rule) - *Это будет продублировано в .cursor/rules\_
- Все модули именованы по греческим/римским богам - _Это будет продублировано в .cursor/rules_
- Фокус на модуле DIKE в текущем спринте

2. Multi-Root VS Code Workspace Configuration (Вместо старых .code-workspace)​

Создаются Multi-Root Workspaces для каждого основного домена. Например, workspaces/mercury.code-workspace будет включать:

// workspaces/mercury.code-workspace
{
  "folders": [
    { "path": "../products/mercury", "name": "Product: Mercury" }, // Относительный путь от файла .code-workspace
    { "path": "../shared/core", "name": "Shared: Core Libs" },
    { "path": "../shared/domain/kaido-talib", "name": "Shared: Kaido TALib" },
    { "path": "../platform/docs/mercury", "name": "Docs: Mercury" }
    // При необходимости можно добавить другие релевантные shared/* или platform/* папки
  ],
  "settings": {
    // Настройки специфичные для этого воркспейса
    "editor.rulers": [80, 120],
    "files.exclude": {
      // Можно скрыть нерелевантные части монорепо, если необходимо
      // Но @folders и так обеспечит точность контекста AI
    },
    "search.exclude": {
      // Исключаем все, что не относится к Mercury и его прямым зависимостям
      "**/products/arcana/**": true,
      "**/products/anytracker/**": true,
      "**/archive/**": true,
      "**/node_modules/**": true
    },
    // Cursor 0.50.7+ specific settings
    "cursor.chat.defaultModel": "claude-3.5-sonnet", // Пример
    "cursor.ai.projectStructure.includeInContext": true, // Помогает AI понимать структуру в воркспейсе
    "cursor.ai.projectStructure.prioritize": ["products/mercury"] // Приоритет для авто-контекста
  },
  "extensions": {
    "recommendations": [
      "ms-vscode.vscode-typescript-next",
      "bradlc.vscode-tailwindcss",
      "esbenp.prettier-vscode"
    ]
  }
}

Ключевое отличие: Каждый .code-workspace файл теперь определяет изолированное рабочее окружение для конкретного домена, явно включая нужные части монорепо.

3. Контекст и Управление AI с Cursor 0.50.7 (Замена Dynamic Context Switching)​

Старый механизм cp .ai-contexts/mercury.json .ai-context.json полностью заменяется нативными функциями Cursor:

  • Открытие Workspace: Разработчик открывает нужный workspaces/mercury.code-workspace для работы над Mercury. Это автоматически устанавливает правильные folders и settings.
  • @folders: Для предоставления AI полного контекста домена используется команда @folders products/mercury (или более специфичные пути внутри воркспейса). AI увидит все файлы в указанных папках.
  • Path-based .cursor/rules: Внутри products/mercury/.cursor/rules создаются правила, специфичные для Mercury (например, запрет mercury-ta, использование мифологических имен). Эти правила применяются автоматически, когда AI работает с файлами в products/mercury/. 
    # products/mercury/.cursor/rules
    When working in products/mercury/:
    - NEVER import from mercury-ta, ALWAYS use kaido-talib
    - Use mythological naming (APOLLO, DIKE, TYCHE, etc.)
    - NO hardcoded ports (dangerous_defaults rule)
    - Background jobs MUST use Redis queues
  • Background Agents: Задачи для AI можно делегировать Background Agent'ам. Агент будет работать в контексте активного воркспейса и примененных @folders и правил. 
    Background Agent: "@folders products/mercury - Refactor DIKE module to use new TournamentService"
  • Rules Generation: Успешные взаимодействия с AI, приведшие к хорошему коду, можно использовать для генерации новых правил командой /Generate Cursor Rules.

package.json scripts:

Скрипты ctx:* теперь будут просто открывать соответствующий .code-workspace файл, если это удобно, или могут быть удалены за ненадобностью, так как переключение происходит через IDE.

{
  "scripts": {
    // Старые ctx:* скрипты заменяются
    "workspace:mercury": "code workspaces/mercury.code-workspace", // Открывает VS Code с нужным воркспейсом
    "workspace:arcana": "code workspaces/arcana.code-workspace",
    // ... другие полезные скрипты
    "lint": "eslint .",
    "test:mercury": "echo 'Running Mercury tests...'" // Пример
  }
}

Удаляется директория .ai-contexts/.

4. 🎓 Cursor Mastery Bootcamp (Адаптировано)​

Этот план также включает обучение новым возможностям Cursor.

Problem 1: Rules в бардаке (Решается Path-based rules и генерацией)​

Что освоить:

  1. Иерархия Rules (Always vs Auto Attached by path vs Manual).
  2. Создание Auto Attached rules в .cursor/rules внутри каждого products/* домена.
  3. Генерация Rules из успешных диалогов.
  4. Дебаг активных Rules.

Problem 2: Неэффективное использование контекста (Решается @folders и Multi-root)​

Что освоить:

  1. Использование @folders path/to/product для дачи полного контекста домена.
  2. Настройка и использование Multi-root workspaces (workspaces/*.code-workspace).
  3. Оптимизация контекста: когда @folders всего продукта, когда более специфичные подпапки.
  4. Дебаг контекста (что AI видит).

Problem 3: Sequential workflow (Решается Background Agents)​

Что освоить:

  1. Делегирование задач Background Agent'ам.
  2. Мониторинг и управление Background Agents.
  3. Декомпозиция задач для агентов.

🚀 План миграции (поэтапный, с учетом Cursor 0.50.7)​

Фаза 0: Подготовка и Обучение (3 дня) - Cursor Mastery Bootcamp​

  1. День 1: Rules & @folders
    • Изучить документацию Cursor по Rules (Always, Auto Attached, Manual) и @folders.
    • Создать базовые .cursor/rules в корне проекта (глобальные, типа dangerous_defaults).
    • Практика с @folders на примере products/mercury.
  2. День 2: Multi-Root Workspaces
    • Создать workspaces/mercury.code-workspace как Multi-root workspace, включающий products/mercury/ и нужные shared/ папки.
    • Настроить settings и search.exclude в нем.
    • Попрактиковаться в работе внутри этого воркспейса.
  3. День 3: Background Agents & Rules Generation
    • Включить Background Agent (Beta).
    • Дать агенту простые задачи в контексте mercury.code-workspace + @folders products/mercury.
    • Попробовать /Generate Cursor Rules после успешного взаимодействия.

Фаза 1: Начальная Структуризация (2-3 дня)​

  1. Создать archive/ - переместить deprecated код (как и в оригинальном плане).
    • mercury-ta/ → archive/mercury-ta/ // ... (остальные элементы для архивации)
  2. Создать AI-manifest файлы для products/mercury и products/arcana.
  3. Создать базовые .cursor/rules в products/mercury/.cursor/rules (например, запрет mercury-ta).
  4. Настроить workspaces/mercury.code-workspace и workspaces/arcana.code-workspace как Multi-Root.

Фаза 2: Mercury Migration & Refinement (3-4 дня) - Фокус на одном домене​

  1. Создать products/mercury/ (если еще не сделано).
  2. Переместить apps/mercury → products/mercury/backend/.
  3. Переместить apps/mercury-dashboard → products/mercury/dashboard/.
  4. Обновить импорты и package.json в products/mercury.
  5. Тщательно протестировать сборку и функциональность Mercury.
  6. Активно использовать mercury.code-workspace:
    • Работать над Mercury ИСКЛЮЧИТЕЛЬНО через этот воркспейс.
    • Применять @folders products/mercury/backend (или другие нужные части) для задач AI.
    • Использовать Background Agent для рефакторинга, добавления тестов в Mercury.
    • Генерировать и уточнять правила в products/mercury/.cursor/rules.

Фаза 3: Shared Libraries Reorganization (2 дня)​

  1. Создать shared/ структуру (как в оригинальном плане).
  2. Переместить packages/ → shared/.
  3. Обновить импорты во всех продуктах, которые уже в products/.
  4. Валидировать dependency graph (можно использовать pnpm list или инструменты Nx, если он будет добавлен позже).
  5. Убедиться, что shared/ библиотеки корректно доступны из Multi-root воркспейсов.

Фаза 4: Остальные продукты (по необходимости)​

  1. Arcana migration: Повторить шаги Фазы 2 для products/arcana/ и workspaces/arcana.code-workspace. // ... (аналогично для AnyTracker, Maschine)

Фаза 5: Validation & Optimization (1-2 дня)​

  1. Тестирование AI workflow:
    • Попросить нового AI (или в новой сессии) выполнить задачу в mercury.code-workspace после применения @folders products/mercury. AI должен быстро понять контекст.
    • Проверить, что Background Agent корректно выполняет задачи.
    • Убедиться, что path-based rules применяются автоматически.
  2. Измерение времени восстановления контекста (должно сократиться до открытия воркспейса + одной @folders команды).
  3. Настройка CI/CD для новой структуры (если есть).
  4. Документирование новой методологии для команды (включая использование воркспейсов, @folders, правил).

📊 Ожидаемые результаты​

Метрики успеха​

  • Время восстановления контекста AI: с 10+ действий до открытия воркспейса + 1 команды @folders.
  • Качество кода: снижение багов за счет четкого контекста и автоматических правил.
  • Скорость разработки: увеличение за счет Background Agents и более точных советов AI.
  • Уверенность в коде: "работает с первого раза" становится чаще.

Преимущества​

  • Mercury (и другие продукты) получают чистый, изолированный контекст в своих воркспейсах.
  • Сохранены все плюсы монорепо.
  • AI-агент работает предсказуемо благодаря Multi-root, @folders и path-based rules. // ... (остальные преимущества из оригинального плана)

🔧 Технические детали​

pnpm-workspace.yaml​

packages:
  - 'products/*/backend'
  - 'products/*/dashboard'
  - 'products/*/mini-app'
  - 'shared/*/*'
  - 'platform/scripts/*'

.cursorignore (по умолчанию)​

archive/**
node_modules/**
dist/**
.next/**
*.log

AI Context файл (.ai-context.json) - УДАЛЯЕТСЯ / ЗАМЕНЯЕТСЯ​

Этот файл и директория .ai-contexts/ больше не нужны. Контекст управляется через:

  1. Multi-Root Workspaces (workspaces/*.code-workspace) - определяют доступные папки.
  2. @folders команда в чате - определяет активный файловый контекст для AI.
  3. Path-based .cursor/rules - определяют постоянные инструкции для AI при работе в определенных директориях.
  4. AI-Manifest.md - высокоуровневое описание домена.

🎯 Sacred Grail Achievement (Cursor 0.50.7 Version)​

С этой системой ты сможешь:

  1. Открыть workspaces/mercury.code-workspace.
  2. Сказать AI: @folders products/mercury (или более конкретно, например, @folders products/mercury/backend/src/dike) "Добавь новую фичу в DIKE модуль согласно products/mercury/ai-manifest.md".
  3. ИЛИ Поручить Background Agent'у: Background Agent: "@folders products/mercury/backend/src/dike - Implement feature X as described in DIKE section of products/mercury/ai-manifest.md, following all rules in products/mercury/.cursor/rules"
  4. AI выполнит:
    • Будет работать в контексте mercury.code-workspace.
    • Благодаря @folders получит полный и точный контекст указанных файлов.
    • Автоматически применит правила из products/mercury/.cursor/rules.
    • Прочитает products/mercury/ai-manifest.md для высокоуровневого понимания задачи и архитектуры.
    • Реализует фичу с пониманием мифологической архитектуры, правильным использованием kaido-talib и т.д.
  5. Результат: Код работает с первого раза, без багов от неправильного контекста, с соблюдением всех доменных правил.

Это твой Sacred Grail - высокоуровневый инструмент управления AI в режиме агента с минимальной болью и максимальной предсказуемостью, основанный на нативных возможностях Cursor 0.50.7.