onboard

Onboard — интерактивный онбординг в проект

Интерактивный процесс изучения проекта. Сканирует структуру, обнаруживает системы, создаёт индексный файл знаний для всех скиллов плагина vmkteam-developer.

Процесс

Шаг 1. Сканирование проекта

Изучи локальную структуру:

• go.mod — модуль, зависимости, Go-версия, vmkteam-зависимости
• Makefile / Makefile.mk — доступные команды, генераторы
• docs/model/*.mfd — MFD-схема, namespace'ы, таблицы
• docs/*.pgd / docs/*.pdd — схема БД (определяет: /pgd или /pgmdd)
• pkg/ — структура пакетов (db, rpc, vt, domain)
• cmd/ — точки входа, бинарники
• .gitlab-ci.yml — CI/CD pipeline
• deployments/ — Nomad/Docker конфиги
• cfg/ — конфигурация (TOML)
• migrations/ — SQL миграции
• CLAUDE.md / .claude/ — существующие инструкции

Автоопределение vmkteam-инструментов из go.mod:

• vmkteam/zenrpc → скилл /zenrpc
• vmkteam/mfd-generator (или Makefile mfd-*) → скилл /mfd
• vmkteam/colgen (или //go:generate colgen) → скилл /colgen
• vmkteam/rpcgen (или Makefile *-client) → скилл /rpcgen
• vmkteam/appkit → скилл /appkit
• vmkteam/cron → скилл /cron
• vmkteam/zenrpc-middleware → скилл /zenrpc
• .pgd файлы → скилл /pgd
• .pdd файлы → скилл /pgmdd

Определи тип сервиса: API, worker, cron, hybrid.

Шаг 2. Определить стадию и infra-группу

Спроси у пользователя:

1. На какой стадии проект?

Стадия	Описание	Доступные системы
Идея	Только код, нет деплоя	YouTrack, Git
Dev	Задеплоен на dev/staging	+ Sentry (dev), API dev, возможно Grafana
Production	Задеплоен на prod	+ Sentry (prod), API prod, Grafana, Prometheus, Loki, Nomad, topsrv

Стадия определяет какие системы спрашивать — не задавай вопросы про Grafana/Prometheus если проект на стадии "Идея".

2. К какой infra-группе относится проект? (например: acme, platform, storefront)

Проверить наличие shared infra-файла: ~/.claude/memory/infra-{group}.md

• Если существует — показать содержимое, спросить актуально ли. Перейти к шагу 3b (только специфика сервиса).
• Если не существует — перейти к шагу 3a (полный опрос), создать infra-файл.

Шаг 3a. Полный опрос (новая infra-группа)

Спрашивай только системы, релевантные стадии.

Infra-level (общие для всех сервисов группы):

1. GitLab: Какой GitLab-инстанс? pcurl-профиль? Username?
2. YouTrack: Какой YouTrack-инстанс? pcurl-профиль?
3. Sentry (Dev+): pcurl-профиль, org? Sentry общий для dev и prod или раздельный?
4. Grafana (Production): pcurl-профиль?
5. Prometheus (Dev+): pcurl-профиль (dev)? pcurl-профиль (prod, если отличается)?
6. Loki (Production): через Grafana? loki datasource UID?
7. Kibana (Production): pcurl-профиль? Тип (opensearch/kibana)?
8. Nomad (Production): pcurl-профиль?
9. topsrv (Production): проект в app.topsrv.io и pcurl-профиль (@topsrv-{slug}, второй токен — @topsrv-{slug}-2; искать в pcurl show)?
10. Ветвление: общая модель (devel→staging, master→production)?

Service-level (специфика этого сервиса):

11. YouTrack проект: shortName, project_id, state_field и значения?

12. GitLab project: Project ID, path?

13. Sentry project: slug?

14. Prometheus job: имя job для этого сервиса?

15. Loki service_name: имя в Loki?

16. Grafana dashboard: UID дашборда?

17. API endpoints: URL dev/prod, pcurl-профили, rpc_endpoint?

18. Nomad job: имя job?

19. Специфика: особые правила, code style?

20. Базовая ветка (base_branch): от какой ветки ответвляются feature-ветки и куда идут MR? (по умолчанию devel; иногда master, main)

21. Артефакты /solve (artifacts_target): куда публиковать артефакты как коммент со спойлерами? Варианты:

    • gitlab — коммент в MR (по умолчанию)
    • youtrack — коммент в задаче
    • ask — спрашивать каждый раз

    docs/llm/tasks/ не коммитится — остаётся локально, поэтому .gitignore должен содержать docs/llm/tasks/. Весь docs/llm/ не игнорируй: в некоторых проектах там закоммиченная документация.

Шаг 3b. Краткий опрос (infra-группа уже есть)

Спрашивать только service-level (пп. 11-21 из шага 3a). Infra-level берётся из ~/.claude/memory/infra-{group}.md.

Шаг 4. Проверка подключений

Если infra-файл уже существует — проверять только service-specific endpoints (API dev/prod, Sentry project, Prometheus job). Infra-level проверки (GitLab, YouTrack, Grafana) уже пройдены.

Для новой infra-группы — проверить все, параллельно:

# YouTrack — проекты и кастомные поля (state может называться иначе: Stage, Status и т.д.)
pcurl @{yt_profile} 'https://{yt_host}/api/admin/projects?fields=id,shortName,name&$top=50' -s -o /dev/null -w '%{http_code}'

# GitLab — проект и доступ
pcurl @{gl_profile} 'https://{gl_host}/api/v4/projects/{gl_project_id}?simple=true' -s -o /dev/null -w '%{http_code}'

# Sentry
pcurl @{sentry_profile} 'https://{sentry_host}/api/0/organizations/{org}/projects/' -s -o /dev/null -w '%{http_code}'

# Grafana
pcurl @{grafana_profile} 'https://{grafana_host}/api/health' -s -o /dev/null -w '%{http_code}'

# Prometheus
pcurl @{prom_profile} 'https://{prom_host}/api/v1/query?query=up' -s -o /dev/null -w '%{http_code}'

# Loki (через Grafana)
pcurl @{grafana_profile} 'https://{grafana_host}/api/datasources/uid/{loki_uid}/resources/labels' -s -o /dev/null -w '%{http_code}'

# topsrv — 200 и в теле project, scopes, expiresAt; 401 — токен истёк или отозван
pcurl @{topsrv_profile} -sS https://app.topsrv.io/api/v1/rpc/ -d '{"jsonrpc":"2.0","id":1,"method":"meta.whoami"}' -w ' %{http_code}'

# API prod (/status скрыт за firewall — проверяем RPC endpoint)
pcurl @{api_prod_profile} 'https://{api_prod_host}/{rpc_endpoint}?smd' -s -o /dev/null -w '%{http_code}'

# API dev
pcurl @{api_dev_profile} 'https://{api_dev_host}/{rpc_endpoint}?smd' -s -o /dev/null -w '%{http_code}'

Шаг 5. Discovery (если проверки прошли)

Параллельно собрать:

# Sentry: проекты (полная карта сервисов организации)
pcurl @{sentry_profile} 'https://{sentry_host}/api/0/organizations/{org}/projects/' -s

# Grafana: дашборды и datasources
pcurl @{grafana_profile} 'https://{grafana_host}/api/search?type=dash-db&query={service}' -s
pcurl @{grafana_profile} 'https://{grafana_host}/api/datasources' -s

# Prometheus: jobs и межсервисная топология
pcurl @{prom_profile} 'https://{prom_host}/api/v1/label/job/values' -s
pcurl @{prom_profile} 'https://{prom_host}/api/v1/query' -s -G --data-urlencode 'query=app_metadata_services'
pcurl @{prom_profile} 'https://{prom_host}/api/v1/query' -s -G --data-urlencode 'query=app_metadata_db_connections_total'

# Loki: сервисы (UID-based путь — /resources/ без /loki/api/v1/)
pcurl @{grafana_profile} 'https://{grafana_host}/api/datasources/uid/{loki_uid}/resources/label/service_name/values' -s

# YouTrack: кастомные поля и значения state (может быть Stage, Status etc.)
pcurl @{yt_profile} 'https://{yt_host}/api/issues?query=project:{PROJECT}&fields=idReadable,customFields(name,value(name))&$top=5' -s

# API: SMD (список RPC namespace'ов и методов) — через ?smd
pcurl @{api_prod_profile} 'https://{api_prod_host}/{rpc_endpoint}?smd' -s -L

Шаг 5b. Multi-repo и Architecture discovery

Определить связанные сервисы из нескольких источников:

# Из pkg/client/ — rpcgen-клиенты
ls pkg/client/ 2>/dev/null

# Из конфигов — URL других сервисов
grep -r 'http://' cfg/local.toml.dist 2>/dev/null

Из Prometheus (Dev и выше) — построить топологию через метрики appkit:

# Какие сервисы существуют
pcurl @{prom_profile} 'https://{prom_host}/api/v1/query' -s -G --data-urlencode 'query=app_metadata_service'

# Межсервисные связи (sync/async/external)
pcurl @{prom_profile} 'https://{prom_host}/api/v1/query' -s -G --data-urlencode 'query=app_metadata_services'

# Подключения к БД
pcurl @{prom_profile} 'https://{prom_host}/api/v1/query' -s -G --data-urlencode 'query=app_metadata_db_connections_total'

Из этих метрик собрать полную карту: какой сервис с кем общается (sync/async), какие БД использует.

Для каждого связанного сервиса проверить наличие локальных исходников.

Шаг 6. Генерация файлов

Онбординг создаёт два файла в РАЗНЫХ директориях:

Файл	Абсолютный путь	Scope	Инструмент
Shared infra	~/.claude/memory/infra-{group}.md	Глобальный (все проекты группы)	Write (абсолютный путь, mkdir -p если нет)
Project index	{project-auto-memory-dir}/project-index.md	Только этот проект	Write (в auto-memory директорию проекта)

Это разные директории, и их легко перепутать:

• ~/.claude/memory/ — глобальная директория, общая для всех проектов группы; infra-файл должен быть доступен из любого из них. Если директории нет — mkdir -p ~/.claude/memory/.
• {project-auto-memory-dir} — auto-memory директория текущего проекта (например ~/.claude/projects/-Users-username-Projects-Go-foo/memory/). Пиши через Write с абсолютным путём.
• Скиллы читают оба файла: infra-level значения — из infra-{group}.md, service-level — из project-index.md, и подставляют их вместо {placeholders}.

6a. Shared infra: ~/.claude/memory/infra-{group}.md

Создаётся один раз для infra-группы. При повторном онбординге — обновляется только если что-то изменилось. Путь всегда абсолютный: ~/.claude/memory/infra-{group}.md.

# infra-{group} — shared infrastructure

## GitLab
- profile: @{gl_profile}
- host: {gl_host}
- username: {gl_username}

## YouTrack
- profile: @{yt_profile}
- host: {yt_host}

## Sentry
- profile: @{sentry_profile}
- host: {sentry_host}
- org: {org}

## Grafana
- profile: @{grafana_profile}
- host: {grafana_host}
- prometheus_datasource_uid: {uid}
- loki_datasource_uid: {uid}

## Prometheus
- profile_dev: @{prom_dev_profile}
- host_dev: {prom_dev_host}
- profile_prod: @{prom_prod_profile}
- host_prod: {prom_prod_host}

## Loki
- via grafana proxy (UID-based: /resources/query_range, НЕ /loki/api/v1/)
- loki_uid: {uid}

## Kibana / OpenSearch Dashboards (если есть)
- profile: @{kibana_profile}
- host: {kibana_host}
- type: {opensearch / kibana}

## Nomad (если есть)
- profile: @{nomad_profile}
- host: {nomad_host}

## topsrv (если есть)
- profile: @{topsrv_profile}
- project: {topsrv_slug}
- scopes: {scopes из meta.whoami}

## Ветвление
- devel → staging (auto deploy)
- master → production (auto deploy)

6b. Project index: {project-auto-memory-dir}/project-index.md

Путь: auto-memory директория текущего проекта (абсолютный). Строка infra: в начале файла указывает на shared infra-файл.

Добавь в MEMORY.md той же директории строку-указатель, если её нет, — так Claude видит индекс в каждой сессии проекта и находит его для скиллов:

- [Project index](project-index.md) — подключения к системам и специфика сервиса для скиллов vmkteam-developer

# {Project} — индекс знаний

infra: ~/.claude/memory/infra-{group}.md

## Общая информация
- Модуль: {module}
- Go: {version}
- Тип: {API/worker/hybrid}
- Стадия: {Идея/Dev/Production}
- Деплой: {Nomad/Docker/K8s / нет}

## Структура
- DB: pkg/db/ ({N} сущностей, {namespaces})
- Domain: pkg/{name}/ (есть/нет)
- RPC: pkg/rpc/ ({N} сервисов, namespace: {ns}, endpoint: /rpc/)
- VT: pkg/vt/ ({N} сервисов, endpoint: /vt/)
- Migrations: docs/patches/ ({N} файлов)

## Инструменты vmkteam
- zenrpc {version}
- mfd-generator {version} (MFD: docs/model/{name}.mfd)
- colgen (//go:generate colgen в pkg/rpc/, pkg/vt/)
- rpcgen {version}
- appkit {version}
- cron (есть/нет)

## Релевантные скиллы
- /gold-arch — архитектура (трёхслойная)
- /zenrpc — RPC-методы, middleware, аннотации
- /mfd — генерация из БД (namespaces: {list})
- /colgen — коллекции и конвертеры
- /pgd или /pgmdd — схема БД ({file})
- /rpcgen — генерация клиентов
- /appkit — метрики, pprof, embedlog
- /pgmigrator — SQL миграции
- /testing — тесты (pkg/db/test/)
- /commit-msg — коммиты
- /go-review — code review (свой код)
- /mr-review — ревью чужих MR
- /gitlab — MR, pipelines, discussions
- /incident — реакция на production инциденты

## Service systems

### GitLab project
- project_id: {gl_project_id}
- project_path: {group/project}
- url: https://{gl_host}/{group/project}/-/merge_requests

### YouTrack project
- project: {SHORT}
- project_id: {id}
- state_field: {State/Stage/Status}
- state_open: {Open/Backlog/...}
- state_done: {Done/Closed/...}
- url: https://{yt_host}/issues?q=project:{SHORT}

### Sentry project
- project_slug: {slug}
- url: https://{sentry_host}/organizations/{org}/issues/?project={project_id}

### Prometheus
- job: {service_job_name}

### Loki
- service_name: {service_name_in_loki}

### Grafana dashboard
- dashboard_uid: {uid}
- dashboard_url: https://{grafana_host}/d/{uid}

### Kibana (если есть)
- index_patterns: {nginx-access-*, nginx-error-*, ...}

### Nomad (если есть)
- job: {nomad_job_name}

### API Production
- profile: @{api_prod_profile}
- host: {api_prod_host}
- rpc_endpoint: /rpc/
- vt_endpoint: /vt/

### API Dev/Staging
- profile: @{api_dev_profile}
- host: {api_dev_host}
- rpc_endpoint: /rpc/

## Solve settings
- base_branch: {devel} — базовая ветка, от которой ответвляются feature-ветки и против которой делается MR/review
- artifacts_target: {gitlab/youtrack/ask} — куда публиковать артефакты /solve как коммент со спойлерами
- Артефакты `docs/llm/tasks/` не коммитятся (`docs/llm/tasks/` в `.gitignore`)

## Makefile-команды
{список ключевых make targets с кратким описанием}

## Связанные сервисы
| Сервис | Тип связи | Локальный путь | Sentry slug | Prometheus job |
|--------|-----------|----------------|-------------|----------------|
| {service} | {sync/async/db} | {path} | {slug} | {job} |

## Локальные пути
- Исходники: {path}
- Связанные проекты: {list}

## Уроки
{пусто при онбординге; /solve дописывает сюда по строке после задач с провальными раундами: «что пошло не так → как избежать (TASK_ID)»}

Шаг 7. Валидация

Покажи пользователю сгенерированный индекс и попроси подтвердить/уточнить.

Результат

После онбординга:

• ~/.claude/memory/infra-{group}.md содержит общие подключения (GitLab, YouTrack, Sentry, Grafana, Prometheus, Loki, Kibana, Nomad, topsrv)
• {project-auto-memory-dir}/project-index.md содержит специфику сервиса и ссылку на infra-файл, а MEMORY.md — указатель на него
• Скиллы читают оба файла: infra-level из infra-{group}.md, service-level из project-index.md
• Повторный онбординг сервиса той же группы — только service-level вопросы