evening_detective_server/AGENTS.md

Backend — правила работы агента

Стек

• Go 1.26;
• gRPC + grpc-gateway;
• PostgreSQL через pgx;
• миграции Goose;
• S3-совместимое хранилище для файлов;
• MCP встроен в основной сервис.

Структура

• api/ — protobuf-контракт;
• proto/ — сгенерированный Go-код;
• internal/app/ — gRPC/HTTP handlers;
• internal/services/ — бизнес-логика;
• internal/repos/ — работа с PostgreSQL;
• internal/modules/ — переиспользуемые модули;
• migrations/ — миграции базы данных.

Правила

1. Сначала найди всех callers изменяемой функции и существующий паттерн.
2. Делай минимальное изменение; каждый модуль разделяй на интерфейс и реализацию.
3. Бизнес-логику держи в services, SQL — в repos, транспорт — в app.
4. Новые HTTP-методы добавляй через api/main.proto и регенерируй код.
5. proto/ и Swagger — сгенерированные файлы; руками их не редактируй.
6. Изменения схемы БД оформляй отдельной миграцией, совместимой с предыдущей версией.
7. Не добавляй .env, ключи, пароли или локальные артефакты в Git.
8. Коммиты и push выполняет только пользователь; агент никогда не коммитит и не отправляет изменения.

Проверки

gofmt -w <изменённые-go-файлы>
go test ./...

После изменения protobuf:

make generate

Для проверки с PostgreSQL используй отдельную тестовую базу через TEST_DATABASE_URL; интеграционные тесты не должны зависеть от production-базы.

Локальный запуск

docker compose -f docker-compose-db.yml up -d
cp .env.example .env
make run

gRPC слушает :8080, REST gateway — :8090.