Skip to content

AGENTS.md

Latest commit

 

History

History
159 lines (99 loc) · 7.07 KB

AGENTS.md

File metadata and controls

159 lines (99 loc) · 7.07 KB
Raw

Sentry Development Guide for AI Agents

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.

Command Execution Guide

Python Command Execution Requirements

CRITICAL: When running Python commands (pytest, mypy, prek, etc.), you MUST use the virtual environment.

For AI Agents (automated commands)

Use the full relative path to virtualenv executables:

cd /path/to/sentry && .venv/bin/pytest tests/...
cd /path/to/sentry && .venv/bin/python -m mypy ...

Or source the activate script in your command:

cd /path/to/sentry && source .venv/bin/activate && pytest tests/...

Important for AI agents:

  • Always use required_permissions: ['all'] when running Python commands to avoid sandbox permission issues
  • The .venv/bin/ prefix ensures you're using the correct Python interpreter and dependencies

Backend Development Commands

Setup

# Refreshes dependencies.
# SENTRY_DEVENV_FRONTEND_ONLY=1 skips over migrations which is not needed for pytest. HIGHLY RECOMMENDED.
SENTRY_DEVENV_FRONTEND_ONLY=1 devenv sync

# refresh dependencies, apply migrations
# Only relevant if you want a working development server.
devenv sync

direnv allow    # activate the environment
devservices up  # bring up services

That is all that is required to run pytest.

devservices serve starts the development server.

When the devserver is running, its full console output (all honcho-managed processes — server, taskworker, kafka consumers, webpack/watchers, etc.) is teed to .artifacts/dev.log, ANSI-stripped and gitignored. Agents can't see the devserver terminal, so tail/grep this file to inspect what's happening (startup, reloads, request logs, tracebacks). The file is truncated on each devserver process start (in-process granian reloads keep appending); override its path with SENTRY_DEV_LOG_FILE. Dev-only — this teeing lives in sentry devserver and is not used in production.

Linting

prek is the single entrypoint for all lint, format, and type-checking tools.

Before considering a task complete, run:

cd /path/to/sentry && .venv/bin/prek run -q

prek detects changed files automatically. To run a specific hook:

SENTRY_MYPY_PRE_PUSH=1 .venv/bin/prek run -q mypy --files src/sentry/foo/bar.py --stage pre-push
.venv/bin/prek run -q ruff --files src/sentry/foo/bar.py

If a hook fails, fix the issues, stage changes, then re-run until it passes.

Testing

For 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 it is 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 nodeids locally.

# Run a specific test file.
# Do not run pytest by itself; it'll take forever!
.venv/bin/pytest -n3 -svv --reuse-db tests/sentry/api/test_base.py

Database Operations

# Update migration after rebase conflict (handles renaming, dependencies, lockfile)
./bin/update-migration <migration_name_or_number> <app_label>
# Example: ./bin/update-migration 0101_workflow_when_condition_group_unique workflow_engine

Frontend Development Commands

Development Setup

pnpm run dev starts the full development server (requires devservices up). pnpm run dev-ui starts only the UI dev server with hot reload, proxying API requests to production sentry.io.

Dev server URLs:

Typechecking

To typecheck frontend code, run pnpm run typecheck. It checks the whole project and does not accept file paths. DO NOT use tsc directly.

Linting

pnpm run lint:js lints JS/TS; it accepts file paths (pnpm run lint:js components/avatar.tsx). pnpm run fix fixes what it can automatically.

Testing

pnpm test-ci <file_path> runs JS tests for the given file(s).

Git worktrees

Each worktree has its own .venv. When you create a new worktree with git worktree add, a post-checkout hook runs devenv sync in the new worktree to setup the dev environment. Otherwise run devenv sync once in the new worktree, then direnv allow to validate and activate the dev environment.

Context-Aware Loading

Use the right AGENTS.md for the area you're working in:

  • Backend (src/**/*.py) → src/AGENTS.md (backend patterns)
  • Tests (tests/**/*.py, src/**/tests/**/*.py) → tests/AGENTS.md (testing patterns)
  • Frontend (static/**/*.{ts,tsx,js,jsx,css,scss}) → static/AGENTS.md (frontend patterns)
  • General → This file (AGENTS.md) for Sentry overview and commands

Workflow 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.

Viewer/Organization Context

  • 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.

Agent Skills

Skills under .agents/skills/ should follow the same current-practice conventions as the rest of the repo:

  • Prefer diff-first review workflows. When no explicit file or patch is provided, default to the current branch diff.
  • Keep skill descriptions aligned with natural user requests like PR review, branch audit, and Warden follow-up.
  • If a downstream review harness controls the final response shape, do not hardcode a competing output format in the skill. Specify required evidence instead.

Feature Flags (FlagPole)

New features should be gated behind a feature flag. See the feature-flags skill (.agents/skills/feature-flags/) for registration, the features.has(...) check, the frontend check, and test usage.

Customer Information

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.

Pull Requests

Frontend (static/) and backend (src/, tests/) are not atomically deployed. A CI check enforces this.

  • If your changes touch both frontend and backend, split them into separate PRs.
  • Land the backend PR first when the frontend depends on new API changes.
  • Pure test additions alongside src/ changes are fine in one PR.