Emil_Shanayev_Resume/CLAUDE.md

CLAUDE.md — my-project

описание проекта

Стек

Языки: Go, TypeScript Frontend: React, TypeScript Инфраструктура: Docker, Kubernetes, GitHub Actions, Jenkins Стиль кода: Минимальные зависимости, явные типы (Go type hints + TS strict mode)

---

Принципы работы агента

• При неоднозначности в задаче — спрашивай, не угадывай и не двигайся вперёд.
• Предпочитай простейшее рабочее решение. Не создавай абстракций без необходимости.
• Не трогай код, файлы и конфиги вне скоупа текущей задачи.
• Верифицируй результат: запускай тесты, проверяй edge cases до завершения задачи.
• Не ломай существующие тесты ради реализации новой функциональности.

---

Запрещено

• Не изменять .env, docker-compose.yml, k8s/prod/* без явного разрешения.
• Не делать git push --force ни при каких обстоятельствах.
• Не деплоить в production без явного подтверждения пользователя.
• Не удалять Kubernetes namespaces, PersistentVolumes или secrets без явной команды.
• Не изменять pipeline-конфиги (Jenkinsfile, .github/workflows/*) без обсуждения.

---

Точки остановки (обязательный checkpoint)

Агент обязан остановиться и явно спросить разрешение перед:

• Любыми изменениями в k8s/prod/* или k8s/staging/*
• Удалением Docker-образов, volumes или сетей
• Изменением RBAC-правил или ServiceAccount'ов
• Ротацией или созданием новых secrets/credentials
• Изменением resource limits/requests на production-сервисах
• Любой операцией, которую нельзя откатить за < 5 минут

---

Структура проекта

.
├── cmd/              # точки входа (main.go)
├── internal/         # приватный код приложения
├── pkg/              # публичные пакеты
├── frontend/         # React-приложение (TypeScript)
│   ├── src/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── pages/
│   └── package.json
├── k8s/
│   ├── base/         # базовые манифесты
│   ├── staging/      # overlays для staging
│   └── prod/         # overlays для production  ← только с разрешения
├── .github/
│   └── workflows/    # GitHub Actions pipelines
├── Dockerfile
├── docker-compose.yml  ← не изменять без разрешения
└── .env                ← не изменять без разрешения

---

Соглашения по коду (Go)

• Стиль: стандартный gofmt / goimports
• Линтер: golangci-lint — запускать перед коммитом
• Ошибки: всегда оборачивать через fmt.Errorf("...: %w", err)
• Логирование: использовать структурированный логгер (slog / zap), не fmt.Println
• Конфигурация: через переменные окружения, не хардкодить значения
• Зависимости: минимальные; новую зависимость — только с обоснованием

---

Соглашения по коду (React / TypeScript)

• TypeScript strict mode обязателен ("strict": true в tsconfig)
• Компоненты: только функциональные, без class components
• Именование: компоненты — PascalCase, хуки — useCamelCase, файлы — kebab-case.tsx
• Стейт: локальный через useState/useReducer; глобальный — только при явной необходимости
• Пропсы: всегда типизировать через interface, не type (для расширяемости)
• Эффекты: не использовать useEffect для получения данных — использовать React Query / SWR
• Линтер: ESLint + eslint-plugin-react-hooks — запускать перед коммитом
• Форматтер: Prettier с конфигом из репозитория — не менять настройки
• Тесты: Vitest + React Testing Library; не тестировать детали реализации, только поведение
• Никаких any типов — использовать unknown + type guard при необходимости

---

CI/CD соглашения

GitHub Actions

• Каждый PR запускает: lint → test → build → docker build
• Образы тегируются: <registry>/<app>:<git-sha>
• Merge в main → автодеплой на staging

Jenkins

• Production-деплой только через Jenkins pipeline с ручным approve-шагом
• Rollback через helm rollback или kubectl rollout undo

---

Работа с Docker

• Base image: gcr.io/distroless/static-debian12 или alpine:3.x — не latest
• Multi-stage build обязателен для Go-бинарей
• Никаких секретов в ENV инструкциях Dockerfile (использовать BuildKit secrets или runtime env)
• Образы сканировать через trivy в CI перед пушем

---

Работа с Kubernetes

• Все манифесты через Kustomize (не сырой kubectl apply в production)
• Resource requests/limits — обязательны для каждого контейнера
• Liveness/readiness probes — обязательны
• PodDisruptionBudget — обязателен для stateful сервисов
• Никаких latest тегов в манифестах

---

Тестирование

• Unit-тесты: go test ./...
• Интеграционные тесты: go test -tags=integration ./...
• Покрытие Go: цель ≥ 70% для internal/
• Frontend тесты: pnpm test (Vitest) — запускать из frontend/
• Перед завершением задачи: убедиться, что все тесты проходят

---

Соглашения по коммитам (Conventional Commits)

feat:     новая функциональность
fix:      исправление бага
chore:    рутинные задачи (зависимости, конфиги)
refactor: рефакторинг без изменения поведения
test:     добавление/изменение тестов
ci:       изменения в CI/CD пайплайнах
docs:     документация

Примеры:

• feat(auth): add JWT validation middleware
• fix(deploy): correct resource limits for worker pod
• ci: add trivy scan step to GitHub Actions