# Agent Instructions

## Tox

- Always run tox from the main `tox.venv`
- If there is no `tox.venv`, create one with `python -m venv tox.venv`, activate it and run `pip install tox`

## Package Manager

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

## Type Checking

Use **tox** for type checking (not mypy directly):
- Run `tox -e mypy` before committing (must pass with zero errors)
- Strict mode enabled (`check_untyped_defs`, `disallow_untyped_defs`)

## Linting & Formatting

Use **tox** for linting (not ruff directly):
- `tox -e ruff`
- Full lint suite: `tox -e linters`
- Full lint suite must pass before committing

## 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 |
