Repository Refactoring Methodology & Plan

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

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

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

🏆 Выбранное решение: Nx-Enhanced Smart Monorepo с Domain Workspaces (Cursor 0.50.7 Edition)

Источники лучших идей:

• o3: Nx integration + "intel" bundling для AI контекста (модернизировано)
• deepthink r1: Domain-driven workspaces с Cursor оптимизацией (через Multi-root)
• Gemini 2.5-pro: Структура "domains/" (ранее "products/") с AI-manifest файлами
• Cursor 0.50.7 Changelog: Background Agents, @folders, Multi-root, Rules Generation как основа AI workflow

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

• ✅ Сохраняет все преимущества pnpm monorepo (shared modules, единая сборка).
• ✅ Nx graph + Улучшенный "Intel Script" для точного определения и загрузки AI контекста через @folders.
• ✅ Domain boundaries через Nx tags и Multi-root workspaces предотвращают coupling и контекстное загрязнение.
• ✅ Cursor-native AI workflow:
  • Multi-root Workspaces для изоляции доменов.
  • @folders для динамической и точной загрузки контекста.
  • Path-based .cursor/rules для автоматического применения доменных правил.
  • AI-Manifest.md для высокоуровневого описания домена.
  • Background Agents для автономного выполнения задач.
• ✅ Постепенное внедрение с фокусом на Mercury.
• ✅ Масштабируемость и четкая структура благодаря Nx.
• ✅ Обучающий компонент для освоения синергии Nx и Cursor 0.50.7.

📁 Финальная структура репозитория

ton-arcana/
├── domains/                      # Domain-driven organization
│   ├── mercury/                  # 🥇 Priority #1 - Trading system
│   │   ├── backend/              # apps/mercury → NestJS app
│   │   ├── dashboard/            # apps/mercury-dashboard → React
│   │   ├── packages/             # Mercury-specific packages
│   │   ├── ai-manifest.md        # AI context + instructions
│   │   └── project.json          # Nx configuration
│   ├── arcana/                   # 🔮 Tarot system
│   │   ├── backend/              # apps/arcana-backend
│   │   ├── twa/                  # apps/arcana-twa
│   │   ├── ai-manifest.md
│   │   └── project.json
│   ├── anytracker/               # 📊 Tracking system
│   │   ├── backend/              # apps/anytracker-backend
│   │   ├── mini-app/             # apps/anytracker-mini-app
│   │   └── ai-manifest.md
│   └── maschine/                 # 🤖 AI assistant features
│       ├── core/
│       └── ai-manifest.md
├── libs/                         # Shared libraries (packages/*)
│   ├── core/                     # Essential utilities
│   │   ├── common-utils/
│   │   ├── types/
│   │   ├── auth-utils/
│   │   └── project.json
│   ├── integrations/             # External service wrappers
│   │   ├── kaido-telegram/
│   │   ├── kaido-ton/
│   │   ├── kaido-ollama/
│   │   ├── openai-utils/
│   │   └── project.json
│   ├── domain/                   # Domain-specific libs
│   │   ├── kaido-talib/          # TS technical analysis
│   │   ├── curvinator/           # Legacy but used
│   │   └── project.json
│   └── deprecated/               # Marked for removal
│       └── mercury-ta/           # Python TA (deprecated)
├── platform/                    # Infrastructure & tooling
│   ├── tools/                    # Development utilities
│   │   ├── intel/                # AI context generator
│   │   ├── workspace-manager/    # Context switching
│   │   └── project.json
│   ├── infra/                    # Infrastructure as code
│   │   ├── ansible/
│   │   ├── docker/
│   │   ├── grafana/
│   │   └── project.json
│   └── docs/                     # Documentation
│       ├── adr/                  # Architecture decisions
│       ├── mercury/              # Domain-specific docs
│       ├── platform/             # General docs
│       └── project.json
├── archive/                      # Fully deprecated
│   ├── k8s/                      # Old Kubernetes configs
│   ├── mcp-task-warrior/         # MCP experiment
│   └── kaido.team/               # Empty public blog
├── tools/                        # Nx/dev tooling
│   ├── intel/                    # AI context bundler
│   │   ├── intel.ts              # Main intel generator
│   │   └── templates/            # Context templates
│   └── workspace-manager/        # Context switching
├── workspaces/                   # VS Code workspace configs
│   ├── mercury.code-workspace    # Mercury-focused development
│   ├── arcana.code-workspace     # Arcana-focused development
│   ├── anytracker.code-workspace # AnyTracker-focused development
│   └── platform.code-workspace  # Infrastructure work
├── nx.json                       # Nx workspace configuration
├── pnpm-workspace.yaml          # pnpm workspace definition
└── package.json                 # Root package.json

🤖 AI-First Context Recovery System (Nx + Cursor 0.50.7)

1. Улучшенный "Intel Script" (Вдохновлено o3, адаптировано для @folders)

Ключевая фича: pnpm run intel <domain> генерирует не просто JSON, а команды для Cursor или точный список путей для @folders.

// tools/intel/intel.ts
import {
  projectGraphAsync,
  ProjectGraph,
} from 'nx/src/project-graph/project-graph';
import { readFileSync, writeFileSync } from 'fs';
import { execSync } from 'child_process';

// Helper function to get all dependencies for a project
function getProjectDependencies(
  projectName: string,
  graph: ProjectGraph,
): string[] {
  const dependencies = new Set<string>();
  const stack = [projectName];

  while (stack.length > 0) {
    const current = stack.pop();
    if (!current || dependencies.has(current)) continue;

    dependencies.add(current);
    const projectNode = graph.nodes[current];
    if (projectNode) {
      // Add paths relative to workspace root for @folders
      dependencies.add(projectNode.data.root);
    }

    (graph.dependencies[current] || []).forEach((dep) => {
      if (!dependencies.has(dep.target)) {
        stack.push(dep.target);
      }
    });
  }
  // We want paths, not project names for @folders
  return Array.from(dependencies)
    .map((depName) => graph.nodes[depName]?.data.root)
    .filter(Boolean) as string[];
}

async function generateIntel(domain: string) {
  const graph = await projectGraphAsync();
  const domainProjectName = `domains-${domain}`; // Assuming Nx project name convention e.g., domains-mercury

  const domainNode = graph.nodes[domainProjectName];
  if (!domainNode) {
    console.error(
      `❌ Nx project for domain '${domain}' (expected: '${domainProjectName}') not found. Check your nx.json and project.json files.`,
    );
    return;
  }

  const domainRoot = domainNode.data.root; // e.g., domains/mercury
  const allRelevantPaths = new Set<string>([
    domainRoot,
    ...getProjectDependencies(domainProjectName, graph),
  ]);

  // Add other important general files if necessary
  allRelevantPaths.add('nx.json');
  allRelevantPaths.add('pnpm-workspace.yaml');
  allRelevantPaths.add(`${domainRoot}/ai-manifest.md`);

  const atFoldersCommand = Array.from(allRelevantPaths)
    .map((p) => `@folders ${p}`)
    .join(' ');

  const intelBundle = {
    domain,
    timestamp: new Date().toISOString(),
    nxProjectName: domainProjectName,
    domainRoot,
    // pathsForContext: Array.from(allRelevantPaths),
    suggestedAtFoldersCommand: atFoldersCommand,
    aiManifestContent: readFileSync(`${domainRoot}/ai-manifest.md`, 'utf-8'),
    // Potentially add recent commits or test status if truly useful for AI initial prompt
  };

  // Output the command for the user to copy into Cursor chat
  console.log(`🧠 Intel for ${domain} ready.`);
  console.log(
    `📋 Copy and paste the following into Cursor chat to set context for ${domain}:`,
  );
  console.log(
    `---------------------------------------------------------------------------`,
  );
  console.log(atFoldersCommand);
  console.log(
    `---------------------------------------------------------------------------`,
  );
  console.log(`ℹ️ Then, you can use Background Agent or chat directly.`);
  console.log(
    `Example: Background Agent: "${atFoldersCommand} - Refactor DIKE module..."`,
  );

  // Optionally, save the bundle for record-keeping, but primary output is the command
  writeFileSync(
    `/tmp/intel-${domain}.json`,
    JSON.stringify(intelBundle, null, 2),
  );
}

const domainArg = process.argv[2];
if (!domainArg) {
  console.error('Usage: node intel.ts <domain_name>');
  process.exit(1);
}
generateIntel(domainArg).catch(console.error);

Принцип работы: Скрипт использует nx graph для определения всех зависимостей домена, включая shared libs, и формирует одну или несколько команд @folders, которые пользователь копирует в Cursor. Это обеспечивает максимально точный и полный контекст.

2. AI-Manifest файлы (Enhanced - остаются ключевыми)

Формат ai-manifest.md (расположенного в domains/mercury/ai-manifest.md и т.д.) остается важным. Он предоставляет высокоуровневые цели, архитектурные заметки и специфические инструкции, которые дополняют формальные .cursor/rules.

# Mercury AI Manifest

<!-- Nx tags: domain:mercury, type:production, priority:high -->

## Domain: Trading System

**Status**: Production (highest priority)
**Revenue**: Active money-maker 💰

## Architecture

- **Backend**: NestJS + TypeScript
- **Dashboard**: React + TypeScript
- **Database**: PostgreSQL + MicroORM
- **Queue**: Redis + Bull.js
- **Infrastructure**: Docker + Ansible

## Mythological Modules (Greek/Roman Gods)

- **APOLLO**: Portfolio analysis & metrics
- **DIKE**: Tournament system for market comparison
- **TYCHE**: Market ranking & sweet spot identification
- **KAIROS**: Strategy execution timing
- **MINERVA**: Advanced technical analysis (TS)
- **MORPHEUS**: Shadow portfolio simulation

## Entry Points

- `backend/src/main.ts` - NestJS application
- `dashboard/src/main.tsx` - React dashboard
- `backend/src/cli/` - Command line tools

## AI Instructions (CRITICAL - дополняют .cursor/rules)

1.  **NEVER use mercury-ta** (Python) → Use `kaido-talib` (TypeScript) (_дублируется и форсируется в .cursor/rules_)
2.  **NO default ports** (dangerous_defaults rule) (_дублируется и форсируется в .cursor/rules_)
3.  **Focus on DIKE module** (current sprint priority - _это для Background Agent/разработчика_)
4.  **Mythological naming** - all modules named after gods (_дублируется и форсируется в .cursor/rules_)
5.  **Redis queues** for background processing
6.  **Tournament system** for market comparison logic

## Current Sprint Focus

- DIKE tournament system improvements
- TYCHE market ranking optimization
- Dashboard performance enhancements

## Dependencies (Nx Graph)

- `@libs/kaido-talib` (technical analysis)
- `@libs/types` (shared types)
- `@libs/common-utils` (utilities)
- `@libs/auth-utils` (authentication)

3. Nx Domain Boundaries и Multi-Root Workspaces

• Nx Tags & Constraints: Используются для формального определения границ между доменами и shared библиотеками в nx.json и project.json файлах. Это помогает предотвратить случайные междоменные зависимости на уровне кода.

  // nx.json (пример depConstraints)
  "enforceBuildableLibDependencyRules": true,
  "depConstraints": [
    {
      "sourceTag": "domain:mercury",
      "onlyDependOnLibsWithTags": ["scope:shared-core", "scope:shared-domain-mercury", "domain:mercury"]
    },
    {
      "sourceTag": "domain:arcana",
      "onlyDependOnLibsWithTags": ["scope:shared-core", "scope:shared-domain-arcana", "domain:arcana"]
    }
  ]

• Multi-Root VS Code Workspaces: Файлы workspaces/mercury.code-workspace, workspaces/arcana.code-workspace и т.д., определяют удобное рабочее окружение в IDE для конкретного домена. Они включают только релевантные папки (domains/имя_домена, нужные libs/*, platform/docs/имя_домена).

  // workspaces/mercury.code-workspace
  {
    "folders": [
      { "path": "../domains/mercury", "name": "Domain: Mercury" },
      { "path": "../libs/core", "name": "Libs: Core" }, // Пример общей библиотеки
      { "path": "../libs/domain/kaido-talib", "name": "Libs: Kaido TALib" } // Пример доменной библиотеки для Mercury
      // ... другие релевантные libs и platform/docs
    ],
    "settings": {
      // ... (search.exclude, cursor.ai.projectStructure.prioritize и т.д. как в плане 1)
      "cursor.ai.projectStructure.prioritize": ["domains/mercury"]
    }
  }

4. Path-based .cursor/rules

Внутри каждого домена (domains/mercury/.cursor/rules, domains/arcana/.cursor/rules) создаются специфичные для этого домена правила. Они автоматически применяются AI при работе с файлами в этих директориях.

# domains/mercury/.cursor/rules
When working in domains/mercury/:
- NEVER import from mercury-ta, ALWAYS use kaido-talib
- Use mythological naming for all new modules (APOLLO, DIKE, TYCHE, etc.)
- Enforce dangerous_defaults rule: NO hardcoded ports (6379, 5432, etc.) - use env vars from config files.
- Background jobs MUST use Redis queues via Bull.js setup in `domains/mercury/backend/src/redis`

5. Background Agents и Rules Generation

• Background Agents: Используются для выполнения задач в контексте, установленном через Multi-root Workspace и уточненном командами @folders (сгенерированными intel скриптом). Пример: Background Agent: "<вставить вывод pnpm run intel mercury сюда> - Implement new ranking algorithm in TYCHE module."
• Rules Generation: /Generate Cursor Rules используется для автоматического создания правил на основе успешных сессий, которые затем можно разместить в соответствующей директории .cursor/rules.

6. 🎓 Cursor Mastery Bootcamp (Nx + Cursor 0.50.7)

Обучение фокусируется на синергии Nx и новых функций Cursor.

Problem 1: Rules в бардаке и неэффективный контекст

Что освоить:

1. Создание иерархии Rules: Глобальные (корень .cursor/rules), доменные (domains/mercury/.cursor/rules).
2. Использование pnpm run intel <domain> для получения точных @folders команд.
3. Применение @folders для загрузки контекста в Cursor.
4. Настройка Multi-root workspaces (workspaces/*.code-workspace) для удобной работы в IDE.

Problem 2: Управление Background Agents с Nx-контекстом

Что освоить:

1. Формулирование задач для Background Agent, включая вывод intel скрипта (команды @folders).
2. Контроль за тем, чтобы агент не выходил за рамки домена, определенного Nx зависимостями.

🚀 Migration Plan (поэтапный, Nx + Cursor 0.50.7)

Фаза 0: Nx Setup & Cursor Bootcamp (3-4 дня)

1. День 1-2: Nx Initialization & Intel Script
   • Установить Nx: pnpm add -D nx и инициализировать: npx nx init (выбрать integrated или package-based в зависимости от предпочтений, package-based может быть проще для начала).
   • Настроить nx.json с базовыми проектами для domains/* и libs/*.
   • Реализовать первую версию tools/intel/intel.ts.
   • Протестировать pnpm run intel mercury (пока может быть неполным, но должен работать).
2. День 3-4: Cursor Mastery Bootcamp (адаптированный)
   • Освоить Multi-root workspaces, @folders, path-based rules, Background Agents.
   • Практика: открыть mercury.code-workspace, запустить pnpm run intel mercury, скопировать @folders в чат, дать Background Agent'у простую задачу по рефакторингу в domains/mercury.

Фаза 1: Mercury Domain - Создание и Nx Интеграция (3-4 дня)

1. Создать domains/mercury/.
2. Переместить apps/mercury → domains/mercury/backend/.
3. Переместить apps/mercury-dashboard → domains/mercury/dashboard/.
4. Создать project.json для domains/mercury/backend и domains/mercury/dashboard. Определить tags (e.g., "domain:mercury", "type:backend").
5. Настроить workspaces/mercury.code-workspace.
6. Написать domains/mercury/ai-manifest.md.
7. Создать domains/mercury/.cursor/rules с базовыми правилами.
8. Обновить и протестировать pnpm run intel mercury. Убедиться, что Nx graph корректно определяет зависимости для Mercury и скрипт генерирует правильные @folders команды.
9. Тестировать сборку и функциональность Mercury через Nx команды (e.g., nx build domains-mercury-backend).

Фаза 2: Shared Libraries - Nx Интеграция (2-3 дня)

1. Создать libs/ структуру.
2. Переместить packages/* в соответствующие поддиректории libs/ (e.g., packages/common-utils -> libs/core/common-utils).
3. Создать project.json для каждой библиотеки в libs/. Определить tags (e.g., "scope:shared-core", "scope:shared-domain-mercury").
4. Настроить nx.json с depConstraints для управления зависимостями между доменами и библиотеками.
5. Обновить импорты в domains/mercury для использования новых путей к libs.
6. Протестировать pnpm run intel mercury - он должен теперь включать корректные пути к зависимым libs в @folders.
7. Проверить nx graph для визуализации зависимостей.

Фаза 3: Archive & Cleanup (1 день)

1. Переместить в archive/: mercury-ta, k8s, mcp-task-warrior, и т.д.
2. Обновить .gitignore и workspace configs, чтобы исключить archive/.

Фаза 4: Остальные Домены (по необходимости, итеративно)

1. Для arcana (и других доменов): повторить шаги Фазы 1 и Фазы 2 (создание domains/arcana/, project.json, ai-manifest.md, .cursor/rules, arcana.code-workspace, обновление intel скрипта или его вызова для arcana).

Фаза 5: Advanced Optimization & Validation (2 дня)

1. CI/CD: Настроить nx affected:build, nx affected:test и т.д. в CI/CD.
2. Полное тестирование AI Workflow:
   • Запустить pnpm ctx:mercury (или эквивалент).
   • Передать вывод intel скрипта и задачу Background Agent'у.
   • Проверить качество кода, соблюдение правил и границ Nx.
3. Документировать новый workflow для команды.

📊 Ожидаемые результаты & Sacred Grail (Nx + Cursor 0.50.7)

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

• AI context restoration: pnpm ctx:<domain> (открывает workspace) + pnpm run intel <domain> (дает @folders команду) → AI готов к работе.
• Точность AI: Высокая, благодаря точному контексту из Nx graph и строгим правилам.
• Bug reduction: 70%+ снижение багов от неправильного контекста
• Development speed: 3x быстрее в agentic режиме
• Confidence: "работает с первого раза" вместо "половина сломается"

Sacred Grail Achievement 🏆

До: "AI, добавь фичу в Mercury... (10 минут ручного контекста, ошибки, багфиксы)"

После:

1. Ты выполняешь: pnpm ctx:mercury (открывается mercury.code-workspace).
2. Ты выполняешь: pnpm run intel mercury. Консоль выводит:

   📋 Copy and paste the following into Cursor chat to set context for mercury:
   ---------------------------------------------------------------------------
   @folders domains/mercury @folders libs/core/common-utils @folders libs/domain/kaido-talib ... (все зависимости Mercury)
   ---------------------------------------------------------------------------

3. Ты копируешь команду @folders ... в Cursor и добавляешь задачу: @folders domains/mercury @folders ... - Add new feature X to DIKE module, respecting ai-manifest.md and all .cursor/rules. ИЛИ Background Agent: "@folders domains/mercury @folders ... - Add new feature X to DIKE module..."
4. AI (или Background Agent) делает:
   • Работает в контексте mercury.code-workspace.
   • Имеет точный и полный набор файлов благодаря сгенерированным @folders (Nx-driven).
   • Автоматически применяет правила из domains/mercury/.cursor/rules.
   • Учитывает domains/mercury/ai-manifest.md.
   • Соблюдает Nx-границы зависимостей.
5. Результат: Код высокого качества, соответствующий архитектуре и правилам, с первого раза.

Это твой Sacred Grail: Nx управляет структурой и зависимостями, Intel Script транслирует это в идеальный контекст для Cursor 0.50.7, позволяя AI агентам работать эффективно и предсказуемо.

🔧 Technical Implementation Details

Nx Project Configuration

// domains/mercury/project.json
{
  "name": "mercury-backend",
  "projectType": "application",
  "root": "domains/mercury/backend",
  "sourceRoot": "domains/mercury/backend/src",
  "targets": {
    "build": {
      "executor": "@nx/node:build",
      "options": {
        "outputPath": "dist/domains/mercury/backend",
        "main": "domains/mercury/backend/src/main.ts",
        "tsConfig": "domains/mercury/backend/tsconfig.app.json"
      }
    },
    "serve": {
      "executor": "@nx/node:execute",
      "options": {
        "buildTarget": "mercury-backend:build"
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "domains/mercury/backend/jest.config.ts"
      }
    }
  },
  "tags": ["domain:mercury", "type:backend", "scope:production"]
}

pnpm-workspace.yaml

packages:
  - 'domains/*/*' // domains/mercury/backend, domains/mercury/dashboard etc.
  - 'libs/*/*'    // libs/core/common-utils, libs/domain/kaido-talib etc.
  - 'platform/*/*'
  - 'tools/*'

Intel Bundle Format (теперь скорее для логгирования, основной вывод - команда)

interface IntelBundle {
  domain: string;
  priority: 'high' | 'medium' | 'low';
  status: 'production' | 'stable' | 'experimental';
  aiManifest: string;
  dependencies: string[];
  recentCommits: string[];
  recentTests: TestSummary;
  keyFiles: string[];
  nxGraph: NxProjectGraph;
  contextInstructions: string[];
}

Этот подход объединяет лучшее от всех моделей и даст тебе Sacred Grail - мгновенный, надежный AI в режиме агента! 🎯