/repo-scout — Разведка бэкенд-репозитория

<purpose> Глубокое сканирование бэкенд-репозитория → структурированный отчёт об API surface, архитектуре, инфраструктуре и текущем покрытии тестами. Даёт AI и человеку полную картину сервиса перед планированием тестового покрытия. </purpose>

Когда использовать

•Первый вход в новый бэкенд-репозиторий
•Перед /test-cases — для сбора данных
•Перед /init-project — для понимания целевого сервиса
•Периодический аудит: "что изменилось в API surface?"

Когда НЕ использовать

•QA-проекты с тестами (используй /init-project)
•Code review (используй стандартные инструменты)
•Фронтенд/мобильные репозитории

Входные данные

•Путь к репозиторию (или текущая директория)
•Не требует CLAUDE.md, qa_agent.md или других AI-файлов
•Может быть первым шагом в новом репо

Алгоритм

Verbosity Protocol

Structured Output Priority: Весь analysis идёт в артефакт (MD/HTML), не в чат.

Chat output (ограничения):

•Brief Summary: max 5 строк (что нашли, сколько, итог)
•Findings table: max 15 строк (топ по severity)
•Полный отчёт: 📊 Полный отчёт: {path} + открыть файл

Iterative steps: Не выводить прогресс по каждому файлу. Checkpoint только при:

•Phase transition (Фаза N → Фаза N+1)
•Предупреждение обнаружено
•Завершение (SKILL COMPLETE)

Tools first:

•Grep → table → report, без "Now I will grep..."
•Read → analyze → report, без "The file shows..."

Post-Check: Inline перед SKILL COMPLETE (5-7 строк checklist), не отдельный файл.

Фазы 1-5: Silent execution. Фаза 6: Только Summary table + "Отчёт: audit/repo-scout-report.md".

Перед началом

Прочитай .claude/qa_agent.md (если есть в рабочем проекте). Выведи:

code

📋 TASK BRIEF
├─ Target: {repo-name} — разведка бэкенд-сервиса
├─ Scope: API surface + инфраструктура + тестовое покрытие
├─ Constraint: Read-only, только Go-паттерны
└─ Action: Вызываю /repo-scout...

Фаза 1: File System Scan

Цель: Определить язык, билд-систему, структуру директорий.

•
Проверь наличие build-файлов:
code
```
go.mod, go.sum, Makefile
```
Если go.mod не найден — выведи: "⚠️ WARNING: go.mod не найден, возможно не Go-проект. Сканирую доступную структуру."
•
Извлеки из go.mod:
- •Имя модуля (module path)
- •Версию Go
- •Ключевые зависимости (HTTP-фреймворк, gRPC, DB driver, тестовые библиотеки)

•

Определи структуру:

code

Glob: cmd/*/main.go → список сервисов
Glob: internal/*/ → бизнес-модули
Glob: pkg/*/ → публичные пакеты

•

Подсчитай размер:

code

Количество .go файлов (без *_test.go)
Количество *_test.go файлов

Фаза 2: API Surface Discovery

Цель: Найти и каталогизировать ВСЕ API endpoints.

2.1 OpenAPI / Swagger

Ищи файлы:

code

Glob: **/swagger.json, **/swagger.yaml, **/openapi.json, **/openapi.yaml, **/*.swagger.json

Для каждого найденного файла:

•Прочитай файл
•Извлеки endpoints: Method, Path, Description
•Отметь наличие/отсутствие response schemas, error codes

2.2 Protocol Buffers (gRPC)

Ищи файлы:

code

Glob: **/*.proto

Для каждого .proto файла:

•Извлеки services и rpc methods
•Запиши Request/Response типы
•Отметь streaming methods (если есть)

2.3 Route Registration (из кода)

Прочитай references/lang-patterns.md для актуальных паттернов.

Ищи в Go-файлах паттерны регистрации маршрутов:

code

Grep: r\.HandleFunc|r\.Get\(|r\.Post\(|r\.Put\(|r\.Delete\(|r\.Route\(|\.GET\(|\.POST\(|echo\.

Для каждого найденного:

•Файл + строка
•HTTP метод + путь
•Handler функция

⚠️ Не дублируй: Если endpoint уже найден в swagger/proto — не добавляй из кода.

2.4 HTTP Client файлы

code

Glob: **/*.http, **/api.http

Если найдены — отметь как дополнительный источник примеров.

Фаза 3: Test Analysis

Цель: Оценить текущее тестовое покрытие.

•
Найди все тестовые файлы:
code
```
Glob: **/*_test.go
```
•
Классифицируй по типу:
- •Unit: файлы без //go:build integration и без Docker/DB imports
- •Integration: файлы с //go:build integration или с sqlmock/testcontainers
- •E2E/API: отдельные тест-репозитории (проверь README на ссылки)
•
Определи тестовые фреймворки:
code
```
Grep в go.mod: testify, gomock, go-sqlmock, testcontainers
```
•
Проверь наличие внешних тест-репозиториев:
- •Ищи в README ссылки на indrive-api-tests-* или *-tests
- •Проверь .dev-platform/ на test runner конфигурации

Фаза 4: Infrastructure Scan

Цель: Понять инфраструктурный контекст.

•
CI/CD:
code
```
Glob: .github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile
```
Кратко: какие пайплайны, есть ли тесты в CI.
•
Docker:
code
```
Glob: **/Dockerfile, **/docker-compose.yaml, **/docker-compose.yml
```
Какие сервисы в compose (DB, Redis, Kafka, etc.)
•
Database:
code
```
Glob: migrations/**, **/migrations/**, **/liquibase/**
```
Тип миграций (Liquibase, goose, Atlas), количество changesets.
•
Конфигурация:
code
```
Glob: config/*.yaml, config/*.yml
```
Среды (local, dev, prod), внешние сервисы.
•
Dev-Platform:
code
```
Glob: .dev-platform/**
```
Если есть — отметить shared-сервисы и зависимости.

Фаза 5: AI Setup Status

Проверь наличие AI-файлов:

code

- CLAUDE.md
- .claude/qa_agent.md
- .claude/skills/*/SKILL.md
- .agents/skills/*/SKILL.md
- AGENTS.md
- .cursor/rules/*.mdc
- .github/copilot-instructions.md

Фаза 6: Report Generation

Собери отчёт и сохрани в audit/repo-scout-report.md. Полный шаблон отчёта с примерами — в references/report-template.md.

Обязательные секции:

•Repository Profile (module, Go version, service type, dependencies)
•API Surface Catalog (REST + gRPC endpoints с Summary)
•Specification Inventory (coverage формула)
•Existing Test Coverage (unit/integration/e2e)
•Infrastructure (CI/CD, Docker, DB, Migrations, Queue, Cache)
•AI Setup Status (CLAUDE.md, qa_agent.md, skills)
•Readiness Assessment (specs, tests, docs, AI setup + blockers + next step)

Quality Gates

• go.mod найден и распарсен
• Все proto файлы прочитаны и RPCs каталогизированы
• Все swagger/openapi файлы прочитаны и endpoints каталогизированы
• Endpoint counts корректны (показана формула)
• Нет placeholder'ов {xxx} в финальном отчёте (кроме "нет")
• Readiness Assessment заполнен по всем 4 критериям

Self-Check

Перед сохранением отчёта проверь:

• Completeness: Все 7 секций заполнены?
• Accuracy: Количества endpoints совпадают между секциями 2 и 3?
• No Hallucinations: Каждый endpoint реально найден в файле (указан источник)?
• Readiness: Оценка обоснована данными из секций 2-5?

Завершение

После сохранения audit/repo-scout-report.md — напечатай блок SKILL COMPLETE (формат в qa_agent.md § Skill Completion Protocol).

Self-Review для этого скилла не генерируется (read-only сканирование, не генерация контента).

code

✅ SKILL COMPLETE: /repo-scout
├─ Артефакты: audit/repo-scout-report.md
├─ Self-Review: N/A (сканирование)
├─ Compilation: N/A
├─ Upstream: нет
└─ Endpoints: {N REST} + {M gRPC} = {total}

Связанные файлы

•Паттерны Go: references/lang-patterns.md
•Следующий шаг: /test-cases (использует repo-scout-report.md как вход)
•AI-файлы: /init-project → CLAUDE.md, /init-agent → qa_agent.md