Denozordec
7953ae6e78
Updated the ReUI documentation to reflect the addition of three new components, bringing the total to 20. Adjusted descriptions, examples, and rules across various files to ensure consistency with the updated component list. Enhanced the API references and installation instructions to improve clarity for users. This change includes updates to the SKILL.md, cli.md, components.md, registry.md, and workflow.md files, ensuring all references are accurate and up-to-date.
7.0 KiB
Руководство для ИИ-агентов (экономия контекста)
Краткие ориентиры по репозиторию EvoBGP, чтобы не тратить токены на полное сканирование дерева и повторное чтение одних и тех же файлов.
С чего начать (минимум чтения)
- Инженерные правила — при изменении кода следовать .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. - docs/README.md — оглавление и роли читателя.
- docs/architecture.md — компоненты
cmd/, картаinternal/, потоки данных (одного этого файла обычно достаточно для ориентации). - Задача-специфично: 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/*/ |
| Веб (SvelteKit) | 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 или это следует из плана — сразу:
- Shell:
powershell -NoProfile -File scripts/commit/staged-context.ps1(первый вызов, до текста коммита). - Скилл .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 стека.