From 9d191763e12ab1e709feab4406fc8fa95929af62 Mon Sep 17 00:00:00 2001
From: Sergey Krylov <ksv741@mail.ru>
Date: Sat, 13 Jun 2026 19:36:05 +0300
Subject: [PATCH] docs: add AGENTS.md with dev instructions and SDD workflow

---
 AGENTS.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..deed358
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,67 @@
+# MoexVibe — Инструкция для агента
+
+## Репозиторий
+
+npm workspaces монорепозиторий: `apps/backend` (NestJS), `apps/frontend` (React + Vite).
+
+## Обязательный подход к разработке
+
+- **SDD (Specification-Driven Development)**: перед написанием кода сначала сформировать спецификацию — PRD, доменную модель, ADR, OpenAPI-контракт, архитектуру фронтенда и бэкенда, план реализации по этапам.
+- **Superpowers**: обязательно использовать скиллы (Skills) при старте любой задачи — brainstorming, frontend-design, test-driven-development, writing-plans, executing-plans, requesting-code-review.
+- **MCP-инструменты**: использовать MCP для анализа и генерации дизайна, работы с API, генерации кода.
+
+## Команды
+
+| Команда | Что делает |
+|---|---|
+| `npm run dev:backend` | Запуск NestJS в режиме watch на :3000 |
+| `npm run dev:frontend` | Vite dev-сервер на :5173, проксирует `/api` → :3000 |
+| `npm run build:backend` | `nest build` |
+| `npm run build:frontend` | `tsc -b && vite build` (в две фазы) |
+| `npm run test:backend` | `vitest run` (SWC, не ts-jest) |
+| `npm run lint` | ESLint только для бэкенда |
+| `npm run format` | Prettier для всех `*.{ts,tsx}` |
+| `npm run codegen -w apps/frontend` | `openapi-typescript` из локального Swagger → `src/api/types.ts` |
+
+Один тест: `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 |
+| `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 результатов поиска (с) |
+
+## Архитектура
+
+- **Бэкенд** — единственный клиент MOEX. Фронтенд никогда не обращается к MOEX напрямую.
+- Feature-модули: `MoexClientModule` (глобальный), `CacheModule` (глобальный), `SharesModule`, `BondsModule`, `SecuritiesModule`, `CandlesModule`, `HealthModule`.
+- `MoexClientService` использует p-queue (rate limiter) + circuit breaker (5 ошибок → 30s открыт).
+- In-memory кеш через `@nestjs/cache-manager`. Путь миграции на Redis описан (см. ADR-002).
+- Глобальный префикс 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).
+- Тесты фронтенда отсутствуют.
+- CI/CD в репозитории нет.