Sergey Krylov 2ed356fbcd docs: document MCP tools setup (code-index-mcp, serena, graphify)

- Add code-index-mcp and serena sections to AGENTS.md
- Update AGENTS.md MCP tools description in obligatory approach
- Add graphify hooks (post-checkout, post-commit) for auto graph rebuild
- Add serena project config
- Add graphify-out knowledge graph artifacts
- Ignore dev.db and graphify-out/cache/ in .gitignore

2026-06-24 13:32:10 +03:00

31 KiB

Raw Blame History

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

Содержание

Обязательный подход к разработке
Процесс разработки
Технические регламенты
Инфраструктура проекта
- Команды
- Переменные окружения
Архитектура

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

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 для крупных многошаговых работ, subagent-driven-development как предпочтительный способ исполнения плана, executing-plans как fallback для явно связанных inline-задач, frontend-design для UI, requesting-code-review перед завершением крупных изменений.
MCP-инструменты: в проекте настроены code-index-mcp (файловый поиск/индексация), serena (LSP-символьный анализ кода) и graphify (knowledge graph). Использовать для анализа, дизайна, работы с API, генерации кода и проверки локального UI, когда это полезно задаче.
Visual Companion: в ходе brainstorming, если предстоящие вопросы действительно требуют визуального представления (mockups, wireframes, диаграммы, сравнение вариантов), отдельным сообщением предложить пользователю Visual Companion. Использовать его только после согласия пользователя и только для тех вопросов, которые понятнее показать, чем описать текстом. 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

Полный набор 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, потом решать, баг это или фича

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

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

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

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

Если есть согласованный plan.md для многошаговой реализации, агент по умолчанию должен предпочитать superpowers:subagent-driven-development. superpowers:executing-plans использовать только когда пользователь явно просит inline-исполнение или когда задачи настолько тесно связаны, что разбиение по subagent-циклам ухудшит надёжность и скорость.

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

Запрещено:

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

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

Pre-flight checklist (обязателен перед реализацией любой фичи)

Агент не имеет права начать реализацию, пока не выполнены все пункты:

Feature branch создана: codex/<feature-name>
spec.md написана и утверждена пользователем
plan.md написан и утверждён пользователем
tasks.md создан с чекбоксами до начала работы
Все тесты проходят на текущем состоянии

Нарушение любого пункта = остановиться и вернуться к пропущенному шагу.

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

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

Правила:

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

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

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

Текущая задача пользователя (она может изменить требования, но соответствующие SDD-артефакты обновляются до реализации).
spec.md фичи.
plan.md фичи.
ADR.
Архитектурная документация.
roadmap.md.
inbox.md.

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

Git workflow

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

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

Использовать Conventional Commits:

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/типов

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

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

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

Бэкенд — описать/обновить DTO и контроллер (NestJS)
Swagger — убедиться, что документация отдаётся корректно (/api/docs-json)
Codegen — npm run codegen -w apps/frontend (генерирует src/api/types.ts)
Фронтенд — использовать обновлённые типы, адаптировать вызовы
Проверка — убедиться, что 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.

code-index-mcp

В проекте настроен code-index-mcp — MCP-сервер для быстрого поиска файлов и кода.

Инструменты:

find_files(pattern) — поиск файлов по glob-паттерну через in-memory индекс
search_code_advanced(pattern) — поиск кода с поддержкой regex, контекста, фильтрации по типу файла
get_file_summary(path) — сводка по файлу (строки, функции, классы, импорты)
get_symbol_body(path, symbol_name) — получить тело символа (функции/класса)
find_implementations(name_path, relative_path) — найти реализации символа
find_referencing_symbols(name_path, relative_path) — найти ссылки на символ

Когда использовать:

Поиск файлов по имени или паттерну (glob)
Быстрый grep по коду с контекстом
Получение только тела функции/класса без всего файла

serena

В проекте настроена serena — MCP-сервер с LSP-символьным анализом кода. Предоставляет symbol-aware инструменты поверх TypeScript LSP.