zeroq-qol-modules/.agent/src/PROTOCOLS/01_ANALYSIS.md

Протокол 01: Анализ репозитория (ANALYSIS)

Цель

Составить полную картину целевого репозитория: тип проекта, архитектура, стек, конвенции, состояние тестов, требования.

Вход

• Целевой репозиторий (локальная копия)
• .agent/metaagent-request.md (конфигурация сессии: глубина, функции) — или auto-generated
• .agent/checkpoints.json (фаза analysis: pending)

Шаги

0.0. Чтение конфигурации сессии

Прочитать config из checkpoints.json (установлен на фазе INIT через 00_CONFIG.md).

Если config отсутствует или неполный — применить default:

{
  "depth": 4,
  "design": { "adr": false, "alternative_arch": false },
  "red_team": false,
  "risk_register": false,
  "decomposition": { "invariant_tests": false },
  "handoff": { "layer_structure": false }
}

Записать (или подтвердить) конфигурацию в checkpoints.json:

"config": {
  "depth": 6,
  "design": { "adr": true, "alternative_arch": true },
  "red_team": false,
  "risk_register": false,
  "decomposition": { "invariant_tests": true },
  "handoff": { "layer_structure": true }
}

Если .agent/metaagent-request.md не найден — использовать значения по умолчанию (depth=6, все базовые функции=true, расширенные=false).

1.0. Определение типа проекта

Просканировать корень репозитория и определить:

• existing — есть исходный код, тесты, система сборки (файлы .py, .js, .ts, .rs, .go и т.д. помимо конфигов и README)
• greenfield — репозиторий пуст или содержит только README, LICENSE, .gitignore
• scaffold — есть базовая структура (pyproject.toml/package.json), но нет значимого кода

Записать тип в analysis-report.md.

Правило: если проект existing — разделы 1.1–1.6 выполняются полностью. Если greenfield — разделы 1.2–1.5 заменяются на 1.7 (извлечение требований из README).

1.1. Общая информация

Прочитать и зафиксировать:

• README — описание проекта, how to build/test/run
• Лицензия — какой LICENSE
• CI/CD — .github/workflows/, .gitlab-ci.yml, Jenkinsfile, Makefile и т.д.
• Главные точки входа — main.py, index.js, cmd/ и т.д.
• Система сборки — package.json, pyproject.toml, Cargo.toml, go.mod, CMakeLists.txt

1.2. Стек технологий (только для existing/scaffold)

Определить:

• Язык(и) — Python, TypeScript, Go, Rust и т.д.
• Фреймворк — FastAPI, Next.js, React, Actix и т.д.
• База данных — PostgreSQL, SQLite, MongoDB и т.д.
• Тестовый раннер — pytest, jest, vitest, go test
• Пакетный менеджер — pip/poetry, npm/yarn/pnpm, cargo, go modules
• Линтер/форматтер — ruff, eslint, prettier, rustfmt, gofmt

1.3. Архитектура (только для existing/scaffold)

• Структура директорий — записать схему (можно tree /F, но не более 3 уровней глубины)
• Архитектурный паттерн — MVC, Clean Architecture, модульный монолит, микросервисы
• Ключевые модули/пакеты — перечислить с кратким описанием
• Внешние зависимости — основные библиотеки

1.4. Конвенции кода (только для existing/scaffold)

• Стиль кода — судя по линтеру и примерам: именование, импорты, типизация
• Паттерны — как организованы роуты, хендлеры, модели, тесты
• Обработка ошибок — как принято обрабатывать ошибки в проекте
• Логирование — используется ли логгер, какой уровень

1.5. Тесты (только для existing/scaffold)

• Какие тесты есть — unit, integration, e2e
• Где лежат — tests/, __tests__/, рядом с модулями
• Запуск — команда для запуска всех тестов
• Текущее состояние — запустить тесты, записать результат (сколько всего, сколько пройдено/упало)
• Покрытие — есть ли метрики покрытия

1.6. Базовая проверка (только для existing/scaffold)

• Собирается ли проект? — запустить сборку
• Запускается ли проект? — если возможно, проверить старт
• Чистый ли git status? — нет ли незакоммиченных изменений

1.7. Извлечение требований (только для greenfield/scaffold)

Если README содержит описание будущего проекта — извлечь и структурировать:

Функциональные требования:

• Пользовательские истории (user stories)
• Основные сценарии использования
• Входные/выходные данные системы

Нефункциональные требования:

• Технологические предпочтения (язык, фреймворк, БД)
• Требования к производительности, безопасности
• Ограничения (сроки, платформа, окружение)

Бизнес-контекст:

• Цель системы (зачем)
• Целевая аудитория
• Ключевые метрики успеха

Сомнительные/неясные требования:

• Вопросы, которые нужно задать пользователю перед проектированием
• Противоречия в README

Выход

.agent/analysis-report.md по шаблону TEMPLATES/analysis-report.md.

Обновить checkpoints.json: phases.analysis = "completed". Если проект greenfield, также установить project_type = "greenfield".

Критерии завершения фазы

• Тип проекта определён (existing / greenfield / scaffold)
• Все соответствующие разделы (1.1–1.7) выполнены
• .agent/analysis-report.md создан и заполнен
• checkpoints.json обновлён