{"owner":"getsentry","repo":"sentry","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Sentry Development Guide for AI Agents\n\n> **IMPORTANT**: AGENTS.md files are the source of truth for AI agent instructions. Always update the relevant AGENTS.md file when adding or modifying agent guidance. Do not add to CLAUDE.md or Cursor rules.\n\n## Command Execution Guide\n\nCritical command instructions that apply across all Sentry development.\n\n### Python Command Execution Requirements\n\n**CRITICAL**: Python commands (pytest, mypy, prek, etc.) MUST run in the virtualenv. Prefix the full relative path, or source the activate script:\n\n```bash\ncd /path/to/sentry && .venv/bin/pytest tests/...\ncd /path/to/sentry && source .venv/bin/activate && pytest tests/...\n```\n\nFor AI agents: always use `required_permissions: ['all']` for Python commands to avoid sandbox permission issues.\n\n### Backend Development Commands\n\n#### Setup\n\n```bash\n# Refreshes dependencies. SENTRY_DEVENV_FRONTEND_ONLY=1 skips migrations\n# (not needed for pytest). HIGHLY RECOMMENDED.\nSENTRY_DEVENV_FRONTEND_ONLY=1 devenv sync\n\n# Refresh dependencies AND apply migrations (only for a working dev server).\ndevenv sync\n\ndirenv allow    # activate the environment\ndevservices up  # bring up services\n```\n\nThat is all that is required to run `pytest`. `devservices serve` starts the development server. For full environment setup/troubleshooting, use the **`setup-dev`** skill.\n\nWhen the devserver runs, its full console output is teed to `.artifacts/dev.log` (ANSI-stripped, gitignored, truncated per process start; override with `SENTRY_DEV_LOG_FILE`). Agents can't see the devserver terminal — `tail`/`grep` this file to inspect startup, reloads, request logs, and tracebacks. Dev-only.\n\n#### Linting\n\nprek is the single entrypoint for all lint, format, and type-checking tools. Before considering a task complete, run `.venv/bin/prek run -q` (detects changed files automatically). To run a specific hook:\n\n```bash\nSENTRY_MYPY_PRE_PUSH=1 .venv/bin/prek run -q mypy --files src/sentry/foo/bar.py --stage pre-push\n.venv/bin/prek run -q ruff --files src/sentry/foo/bar.py\n```\n\nIf a hook fails, fix the issues, stage changes, then re-run until it passes.\n\n#### Testing\n\nFor backend-scoped changes, prioritize running the individual relevant pytest files or nodeids locally. `make test-selective` is not optimized for routine local development, so use it only when useful for a particular investigation. If a PR's backend CI fails, inspect the `select-tests` job in `.github/workflows/backend.yml` and its selected-test output to identify the exact nodeids CI ran, then run those locally.\n\n```bash\n# Run a specific test file. Do not run pytest by itself; it'll take forever!\n.venv/bin/pytest -n3 -svv --reuse-db tests/sentry/api/test_base.py\n```\n\n#### Database Operations\n\nCreating/applying migrations and resolving rebase conflicts (`makemigrations`, `django migrate`, `update-migration`) → use the **`generate-migration`** skill. To reset the database (`make reset-db`) or other environment tasks → use the **`setup-dev`** skill.\n\n### Frontend Development Commands\n\n#### Development Setup\n\n```bash\npnpm run dev     # full dev server (requires devservices up)\npnpm run dev-ui  # UI-only with hot reload; proxies API to production sentry.io\n```\n\nDev server URLs: full devserver `http://dev.getsentry.net:8000`; frontend-only `https://sentry.dev.getsentry.net:7999/`.\n\n#### Typechecking\n\nRun the `pnpm run typecheck` script. It checks the whole project and does not accept file paths. DO NOT use `tsc` directly.\n\n#### Linting\n\n```bash\npnpm run lint:js                          # all JS/TS\npnpm run lint:js components/avatar.tsx    # specific file(s)\npnpm run fix                              # auto-fix\n```\n\n#### Testing\n\n```bash\npnpm test-ci <file_path>                       # run tests\npnpm test-ci components/avatar.spec.tsx        # specific file(s)\n```\n\n### Context-Aware Loading\n\nUse the right AGENTS.md for the area you're working in:\n\n- **Backend** (`src/**/*.py`) → `src/AGENTS.md` (backend patterns)\n- **Tests** (`tests/**/*.py`, `src/**/tests/**/*.py`) → `tests/AGENTS.md` (testing patterns)\n- **Frontend** (`static/**/*.{ts,tsx,js,jsx,css,scss}`) → `static/AGENTS.md` (frontend patterns)\n- **General** → This file (`AGENTS.md`) for Sentry overview and commands\n\nWorkflow steering (commit, pre-commit, hybrid cloud, etc.) lives in **skills** (`.agents/skills/`). Attach or read the area `AGENTS.md` when working in that tree. Add or update guidance in the appropriate AGENTS.md or skill—do not duplicate long guidance in editor-specific rule files.\n\n## Viewer/Organization Context\n\n- Viewer identity is wired through the app via the `ViewerContext` contextvar; use `sentry.viewer_context.get_viewer_context()` instead of explicitly threading org/user identity when the current viewer is in scope.\n\n## Agent Skills\n\nSkills under `.agents/skills/` should follow the same current-practice conventions as the rest of the repo:\n\n- Prefer diff-first review workflows. When no explicit file or patch is provided, default to the current branch diff.\n- Keep skill descriptions aligned with natural user requests like PR review, branch audit, and Warden follow-up.\n- If a downstream review harness controls the final response shape, do not hardcode a competing output format in the skill. Specify required evidence instead.\n\n## Feature Flags (FlagPole)\n\nNew features should be gated behind a flag: register in `src/sentry/features/temporary.py`, check with `features.has(...)` (Python) or `organization.features.includes(...)` (frontend). For the full workflow (registration, `api_expose`, tests, rollout) → use the **`feature-flags`** skill, or see https://develop.sentry.dev/feature-flags/.\n\n## Customer Information\n\n**Never include customer information in pull requests, commits, or code.** This covers organization slugs, user emails, account names, internal IDs tied to specific customers, support ticket details, and any other data that identifies a Sentry customer. Use anonymized or synthetic examples (`org-slug`, `user@example.com`) in PR descriptions, commit messages, code comments, tests, and fixtures. If a real identifier is needed for debugging, keep it in internal tooling (Slack, tickets, private notes)—not in the public git history.\n\n## Pull Requests\n\nFrontend (`static/`) and backend (`src/`, `tests/`) are **not atomically deployed**. A CI check enforces this.\n\n- If your changes touch both frontend and backend, split them into **separate PRs**.\n- Land the backend PR first when the frontend depends on new API changes.\n- Pure test additions alongside `src/` changes are fine in one PR.\n"},"files":{"AGENTS.md":"# Sentry Development Guide for AI Agents\n\n> **IMPORTANT**: AGENTS.md files are the source of truth for AI agent instructions. Always update the relevant AGENTS.md file when adding or modifying agent guidance. Do not add to CLAUDE.md or Cursor rules.\n\n## Command Execution Guide\n\nCritical command instructions that apply across all Sentry development.\n\n### Python Command Execution Requirements\n\n**CRITICAL**: Python commands (pytest, mypy, prek, etc.) MUST run in the virtualenv. Prefix the full relative path, or source the activate script:\n\n```bash\ncd /path/to/sentry && .venv/bin/pytest tests/...\ncd /path/to/sentry && source .venv/bin/activate && pytest tests/...\n```\n\nFor AI agents: always use `required_permissions: ['all']` for Python commands to avoid sandbox permission issues.\n\n### Backend Development Commands\n\n#### Setup\n\n```bash\n# Refreshes dependencies. SENTRY_DEVENV_FRONTEND_ONLY=1 skips migrations\n# (not needed for pytest). HIGHLY RECOMMENDED.\nSENTRY_DEVENV_FRONTEND_ONLY=1 devenv sync\n\n# Refresh dependencies AND apply migrations (only for a working dev server).\ndevenv sync\n\ndirenv allow    # activate the environment\ndevservices up  # bring up services\n```\n\nThat is all that is required to run `pytest`. `devservices serve` starts the development server. For full environment setup/troubleshooting, use the **`setup-dev`** skill.\n\nWhen the devserver runs, its full console output is teed to `.artifacts/dev.log` (ANSI-stripped, gitignored, truncated per process start; override with `SENTRY_DEV_LOG_FILE`). Agents can't see the devserver terminal — `tail`/`grep` this file to inspect startup, reloads, request logs, and tracebacks. Dev-only.\n\n#### Linting\n\nprek is the single entrypoint for all lint, format, and type-checking tools. Before considering a task complete, run `.venv/bin/prek run -q` (detects changed files automatically). To run a specific hook:\n\n```bash\nSENTRY_MYPY_PRE_PUSH=1 .venv/bin/prek run -q mypy --files src/sentry/foo/bar.py --stage pre-push\n.venv/bin/prek run -q ruff --files src/sentry/foo/bar.py\n```\n\nIf a hook fails, fix the issues, stage changes, then re-run until it passes.\n\n#### Testing\n\nFor backend-scoped changes, prioritize running the individual relevant pytest files or nodeids locally. `make test-selective` is not optimized for routine local development, so use it only when useful for a particular investigation. If a PR's backend CI fails, inspect the `select-tests` job in `.github/workflows/backend.yml` and its selected-test output to identify the exact nodeids CI ran, then run those locally.\n\n```bash\n# Run a specific test file. Do not run pytest by itself; it'll take forever!\n.venv/bin/pytest -n3 -svv --reuse-db tests/sentry/api/test_base.py\n```\n\n#### Database Operations\n\nCreating/applying migrations and resolving rebase conflicts (`makemigrations`, `django migrate`, `update-migration`) → use the **`generate-migration`** skill. To reset the database (`make reset-db`) or other environment tasks → use the **`setup-dev`** skill.\n\n### Frontend Development Commands\n\n#### Development Setup\n\n```bash\npnpm run dev     # full dev server (requires devservices up)\npnpm run dev-ui  # UI-only with hot reload; proxies API to production sentry.io\n```\n\nDev server URLs: full devserver `http://dev.getsentry.net:8000`; frontend-only `https://sentry.dev.getsentry.net:7999/`.\n\n#### Typechecking\n\nRun the `pnpm run typecheck` script. It checks the whole project and does not accept file paths. DO NOT use `tsc` directly.\n\n#### Linting\n\n```bash\npnpm run lint:js                          # all JS/TS\npnpm run lint:js components/avatar.tsx    # specific file(s)\npnpm run fix                              # auto-fix\n```\n\n#### Testing\n\n```bash\npnpm test-ci <file_path>                       # run tests\npnpm test-ci components/avatar.spec.tsx        # specific file(s)\n```\n\n### Context-Aware Loading\n\nUse the right AGENTS.md for the area you're working in:\n\n- **Backend** (`src/**/*.py`) → `src/AGENTS.md` (backend patterns)\n- **Tests** (`tests/**/*.py`, `src/**/tests/**/*.py`) → `tests/AGENTS.md` (testing patterns)\n- **Frontend** (`static/**/*.{ts,tsx,js,jsx,css,scss}`) → `static/AGENTS.md` (frontend patterns)\n- **General** → This file (`AGENTS.md`) for Sentry overview and commands\n\nWorkflow steering (commit, pre-commit, hybrid cloud, etc.) lives in **skills** (`.agents/skills/`). Attach or read the area `AGENTS.md` when working in that tree. Add or update guidance in the appropriate AGENTS.md or skill—do not duplicate long guidance in editor-specific rule files.\n\n## Viewer/Organization Context\n\n- Viewer identity is wired through the app via the `ViewerContext` contextvar; use `sentry.viewer_context.get_viewer_context()` instead of explicitly threading org/user identity when the current viewer is in scope.\n\n## Agent Skills\n\nSkills under `.agents/skills/` should follow the same current-practice conventions as the rest of the repo:\n\n- Prefer diff-first review workflows. When no explicit file or patch is provided, default to the current branch diff.\n- Keep skill descriptions aligned with natural user requests like PR review, branch audit, and Warden follow-up.\n- If a downstream review harness controls the final response shape, do not hardcode a competing output format in the skill. Specify required evidence instead.\n\n## Feature Flags (FlagPole)\n\nNew features should be gated behind a flag: register in `src/sentry/features/temporary.py`, check with `features.has(...)` (Python) or `organization.features.includes(...)` (frontend). For the full workflow (registration, `api_expose`, tests, rollout) → use the **`feature-flags`** skill, or see https://develop.sentry.dev/feature-flags/.\n\n## Customer Information\n\n**Never include customer information in pull requests, commits, or code.** This covers organization slugs, user emails, account names, internal IDs tied to specific customers, support ticket details, and any other data that identifies a Sentry customer. Use anonymized or synthetic examples (`org-slug`, `user@example.com`) in PR descriptions, commit messages, code comments, tests, and fixtures. If a real identifier is needed for debugging, keep it in internal tooling (Slack, tickets, private notes)—not in the public git history.\n\n## Pull Requests\n\nFrontend (`static/`) and backend (`src/`, `tests/`) are **not atomically deployed**. A CI check enforces this.\n\n- If your changes touch both frontend and backend, split them into **separate PRs**.\n- Land the backend PR first when the frontend depends on new API changes.\n- Pure test additions alongside `src/` changes are fine in one PR.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Sentry Development Guide for AI Agents\n\n> **IMPORTANT**: AGENTS.md files are the source of truth for AI agent instructions. Always update the relevant AGENTS.md file when adding or modifying agent guidance. Do not add to CLAUDE.md or Cursor rules.\n\n## Command Execution Guide\n\nCritical command instructions that apply across all Sentry development.\n\n### Python Command Execution Requirements\n\n**CRITICAL**: Python commands (pytest, mypy, prek, etc.) MUST run in the virtualenv. Prefix the full relative path, or source the activate script:\n\n```bash\ncd /path/to/sentry && .venv/bin/pytest tests/...\ncd /path/to/sentry && source .venv/bin/activate && pytest tests/...\n```\n\nFor AI agents: always use `required_permissions: ['all']` for Python commands to avoid sandbox permission issues.\n\n### Backend Development Commands\n\n#### Setup\n\n```bash\n# Refreshes dependencies. SENTRY_DEVENV_FRONTEND_ONLY=1 skips migrations\n# (not needed for pytest). HIGHLY RECOMMENDED.\nSENTRY_DEVENV_FRONTEND_ONLY=1 devenv sync\n\n# Refresh dependencies AND apply migrations (only for a working dev server).\ndevenv sync\n\ndirenv allow    # activate the environment\ndevservices up  # bring up services\n```\n\nThat is all that is required to run `pytest`. `devservices serve` starts the development server. For full environment setup/troubleshooting, use the **`setup-dev`** skill.\n\nWhen the devserver runs, its full console output is teed to `.artifacts/dev.log` (ANSI-stripped, gitignored, truncated per process start; override with `SENTRY_DEV_LOG_FILE`). Agents can't see the devserver terminal — `tail`/`grep` this file to inspect startup, reloads, request logs, and tracebacks. Dev-only.\n\n#### Linting\n\nprek is the single entrypoint for all lint, format, and type-checking tools. Before considering a task complete, run `.venv/bin/prek run -q` (detects changed files automatically). To run a specific hook:\n\n```bash\nSENTRY_MYPY_PRE_PUSH=1 .venv/bin/prek run -q mypy --files src/sentry/foo/bar.py --stage pre-push\n.venv/bin/prek run -q ruff --files src/sentry/foo/bar.py\n```\n\nIf a hook fails, fix the issues, stage changes, then re-run until it passes.\n\n#### Testing\n\nFor backend-scoped changes, prioritize running the individual relevant pytest files or nodeids locally. `make test-selective` is not optimized for routine local development, so use it only when useful for a particular investigation. If a PR's backend CI fails, inspect the `select-tests` job in `.github/workflows/backend.yml` and its selected-test output to identify the exact nodeids CI ran, then run those locally.\n\n```bash\n# Run a specific test file. Do not run pytest by itself; it'll take forever!\n.venv/bin/pytest -n3 -svv --reuse-db tests/sentry/api/test_base.py\n```\n\n#### Database Operations\n\nCreating/applying migrations and resolving rebase conflicts (`makemigrations`, `django migrate`, `update-migration`) → use the **`generate-migration`** skill. To reset the database (`make reset-db`) or other environment tasks → use the **`setup-dev`** skill.\n\n### Frontend Development Commands\n\n#### Development Setup\n\n```bash\npnpm run dev     # full dev server (requires devservices up)\npnpm run dev-ui  # UI-only with hot reload; proxies API to production sentry.io\n```\n\nDev server URLs: full devserver `http://dev.getsentry.net:8000`; frontend-only `https://sentry.dev.getsentry.net:7999/`.\n\n#### Typechecking\n\nRun the `pnpm run typecheck` script. It checks the whole project and does not accept file paths. DO NOT use `tsc` directly.\n\n#### Linting\n\n```bash\npnpm run lint:js                          # all JS/TS\npnpm run lint:js components/avatar.tsx    # specific file(s)\npnpm run fix                              # auto-fix\n```\n\n#### Testing\n\n```bash\npnpm test-ci <file_path>                       # run tests\npnpm test-ci components/avatar.spec.tsx        # specific file(s)\n```\n\n### Context-Aware Loading\n\nUse the right AGENTS.md for the area you're working in:\n\n- **Backend** (`src/**/*.py`) → `src/AGENTS.md` (backend patterns)\n- **Tests** (`tests/**/*.py`, `src/**/tests/**/*.py`) → `tests/AGENTS.md` (testing patterns)\n- **Frontend** (`static/**/*.{ts,tsx,js,jsx,css,scss}`) → `static/AGENTS.md` (frontend patterns)\n- **General** → This file (`AGENTS.md`) for Sentry overview and commands\n\nWorkflow steering (commit, pre-commit, hybrid cloud, etc.) lives in **skills** (`.agents/skills/`). Attach or read the area `AGENTS.md` when working in that tree. Add or update guidance in the appropriate AGENTS.md or skill—do not duplicate long guidance in editor-specific rule files.\n\n## Viewer/Organization Context\n\n- Viewer identity is wired through the app via the `ViewerContext` contextvar; use `sentry.viewer_context.get_viewer_context()` instead of explicitly threading org/user identity when the current viewer is in scope.\n\n## Agent Skills\n\nSkills under `.agents/skills/` should follow the same current-practice conventions as the rest of the repo:\n\n- Prefer diff-first review workflows. When no explicit file or patch is provided, default to the current branch diff.\n- Keep skill descriptions aligned with natural user requests like PR review, branch audit, and Warden follow-up.\n- If a downstream review harness controls the final response shape, do not hardcode a competing output format in the skill. Specify required evidence instead.\n\n## Feature Flags (FlagPole)\n\nNew features should be gated behind a flag: register in `src/sentry/features/temporary.py`, check with `features.has(...)` (Python) or `organization.features.includes(...)` (frontend). For the full workflow (registration, `api_expose`, tests, rollout) → use the **`feature-flags`** skill, or see https://develop.sentry.dev/feature-flags/.\n\n## Customer Information\n\n**Never include customer information in pull requests, commits, or code.** This covers organization slugs, user emails, account names, internal IDs tied to specific customers, support ticket details, and any other data that identifies a Sentry customer. Use anonymized or synthetic examples (`org-slug`, `user@example.com`) in PR descriptions, commit messages, code comments, tests, and fixtures. If a real identifier is needed for debugging, keep it in internal tooling (Slack, tickets, private notes)—not in the public git history.\n\n## Pull Requests\n\nFrontend (`static/`) and backend (`src/`, `tests/`) are **not atomically deployed**. A CI check enforces this.\n\n- If your changes touch both frontend and backend, split them into **separate PRs**.\n- Land the backend PR first when the frontend depends on new API changes.\n- Pure test additions alongside `src/` changes are fine in one PR.\n","category":"root","tokens":1646}]}