docs: Add AGENTS.md

Author: sentrivana

AGENTS.md

@@ -0,0 +1,63 @@
+# Agent Instructions
+
+## Package Manager
+
+Use **tox** for testing (not pytest directly):
+- Always run tox from the main `.venv`. If there is no `.venv`, create it and install `pip install -r requirements-lint.txt -r requirements-test.txt tox`
+- Test matrix config is in `tox.ini`
+- Integration tests: `tox -e py3.14-{integration}-v{version}`
+- Common tests: `tox -e py3.14-common`
+
+## Type Checking
+
+- Always run mypy from the main `.venv`. If there is no `.venv`, create it and install `pip install -r requirements-lint.txt -r requirements-test.txt`
+- Run `mypy sentry_sdk` before committing (must pass with zero errors)
+- Strict mode enabled (`check_untyped_defs`, `disallow_untyped_defs`)
+
+## Linting & Formatting
+
+- **Ruff** for linting and formatting
+- `ruff check tests sentry_sdk`
+- `ruff format --check tests sentry_sdk`
+- Full lint suite: `tox -e linters`
+
+## 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 |

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md