Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (61 loc) · 4.18 KB

AGENTS.md

File metadata and controls

84 lines (61 loc) · 4.18 KB

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

Long-term Knowledge

Gotcha

  • AGENTS.md must be excluded from markdown linters: AGENTS.md is auto-managed by lore and uses `*` list markers and long lines that violate typical remark-lint rules (unordered-list-marker-style, maximum-line-length). When a project uses remark with `--frail` (warnings become errors), AGENTS.md will fail CI. Fix: add `AGENTS.md` to `.remarkignore`. This applies to any lore-managed project with markdown linting.
  • Consola prompt cancel returns truthy Symbol, not false: When a user cancels a `consola` / `@clack/prompts` confirmation prompt (Ctrl+C), the return value is `Symbol(clack:cancel)`, not `false`. Since Symbols are truthy in JavaScript, checking `!confirmed` will be `false` and the code falls through as if the user confirmed. Fix: use `confirmed !== true` (strict equality) instead of `!confirmed` to correctly handle cancel, false, and any other non-true values.
  • Zod z.coerce.number() converts null to 0 silently: Zod gotchas in this codebase: (1) `z.coerce.number()` passes input through `Number()`, so `null` silently becomes `0`. Be aware if `null` vs `0` distinction matters. (2) Zod v4 `.default({})` short-circuits — it returns the default value without parsing through inner schema defaults. So `.object({ enabled: z.boolean().default(true) }).default({})` returns `{}`, not `{ enabled: true }`. Fix: provide fully-populated default objects. This affected nested config sections in src/config.ts during the v3→v4 upgrade.