Перейти к содержанию

TOOLING — агенты, скиллы, MCP

Справочник для Claude Code по инструментам, настроенным в этом проекте. Контекст решения — docs/DECISIONS.md (ADR-0011, ADR-0012).

Структура — группа GitLab mybit, отдельный репозиторий на сервис (не монорепо, см. ADR-0012). Локально сервисы — соседние директории под этой же рабочей папкой (mybit/platform), каждая со своим .git.

Субагенты (.claude/agents/)

Каждый скоупнут на свою директорию/репозиторий, читает свой CLAUDE.md + релевантный раздел docs/SERVICES.md перед началом работы. Независимые сервисы можно запускать параллельно через Agent tool. Коммитить/пушить агент должен внутри своей директории — это отдельный git-репозиторий со своим remote, а не часть platform.

Агент Скоуп (репозиторий mybit/…)
core-service-go core-service/, proto/
telegram-bot-py telegram-bot/
miniapp-frontend miniapp-frontend/ (+ Playwright MCP для E2E)
sync-workers-go wger-sync-worker/, google-health-sync/, applehealth-import/
inbody-parser-py inbody-parser/
wger-fork wger/
infra-devops platform/docker-compose.yml, .gitlab-ci.yml каждого репо, GitLab MCP

Scoping — на уровне system prompt, не sandbox: агент физически может выйти за пределы своей директории через Bash, но проинструктирован этого не делать.

Скиллы (.claude/skills/, проектные)

  • task-to-issue — анализ задачи → определение сервиса(ов) → создание/обновление issue в GitLab через MCP.
  • deploy — триггер и мониторинг GitLab CI pipeline через MCP. Пайплайнов пока нет ни у одного сервиса — появятся по мере кода.

Глобальный (~/.claude/skills/):

  • council (tsenart/council-skill) — многоперспективный разбор сложных решений/тредеофов, автоматически триггерится по описанию задачи.

MCP-серверы

  • gitlab (@zereight/mcp-gitlab, local scope) — issues/MR/pipelines/ milestones/wiki для группы mybit (10 репозиториев) на http://gitlab.local.
  • playwright (.mcp.json, project scope) — headless Playwright для будущих E2E-тестов miniapp-frontend.
  • playwright-extension (local scope) — водит реальный Chrome пользователя через Playwright MCP Bridge extension, для ad hoc браузерных задач вне автотестов.
  • Context7 — уже подключён на уровне claude.ai-коннектора (mcp__claude_ai_Context7__*). Использовать для актуальной документации внешних библиотек (Django/DRF, gRPC-go, python-telegram-bot/aiogram и т.д.) вместо памяти модели.

LSP

Официальные плагины Anthropic (anthropics/claude-plugins-official): gopls-lsp, pyright-lsp, typescript-lsp. Бинарники: gopls (~/go/bin), pyright-langserver (~/.local/bin), typescript-language-server (homebrew/npm global).

CI/CD

Пайплайн есть в каждом репозитории: lint → test → build → deploy.

  • Все джобы обязаны нести tags: [pet]. У group-раннера mybit run_untagged=false, поэтому джоба без тега уедет на instance-раннер VM gitlab, где нет доступа к docker.sock.
  • Потребители proto ставят GIT_SUBMODULE_STRATEGY: recursive. Новый потребитель должен быть добавлен в job-token allowlist проекта proto, иначе submodule не склонируется (LESSONS-0007).
  • deploy — ручной, только с main.
  • Смотреть результаты через mcp__gitlab__list_pipelines / get_pipeline_job_output, а не открывать UI руками.

Учётная запись автоматизации

Всё, что делает Claude Code в GitLab, идёт от отдельного пользователя claudeBot (claude@arvberezin.online), а не от владельца. Смысл простой: по журналу видно, что сделал человек, а что — автоматика, и апрув владельца остаётся единственным действием, которое нельзя списать на бота.
Роль Maintainer в группе mybit
Токен api + write_repository, больше ничего
Хранится homelab-infra: secrets/homelab.sops.yaml → services.gitlab.users.claudeBot
Используется GitLab MCP, git push (keychain), работа с доской

Maintainer — не «на всякий случай», а минимум для мержа: main защищён как push = никто, merge = Maintainer+. С ролью Developer апрув владельца было бы нечем применить.

Локально настроено: git-идентичность во всех десяти репозиториях, креды для gitlab.local в keychain, токен в MCP-конфиге (--scope local, вне git).

Проверено сквозняком: комментарий на доске, коммит и git push — все атрибутированы claudeBot, мерж в защищённый main доступен.

Открытый вопрос. Учётка сейчас is_admin: true — это заметно больше, чем нужно: админ читает чужие приватные репозитории, меняет настройки инстанса и выпускает impersonation-токены. Для всего перечисленного выше хватает Maintainer в одной группе. Снятие админки ждёт решения владельца.

Известные ограничения

  • playwright-extension и gitlab MCP зарегистрированы с --scope local — требуют перезапуска сессии Claude Code, чтобы подключиться.
  • GitLab-инстанс доступен только в домашней сети (gitlab.local, LAN) — вне сети MCP не сработает.
  • Локальные *.local — это mDNS: из контейнеров они не резолвятся, нужен extra_hosts (LESSONS-0008).
  • Инфраструктура (~/infra/homelab-infra) — отдельный репозиторий со своим контрактом: check-режим, подтверждение перед apply, обновление доков и CHANGELOG. Прогоны по mybit — только --limit pet.