- Added engineering rules references in AGENTS.md for code changes and specific areas (web, BIRD).
- Enhanced README.md to include links to engineering rules for different development areas.
- Updated birdfmt documentation to specify engineering rules for BIRD/BGP/IP.
- Clarified UI development guidelines in web/README.md to follow shadcn-svelte documentation and repository rules.

2026-05-20 00:14:14 +07:00

4.5 KiB

Raw Blame History

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

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

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

Инженерные правила — при изменении кода следовать .cursor/rules/engineering.mdc; для web/ — .cursor/rules/web-shadcn.mdc; для birdfmt / pipeline / BIRD — .cursor/rules/networking-bird.mdc.
docs/README.md — оглавление и роли читателя.
docs/architecture.md — компоненты cmd/, карта internal/, потоки данных (одного этого файла обычно достаточно для ориентации).
Задача-специфично: docs/api.md, docs/access.md, web/README.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/; не читайте план целиком без причины.

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

Консоль пользователя: PowerShell; пути в стиле deploy\compose.
Быстрый старт и переменные: docs/quickstart.md, README.md.

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

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

Svelte / фронтенд

При правках web/**/*.svelte или Svelte-модулей следуйте навыкам/инструментам проекта (официальный Svelte MCP и скиллы Cursor, если подключены).

4.5 KiB Raw Blame History Unescape Escape