moex-vibe/AGENTS.md

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

## Содержание

- [Обязательный подход к разработке](#обязательный-подход-к-разработке)
- [Процесс разработки](#процесс-разработки)
  - [Структура документации](#структура-документации)
  - [Назначение документов](#назначение-документов)
  - [Правила разработки](#правила-разработки)
    - [Определение бага](#определение-бага)
  - [Процесс работы над фичей](#процесс-работы-над-фичей)
  - [Работа с новыми идеями](#работа-с-новыми-идеями)
  - [Работа с существующими фичами](#работа-с-существующими-фичами)
  - [Поддержание документации](#поддержание-документации)
  - [Поведение AI-агентов](#поведение-ai-агентов)
    - [Anti-Loop: лимит на итерации](#anti-loop-лимит-на-итерации)
  - [Приоритет источников информации](#приоритет-источников-информации)
  - [Git workflow](#git-workflow)
    - [Конвенция коммитов](#конвенция-коммитов)
  - [Документация и SDD-артефакты](#документация-и-sdd-артефакты)
  - [Definition of Done (DoD)](#definition-of-done-dod)
- [Технические регламенты](#технические-регламенты)
  - [Правила тестирования](#правила-тестирования)
  - [Работа с миграциями Prisma](#работа-с-миграциями-prisma)
  - [Правила рефакторинга](#правила-рефакторинга)
  - [Политики безопасности](#политики-безопасности)
  - [ADR-процесс](#adr-процесс)
  - [Правила обновления OpenAPI/типов](#правила-обновления-openapiтипов)
    - [Цикл работы над API](#цикл-работы-над-api)
- [Инфраструктура проекта](#инфраструктура-проекта)
  - [Команды](#команды)
  - [Переменные окружения](#переменные-окружения)
- [Архитектура](#архитектура)
  - [Бэкенд](#бэкенд)
  - [Фронтенд](#фронтенд)
  - [Стиль кода](#стиль-кода)

---

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

- **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**: в ходе `brainstorming`, если предстоящие вопросы действительно требуют визуального представления (mockups, wireframes, диаграммы, сравнение вариантов), отдельным сообщением предложить пользователю [Visual Companion](https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md). Использовать его только после согласия пользователя и только для тех вопросов, которые понятнее показать, чем описать текстом. Visual Companion — инструмент, а не отдельный режим работы.

---

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

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

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

```text
docs/

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

```

Полный набор `spec.md`, `plan.md` и `tasks.md` обязателен для новых фич. Исторические feature-каталоги могут быть неполными: отсутствующие артефакты не требуется восстанавливать задним числом, если это не нужно для текущего изменения.

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

#### 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

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

#### Определение бага

Баг — это поведение системы, противоречащее спецификации, acceptance criteria, API-контракту, зафиксированному тестами поведению или подтверждённому архитектурному инварианту.

Если желаемое поведение нигде не зафиксировано и не следует из существующего контракта или инварианта — это отсутствующая функциональность (new feature), а не баг.

Классификация:

- **Есть зафиксированный контракт, поведение не соответствует** → баг (можно чинить напрямую, Правило 5)
- **Нет зафиксированного контракта, требуется новое поведение** → новая фича (нужна спецификация)
- **Spec есть, но в нём неопределённость** → сначала уточнить spec, потом решать, баг это или фича

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

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

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

Для исторической фичи сначала прочитать все имеющиеся артефакты. Отсутствие старого `plan.md` или `tasks.md` само по себе не блокирует maintenance или исправление бага и не требует создавать их задним числом. Для нового расширения такой фичи сначала подготовить недостающие артефакты в объёме текущего изменения.

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

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

Не реализовывать её автоматически. Необходимо определить, является ли она:

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

Если это улучшение или новая фича — добавить её в inbox.md или создать отдельную фичу.

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

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

Пример:

```
Portfolio Dashboard
├── История операций
├── Пагинация истории операций
├── Фильтрация истории операций
└── Экспорт истории операций
```

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

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

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

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

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

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

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

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

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

**Запрещено:**

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

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

### Anti-Loop: лимит на итерации

Если после 3 последовательных неудачных попыток исправить одну и ту же проблему в рамках одной гипотезы симптом не изменился — остановиться и запросить помощь у пользователя.

Правила:

- Каждая попытка = один цикл «сформулировал гипотезу → внёс изменение → проверил → тот же симптом сохранился»
- Сбор новой диагностической информации без изменения кода попыткой не считается
- Не начинать 4-ю попытку без явного указания пользователя
- При запросе помощи приложить: что пытался сделать, что пошло не так, последнее состояние кода/логов

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

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

1. Текущая задача пользователя (она может изменить требования, но соответствующие SDD-артефакты обновляются до реализации).
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-правки можно держать в той же ветке, если они относятся к текущей задаче.

### Конвенция коммитов

Использовать [Conventional Commits](https://www.conventionalcommits.org/):

- `feat:` — новая функциональность
- `fix:` — исправление бага
- `chore:` — обслуживание (зависимости, конфиги, CI)
- `docs:` — документация
- `refactor:` — рефакторинг без изменения поведения
- `test:` — добавление или исправление тестов
- `style:` — форматирование, кодстайл (prettier)
- `perf:` — улучшение производительности
- `build:` — изменения сборки и зависимостей
- `ci:` — изменения CI/CD

Формат: `<тип>(<необязательный scope>): <краткое описание в настоящем времени>`

Примеры:

- `feat: add portfolio rebalancing endpoint`
- `fix: handle empty dividend list from MOEX`
- `docs: update API authentication section`

### Документация и 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`.

### Definition of Done (DoD)

- Все acceptance criteria реализованы
- Тесты проходят
- Lint проходит
- Для новой фичи созданы и обновлены spec/plan/tasks; для исторической фичи обновлены существующие и необходимые для текущего изменения артефакты
- Документация обновлена
- Нет TODO без согласования

---

## Технические регламенты

### Правила тестирования

- Для новой бизнес-логики → обязательны unit-тесты
- Для API-контрактов → интеграционные тесты
- Не мокать собственный код без необходимости
- В unit-тестах мокать внешние API (MOEX, T-Bank) и Prisma
- При исправлении бага — сначала падающий тест (TDD)
- Тесты писать рядом с основным кодом

### Работа с миграциями Prisma

- Никогда не редактировать файлы в `prisma/migrations/` вручную
- После изменения `schema.prisma` → `npm exec -w apps/backend -- prisma migrate dev --name <name>`
- Изменять существующие миграции допустимо только до их публикации/мержа. После мержа создавать новую миграцию
- Всегда запускать `npm exec -w apps/backend -- prisma generate` после изменения схемы

### Правила рефакторинга

- Не выполнять крупный рефакторинг вне рамок задачи
- Допустимы: локальные улучшения, устранение техдолга рядом с изменяемым кодом, исправление архитектурных нарушений
- Запрещено: менять структуру проекта без ADR, переписывать модули без отдельной задачи
- Крупный рефакторинг требует отдельного эпика/фичи + ADR

### Политики безопасности

- Запрещено логировать токены, пароли, секреты
- Не отключать guard'ы
- Не хранить секреты в коде, не коммитить .env
- Использовать маскирование при выводе (например, `***`)

### ADR-процесс

- Создавать ADR при: выборе новой технологии, изменении архитектуры, изменении API-контрактов, изменении стратегии хранения данных
- ADR должен содержать: Контекст, Рассмотренные варианты, Решение, Последствия

### Правила обновления OpenAPI/типов

1. Обновить DTO/Controller на бэкенде
2. Обновить Swagger
3. Запустить `npm run codegen -w apps/frontend`
4. Использовать обновлённые типы из `src/api/types.ts`
5. Никогда не редактировать `types.ts` вручную

### Цикл работы над API

Стандартная процедура при любом изменении API-контракта:

1. **Бэкенд** — описать/обновить DTO и контроллер (NestJS)
2. **Swagger** — убедиться, что документация отдаётся корректно (`/api/docs-json`)
3. **Codegen** — `npm run codegen -w apps/frontend` (генерирует `src/api/types.ts`)
4. **Фронтенд** — использовать обновлённые типы, адаптировать вызовы
5. **Проверка** — убедиться, что `npm run build` проходит в обоих пакетах

Обновление типов вручную (`types.ts`) запрещено — всегда через codegen.

---

## Инфраструктура проекта

### Команды

Основные команды проекта описаны в README.md.

Перед завершением задачи запускать тесты, lint и build затронутых пакетов.

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

Основные настройки находятся в .env.

Полный список переменных описан в README.md.

---

## Архитектура

### Бэкенд

- **Бэкенд** — единственный клиент MOEX. Фронтенд никогда не обращается к MOEX напрямую.
- Актуальная композиция backend-модулей определяется в `apps/backend/src/app.module.ts`; не дублировать динамический список модулей в инструкциях. Опубликованное описание архитектуры находится в `apps/docs/docs/backend/modules.md`.
- `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.