# Agent Instructions

## Tox

- Run tox via uv: `uv run tox -e <env>`
- `tox` + `tox-uv` are declared as the project's default dev dependencies in `pyproject.toml`, so uv installs them automatically into `.venv`.

## Package Manager

Use **tox** for testing (not pytest directly):
- Test matrix configuration is in `tox.ini`
- Integration tests: `uv run tox -e py3.14-{integration}-v{version}`
- Common tests: `uv run tox -e py3.14-common`
- Run specific test file: `TESTPATH=tests/integrations/logging/test_logging.py uv run tox -e py3.14-common`
- Run single test: `TESTPATH=tests/path/to/test_file.py uv run tox -e py3.14-common -- -k "test_name"`

## Type Checking

Mypy and its type stubs live in the opt-in `typing` dependency group:
- Run `uv run --group typing mypy sentry_sdk` before committing (must pass with zero errors)
- Strict mode enabled (`check_untyped_defs`, `disallow_untyped_defs`)

## Linting & Formatting

Use **ruff** for linting and formatting:
- `uv run ruff check --fix tests sentry_sdk`
- `uv run ruff format tests sentry_sdk`

## Commit Attribution

AI commits MUST include:
```
Co-Authored-By: <agent model name> <noreply@anthropic.com>
```
Example: `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`

## Auto-Generated Files

Do NOT edit these directly — modify source scripts instead:
- `tox.ini` — generated by `scripts/populate_tox/populate_tox.py` from `scripts/populate_tox/tox.jinja`
- `.github/workflows/test-integrations-*.yml` — generated by `scripts/split_tox_gh_actions/split_tox_gh_actions.py`
- Regenerate all: `scripts/generate-test-files.sh`

## Adding Integrations to Test Suite

1. Add minimum version to `_MIN_VERSIONS` in `sentry_sdk/integrations/__init__.py`
2. Add config to `TEST_SUITE_CONFIG` in `scripts/populate_tox/config.py`
3. Add to group in `scripts/split_tox_gh_actions/split_tox_gh_actions.py`
4. Run `scripts/generate-test-files.sh`

## Integration Contract

- Don't crash applications or swallow exceptions
- Don't mutate object references or alter function signatures
- Don't leak file descriptors or make unexpected DB requests
- Write defensive code
- Use end-to-end tests (not mocks)

## Key Paths

| Path | Description |
|------|-------------|
| `sentry_sdk/integrations/` | integration modules |
| `sentry_sdk/ai/` | AI monitoring |
| `sentry_sdk/crons/` | Cron monitoring |
| `sentry_sdk/profiler/` | Performance profiling |
| `tests/integrations/{name}/` | Integration test suites |
| `scripts/populate_tox/config.py` | Test suite configuration |
