AGENTS.md

AGENTS.md

AGENTS.md

Language Policy

• All chat responses and explanations: Russian only
• All git commit messages: English only
• All code comments, docstrings, variable names: English only
• All PR descriptions, issue comments, CI/CD messages: English only
• All file names, function names, class names: English only
• All review to Jira: English only
• When explaining what you did after a commit or file change — explain in Russian, but the commit message itself must always be in English.

General Behavior

• Before making changes — always read and understand existing code/structure first
• Ask clarifying questions before implementing if requirements are ambiguous
• Never delete or overwrite files without explicit confirmation
• Prefer small, focused commits over large bulk changes
• Always explain what was changed and why (in Russian)

Python Tooling

• Always use UV for Python package management and Python versioning
• Always use uv run to execute scripts instead of python directly
• Always define Python version in .python-version file (managed by UV)
• Always use pyproject.toml as the single source of truth (no setup.py, no requirements.txt)
• Always use uv lock to generate and commit uv.lock for reproducible builds
• Prefer virtual environments via uv venv — never use system Python
• Use uv add / uv remove — never edit pyproject.toml dependencies manually
• Separate dependency groups: [project.dependencies] for runtime, [dependency-groups] for dev/test/lint
• Always pin dev tools (ruff, mypy, pytest, bandit) as dev dependencies, not globally
• Use ruff for linting and formatting (replaces flake8, black, isort)
• Use mypy for static type checking with strict mode where possible
• Use pytest as the test runner

Code Quality

• All code must pass linting before committing (ruff, mypy, bandit, shellcheck)
• No hardcoded secrets, tokens, passwords — use env vars or secret managers
• No commented-out dead code in final commits
• Functions must have type hints and docstrings
• Max function length: ~50 lines — split if larger

Infrastructure as Code (Terraform)

• Always run terraform fmt and terraform validate before committing
• Use tflint and checkov for static analysis
• Never commit .terraform/, *.tfstate, *.tfvars with secrets
• Use Terragrunt for DRY multi-environment configs
• Tag all resources: environment, owner, project, managed-by
• Use remote state (S3 + DynamoDB or Azure Storage) — never local state

CI/CD

• All pipelines must have explicit timeout per job
• Secrets via GitHub Actions secrets or GitLab CI variables — never inline
• Use SARIF upload for security scan results where supported
• Separate stages: lint → test → build → scan → deploy
• Always use pinned versions for actions/images (never latest)

Docker & Containers

• Always use multi-stage builds
• Base images must be pinned to digest or explicit version tag
• Run hadolint on every Dockerfile
• Run trivy for image vulnerability scanning
• Never run containers as root unless explicitly required

Security

• Run gitleaks / trufflehog before every push
• Rotate credentials immediately if accidentally committed
• Use OIDC-based auth where possible (no long-lived tokens)
• Apply least-privilege principle for all IAM/RBAC roles

Observability

• New services must expose /health and /metrics endpoints
• Add Prometheus metrics for key business operations
• Dashboards (Grafana) must be stored as code (JSON/YAML)
• Alerts must have runbook links in annotations

Git Hygiene

• Branch naming: feat/, fix/, chore/, docs/, refactor/
• Commit message format: type(scope): short description (Conventional Commits)
• No force-push to main/master/develop
• Squash WIP commits before merging
• PRs must reference an issue or ticket number