EvoBGP/AGENTS.md

Руководство для ИИ-агентов (экономия контекста)

Краткие ориентиры по репозиторию EvoBGP, чтобы не тратить токены на полное сканирование дерева и повторное чтение одних и тех же файлов.

С чего начать (минимум чтения)

0. Инженерные правила — при изменении кода следовать .cursor/rules/engineering.mdc; для apps/web/ + packages/ui/ — .cursor/rules/web-shadcn.mdc; для birdfmt / pipeline / BIRD — .cursor/rules/networking-bird.mdc. Context7 (документация библиотек) — закреплённые ID стека: .cursor/rules/context7-stack.mdc; скилл .cursor/skills/context7-evobgp/SKILL.md.
1. docs/README.md — оглавление и роли читателя.
2. docs/architecture.md — компоненты cmd/, карта internal/, потоки данных (одного этого файла обычно достаточно для ориентации).
3. Задача-специфично: docs/api.md, docs/access.md — только если меняете API или доступ.

Источник правды по HTTP-контракту: docs/openapi.yaml. Не дублируйте длинные фрагменты спецификации в ответах — ссылайтесь на путь и тег/операцию.

Карта кода (куда смотреть)

Область	Где искать
REST, auth, CORS	internal/httpapi/
Бизнес-слой и абстракция хранилища	internal/store/
PostgreSQL	internal/repository/, internal/db/, migrations/
Фоновые задачи	internal/jobs/
Цепочка refresh модуля (ingest+render, BIRD preview)	internal/pipeline/
Конфиг BIRD, birdc	internal/birdfmt/, internal/birddeploy/
Бандлы и подписи	internal/bundle/, internal/signing/
Точки входа процессов	cmd/*/
Веб (React + ReUI)	apps/web/
Compose, деплой	deploy/compose/

Точки входа бинарников и их роли — в таблице в начале docs/architecture.md.

Как не раздувать контекст

• Сначала узкий поиск: grep/поиск по символу или короткий семантический запрос по одной папке (internal/httpapi/, internal/pipeline/, …), а не чтение всех .go подряд.
• Читайте файлы целиком только при необходимости: большие файлы — с offset/limit или по найденным строкам.
• Не подтягивайте в контекст: web/node_modules/, сгенерированные артефакты сборки, бинарники, полный openapi.html, если достаточно openapi.yaml.
• Повторное использование: если docs/architecture.md уже описывает поток — не пересказывайте его длинно; укажите документ и конкретный подпункт задачи.
• Длинные планы: .cursor/plans/*.plan.md — для истории решений; для навигации пользователю достаточно docs/; не читайте план целиком без причины.

Коммиты (Conventional Commits)

Если пользователь просит коммит, commit message, закоммить, git commit, /commit-message или это следует из плана — сразу:

1. Shell: powershell -NoProfile -File scripts/commit/staged-context.ps1 (первый вызов, до текста коммита).
2. Скилл .cursor/skills/commit-message/SKILL.md и правило .cursor/rules/conventional-commits.mdc.

Без вывода скрипта (exit 0) не придумывать сообщение коммита. Заголовок — EN, тело — RU; несвязанные области — auto-split (скилл).

Кнопка ✨ Generate commit message в Source Control skill/rule не использует. Для сообщений по правилам EvoBGP — Agent Chat → /commit-message (см. .cursor/commands/commit-message.md).

Команды и среда

• Консоль пользователя: PowerShell; пути в стиле deploy\compose.
• Быстрый старт и переменные: docs/quickstart.md, README.md.
• Go: после правок — gofmt -w, go vet ./..., scripts/lint-go.ps1 (как CI golangci-lint).

Язык документации проекта

Пользовательская документация в docs/ — преимущественно на русском. Комментарии и имена в коде — в существующем стиле репозитория.

Frontend (React + shadcn/ui + ReUI)

При правках apps/web/** или packages/ui/** следуйте .cursor/rules/web-shadcn.mdc (WEB-19): перед завершением задачи обязательно:

pnpm --filter @evobgp/web run typecheck
pnpm --filter @evobgp/web run lint
pnpm --filter @evobgp/web run build

Все три команды должны exit 0. CI job web не пропускает без этого.

Стек: React 19, TanStack Router/Query, shadcn/ui (base-nova, registry @shadcn + @reui), Tailwind v4, lucide-react. Legacy Svelte UI удалён (миграция завершена).

UI design contract: docs/ui-design-contract.md — surface frame, kit apps/web/src/components/reui-kit/.

Docs: Introduction · llms.txt · MCP · Agent Skills. Skill: .claude/skills/reui (668fb463eb).

UI-задачи начинаются с MCP user-reui (surface: "frame") + plugin-shadcn-shadcn, затем CLI pnpm dlx shadcn@latest add ... из apps/web. См. также .cursor/rules/context7-stack.mdc для Context7 ID стека.