moex-vibe/AGENTS.md

MoexVibe — Инструкция для агента

Репозиторий

npm workspaces монорепозиторий: apps/backend (NestJS), apps/frontend (React + Vite), apps/docs (Docusaurus).

Обязательный подход к разработке

• SDD (Specification-Driven Development): перед значимыми изменениями сначала зафиксировать спецификацию нужного масштаба — PRD/цели, доменную модель, ADR, API-контракт, frontend/backend architecture и этапы реализации. Для небольших maintenance-правок достаточно короткого обоснования и acceptance criteria.
• Superpowers: использовать релевантные Skills при старте задачи. Обычно: brainstorming для уточнения дизайна, systematic-debugging для багов, test-driven-development для feature/bugfix, writing-plans/executing-plans для крупных многошаговых работ, frontend-design для UI, requesting-code-review перед завершением крупных изменений.
• MCP-инструменты: использовать MCP для анализа, дизайна, работы с API, генерации кода и проверки локального UI, когда это полезно задаче.
• Visual Companion: при обсуждении дизайна UI (mockups, макеты, варианты внешнего вида) использовать visual companion в браузере.

Процесс разработки

Проект использует подход Specification-Driven Development (SDD).

Структура документации

docs/

├── inbox.md
├── roadmap.md
│
├── research/
│
├── epics/
│   └── {epic-name}.md
│
└── features/
    └── {feature-name}/
        ├── spec.md
        ├── plan.md
        └── tasks.md
        

Назначение документов

inbox.md

Содержит идеи и мысли, которые появились во время работы над проектом.

Записи в inbox не являются требованиями и не должны реализовываться напрямую.

roadmap.md

Содержит список запланированных эпиков и фич.

Наличие задачи в roadmap не означает, что её нужно немедленно реализовать.

research/

Содержит результаты исследований и экспериментов.

Документы могут содержать гипотезы, предположения и открытые вопросы.

Результаты исследований необходимо проверять перед реализацией.

epics/

Эпик представляет собой крупную продуктовую возможность или модуль.

Эпик может состоять из нескольких фич.

features/{feature-name}/spec.md

Описывает ЧТО должно быть реализовано.

Спецификация должна содержать:

• цель
• требования
• ограничения
• критерии приемки (Acceptance Criteria)

Спецификация не должна содержать деталей реализации.

features/{feature-name}/plan.md

Описывает КАК будет реализована фича.

План может содержать:

• архитектурные решения
• API контракты
• потоки данных
• технический подход

features/{feature-name}/tasks.md

Содержит список задач для реализации.

Задачи должны быть:

• небольшими
• конкретными
• независимыми по возможности

Правила разработки

Правило 1

Нельзя начинать реализацию без спецификации.

Если спецификации нет:

• Провести исследование при необходимости.
• Создать spec.md.
• Уточнить требования.
• Только после этого переходить к реализации.

Правило 2

Реализация должна соответствовать spec.md.

Если в процессе разработки выясняется, что требования неполные или ошибочные:

Не изменять поведение системы молча.

Сначала обновить:

• spec.md
• plan.md

И только потом продолжать реализацию.

Правило 3

Спецификация является источником истины.

Если plan.md противоречит spec.md: Приоритет имеет spec.md.

Правило 4

Не добавлять функциональность, которая отсутствует в спецификации.

Если появилась новая идея:

• обновить спецификацию;
• либо создать новую фичу.

Правило 5

Исправления ошибок можно выполнять напрямую.

Новая функциональность должна проходить через спецификацию.

Процесс работы над фичей

При реализации фичи необходимо:

1. Ознакомиться с эпиком, если он существует.
2. Прочитать spec.md.
3. Прочитать plan.md.
4. Прочитать tasks.md.
5. Выполнять задачи последовательно.
6. Отмечать выполненные задачи.
7. Обновлять plan.md при изменении технических решений.
8. Обновлять spec.md при изменении требований.

Работа с новыми идеями

Если во время реализации появилась новая идея:

Не реализовывать её автоматически.

Необходимо определить, является ли она:

• багом;
• улучшением существующей функциональности;
• новой фичей.

Если это улучшение или новая фича:

Добавить её в:

• inbox.md

или создать отдельную фичу.

Работа с существующими фичами

Улучшения существующей функциональности обычно остаются внутри текущего эпика.

Пример:

Portfolio Dashboard

• История операций
• Пагинация истории операций
• Фильтрация истории операций
• Экспорт истории операций

Все перечисленные возможности относятся к одному эпику.

Новый эпик создаётся только при появлении новой продуктовой возможности или нового домена.

Поддержание документации

Документация должна соответствовать текущему состоянию проекта.

После значимых изменений необходимо обновлять:

• spec.md
• plan.md
• tasks.md
• ADR
• архитектурную документацию

Документация не должна отставать от реализации.

Поведение AI-агентов

Перед написанием кода необходимо:

1. Изучить спецификацию фичи.
2. Проверить полноту требований.
3. Найти неоднозначности и противоречия.
4. При необходимости запросить уточнения.

Запрещено:

• придумывать требования;
• додумывать поведение системы;
• реализовывать неописанную функциональность.

Если информации недостаточно:

• Остановиться и запросить уточнение вместо того, чтобы делать предположения.

Приоритет источников информации

При возникновении противоречий использовать следующий порядок приоритетов:

1. Текущая задача пользователя.
2. spec.md фичи.
3. plan.md фичи.
4. ADR.
5. Архитектурная документация.
6. roadmap.md.
7. inbox.md.

roadmap.md и inbox.md никогда не являются основанием для реализации функциональности.

Git workflow

• Для каждой самостоятельной фичи создавать отдельную feature branch и вести разработку внутри неё.
• Имя ветки по умолчанию начинать с codex/, если пользователь не попросил другой префикс.
• Не смешивать независимые фичи в одной ветке. Небольшие связанные docs/chore/test-правки можно держать в той же ветке, если они относятся к текущей задаче.

Документация и SDD-артефакты

• apps/docs — единственная опубликованная человекочитаемая документация проекта (Docusaurus).
• ADR для опубликованной документации находятся в apps/docs/docs/adr/.
• OpenAPI source of truth — live Swagger JSON бэкенда на /api/docs-json; frontend generated types находятся в apps/frontend/src/api/types.ts.

Команды

Команда	Что делает
npm run dev:backend	Запуск NestJS в режиме watch на :3000
npm run dev:frontend	Vite dev-сервер на :5173, проксирует /api → :3000
npm run dev:docs	Docusaurus dev-сервер
npm run build:backend	nest build
npm run build:frontend	tsc -b && vite build (в две фазы)
npm run build:docs	docusaurus build
npm run test:backend	vitest run (SWC, не ts-jest)
npm run test:frontend	Frontend Vitest suite
npm run lint	ESLint для backend и frontend
npm run format	Prettier для всех *.{ts,tsx}
npm run codegen -w apps/frontend	openapi-typescript из локального Swagger → src/api/types.ts

Live MOEX integration tests opt-in: npm run test:integration -w apps/backend.

Один тест: npx vitest run path/to/test.spec.ts -w apps/backend

Переменные окружения

Переменная	По умолчанию	Описание
PORT	3000	Порт бэкенда
MOEX_BASE_URL	https://iss.moex.com/iss	Endpoint MOEX ISS
MOEX_RATE_LIMIT	10	Запросов/с к MOEX
MOEX_CIRCUIT_BREAKER_THRESHOLD	5	Количество ошибок до открытия circuit breaker
MOEX_CIRCUIT_BREAKER_RESET_SECONDS	30	Время до попытки закрыть circuit breaker
T_BANK_TOKEN	''	Server-side токен T-Bank Invest
T_BANK_BASE_URL	invest-public-api.tbank.ru:443	gRPC endpoint T-Bank Invest
T_BANK_CA_CERT_PATH	''	Путь к PEM root CA для gRPC TLS, если локальная сеть подменяет сертификаты
T_BANK_APP_NAME	ksv741.moex-vibe	Metadata приложения для T-Bank
T_BANK_RATE_LIMIT_PER_SECOND	5	Rate limiter для OperationsService и UsersService (запросов/с)
T_BANK_INSTRUMENTS_RATE_LIMIT	20	Rate limiter для InstrumentsService (запросов/с)
T_BANK_REQUEST_TIMEOUT_MS	10000	Deadline gRPC-запроса (мс)
CACHE_MARKET_DATA_TTL	900	TTL рыночных данных (с)
CACHE_HISTORY_TTL	3600	TTL истории (с)
CACHE_CANDLES_TTL	3600	TTL свечей (с)
CACHE_SECURITY_TTL	86400	TTL спецификации (с)
CACHE_SEARCH_TTL	3600	TTL результатов поиска (с)
CACHE_DIVIDENDS_TTL	86400	TTL дивидендных данных (с)
DATABASE_URL	file:./dev.db	URL SQLite для Prisma
JWT_SECRET	dev-jwt-secret-...	Secret для access token
JWT_REFRESH_SECRET	dev-refresh-secret-...	Secret для refresh token
JWT_ACCESS_EXPIRES	15m	TTL access token
JWT_REFRESH_EXPIRES	7d	TTL refresh token

Архитектура

• Бэкенд — единственный клиент MOEX. Фронтенд никогда не обращается к MOEX напрямую.
• Feature-модули: PrismaModule (глобальный), MoexClientModule (глобальный), CacheModule (глобальный), AuthModule, SharesModule, BondsModule, SecuritiesModule, CandlesModule, PortfolioModule, HealthModule.
• MoexClientService использует p-queue (rate limiter) + circuit breaker (5 ошибок → 30s открыт).
• In-memory кеш через @nestjs/cache-manager. Путь миграции на Redis описан (см. ADR-002).
• Аутентификация: JWT access token (15m, в памяти) + refresh token (7d, httpOnly cookie, bcrypt hash в БД). Глобальный JwtAuthGuard (@Public() для открытых эндпоинтов).
• БД: SQLite через Prisma ORM. Prisma client используется из @prisma/client; схема и миграции находятся в apps/backend/prisma/.
• Глобальный префикс NestJS: /api/v1. Swagger: /api/docs.
• Глобальный ValidationPipe (transform: true, whitelist: true), HttpExceptionFilter, TransformInterceptor, middleware логирования запросов.
• Ответы API обёрнуты в { data: T, meta: { fromCache, cachedAt } }.
• Алиасы: @/* → src/* в обоих пакетах.

Фронтенд

• React 18 + react-router-dom v6 + TanStack Query v5.
• lightweight-charts v4 для графиков цен.
• openapi-fetch + рукописные типы responses.ts (не полностью codegen'овые).
• TanStack Query по умолчанию: staleTime: 900s, retry: 2, refetchOnWindowFocus: false.
• Конвенция ключей запросов: ['stock', secid], ['securities', 'search', query], и т.д.
• CSS через styles.css (CSS custom properties, без CSS-in-JS или Tailwind).

Стиль кода

• Prettier: одинарные кавычки, trailing commas, printWidth 100, точки с запятой.
• Бэкенд: const, PascalCase для модулей/контроллеров/сервисов, DTO в dto/ внутри каждого модуля.
• Бэкенд использует SWC через unplugin-swc (vitest config).
• Тесты фронтенда есть: Vitest + Testing Library + MSW.
• CI находится в .gitea/workflows/ci.yml.
• Pre-commit checks настроены через Husky и lint-staged.