From 4614364269c68c0d670f6d0b8944352745935c6a Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 25 Feb 2026 14:25:34 +0100 Subject: [PATCH 1/5] add agents.md --- .cursor/rules/sdk_development.mdc | 209 ------------------------------ AGENTS.md | 134 +++++++++++++++++++ CLAUDE.md | 189 +-------------------------- 3 files changed, 138 insertions(+), 394 deletions(-) delete mode 100644 .cursor/rules/sdk_development.mdc create mode 100644 AGENTS.md diff --git a/.cursor/rules/sdk_development.mdc b/.cursor/rules/sdk_development.mdc deleted file mode 100644 index f3bbc6ee6669..000000000000 --- a/.cursor/rules/sdk_development.mdc +++ /dev/null @@ -1,209 +0,0 @@ ---- -description: Guidelines for working on the Sentry JavaScript SDK monorepo -alwaysApply: true ---- - -# SDK Development Rules - -You are working on the Sentry JavaScript SDK, a critical production SDK used by thousands of applications. Follow these rules strictly. - -## Code Quality Requirements (MANDATORY) - -**CRITICAL**: All changes must pass these checks before committing: - -1. **Always run `yarn lint`** - Fix all linting issues -2. **Always run `yarn test`** - Ensure all tests pass -3. **Always run `yarn build:dev`** - Verify TypeScript compilation - -## Development Commands - -### Build Commands - -- `yarn build` - Full production build with package verification -- `yarn build:dev` - Development build (transpile + types) -- `yarn build:dev:watch` - Development build in watch mode (recommended) -- `yarn build:dev:filter ` - Build specific package and dependencies -- `yarn build:bundle` - Build browser bundles only - -### Testing - -- `yarn test` - Run all unit tests - -### Linting and Formatting - -- `yarn lint` - Run ESLint and Prettier checks -- `yarn fix` - Auto-fix linting and formatting issues -- `yarn format:check` - Check file formatting only -- `yarn format` - Auto-fix formatting issues -- `yarn lint:es-compatibility` - Check ES compatibility - -## Git Flow Branching Strategy - -This repository uses **Git Flow**. See [docs/gitflow.md](docs/gitflow.md) for details. - -### Key Rules - -- **All PRs target `develop` branch** (NOT `master`) -- `master` represents the last released state -- Never merge directly into `master` (except emergency fixes) -- Avoid changing `package.json` files on `develop` during pending releases -- Never update dependencies, package.json content or build scripts unless explicitly asked for -- When asked to do a task on a set of files, always make sure that all occurences in the codebase are covered. Double check that no files have been forgotten. -- Unless explicitly asked for, make sure to cover all files, including files in `src/` and `test/` directories. - -### Branch Naming - -- Features: `feat/descriptive-name` -- Releases: `release/X.Y.Z` - -## Repository Architecture - -This is a monorepo with 40+ packages in the `@sentry/*` namespace, managed with Yarn workspaces and Nx. - -### Core Packages - -- `packages/core/` - Base SDK with interfaces, type definitions, core functionality -- `packages/types/` - Shared TypeScript type definitions - this is deprecated, never modify this package -- `packages/browser-utils/` - Browser-specific utilities and instrumentation -- `packages/node-core/` - Node Core SDK which contains most of the node-specific logic, excluding OpenTelemetry instrumentation. - -### Platform SDKs - -- `packages/browser/` - Browser SDK with bundled variants -- `packages/node/` - Node.js SDK. All general Node code should go into node-core, the node package itself only contains OpenTelemetry instrumentation on top of that. -- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` - Runtime-specific SDKs - -### Framework Integrations - -- Framework packages: `packages/{framework}/` (react, vue, angular, etc.) -- Client/server entry points where applicable (nextjs, nuxt, sveltekit) -- Integration tests use Playwright (Remix, browser-integration-tests) - -### AI Integrations - -- `packages/core/src/tracing/{provider}/` - Core instrumentation logic (OpenAI, Anthropic, Vercel AI, LangChain, etc.) -- `packages/node/src/integrations/tracing/{provider}/` - Node.js-specific integration + OTel instrumentation -- `packages/cloudflare/src/integrations/tracing/{provider}.ts` - Edge runtime support -- Patterns: OTEL Span Processors, Client Wrapping, Callback/Hook Based -- See `.cursor/rules/adding-a-new-ai-integration.mdc` for implementation guide - -### User Experience Packages - -- `packages/replay-internal/` - Session replay functionality -- `packages/replay-canvas/` - Canvas recording for replay -- `packages/replay-worker/` - Web worker support for replay -- `packages/feedback/` - User feedback integration - -### Development Packages (`dev-packages/`) - -- `browser-integration-tests/` - Playwright browser tests -- `e2e-tests/` - End-to-end tests for 70+ framework combinations -- `node-integration-tests/` - Node.js integration tests -- `test-utils/` - Shared testing utilities -- `bundle-analyzer-scenarios/` - Bundle analysis -- `rollup-utils/` - Build utilities -- GitHub Actions packages for CI/CD automation - -## Development Guidelines - -### Build System - -- Uses Rollup for bundling (`rollup.*.config.mjs`) -- TypeScript with multiple tsconfig files per package -- Nx orchestrates task execution across packages with caching -- Vite for testing with `vitest` - -### Package Structure Pattern - -Each package typically contains: - -- `src/index.ts` - Main entry point -- `src/sdk.ts` - SDK initialization logic -- `rollup.npm.config.mjs` - Build configuration -- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` -- `test/` directory with corresponding test files - -### Key Development Notes - -- Uses Volta for Node.js/Yarn version management -- Requires initial `yarn build` after `yarn install` for TypeScript linking -- Integration tests use Playwright extensively -- Never change the volta, yarn, or package manager setup in general unless explicitly asked for - -### E2E Testing - -E2E tests are located in `dev-packages/e2e-tests/` and verify SDK behavior in real-world framework scenarios. - -#### How Verdaccio Registry Works - -E2E tests use [Verdaccio](https://verdaccio.org/), a lightweight npm registry running in Docker. Before tests run: - -1. SDK packages are built and packed into tarballs (`yarn build && yarn build:tarball`) -2. Tarballs are published to Verdaccio at `http://127.0.0.1:4873` -3. Test applications install packages from Verdaccio instead of public npm - -#### The `.npmrc` Requirement - -Every E2E test application needs an `.npmrc` file with: - -``` -@sentry:registry=http://127.0.0.1:4873 -@sentry-internal:registry=http://127.0.0.1:4873 -``` - -Without this file, pnpm installs from the public npm registry instead of Verdaccio, so your local changes won't be tested. This is a common cause of "tests pass in CI but fail locally" or vice versa. - -#### Running a Single E2E Test - -```bash -# Build packages first -yarn build && yarn build:tarball - -# Run a specific test app -cd dev-packages/e2e-tests -yarn test:run - -# Run with a specific variant (e.g., Next.js 15) -yarn test:run --variant -``` - -#### Common Pitfalls and Debugging - -1. **Missing `.npmrc`**: Most common issue. Always verify the test app has the correct `.npmrc` file. - -2. **Stale tarballs**: After SDK changes, must re-run `yarn build:tarball`. - -3. **Debugging tips**: - - Check browser console logs for SDK initialization errors - - Use `debug: true` in Sentry config - - Verify installed package version: check `node_modules/@sentry/*/package.json` - -### Notes for Background Tasks - -- Make sure to use [volta](https://volta.sh/) for development. Volta is used to manage the node, yarn and pnpm version used. -- Make sure that [PNPM support is enabled in volta](https://docs.volta.sh/advanced/pnpm). This means that the `VOLTA_FEATURE_PNPM` environment variable has to be set to `1`. -- Yarn, Node and PNPM have to be used through volta, in the versions defined by the volta config. NEVER change any versions unless explicitly asked to. - -## Testing Single Packages - -- Test specific package: `cd packages/{package-name} && yarn test` -- Build specific package: `yarn build:dev:filter @sentry/{package-name}` - -## Code Style Rules - -- Follow existing code conventions in each package -- Check imports and dependencies - only use libraries already in the codebase -- Look at neighboring files for patterns and style -- Never introduce code that exposes secrets or keys -- Follow security best practices - -## Before Every Commit Checklist - -1. ✅ `yarn lint` (fix all issues) -2. ✅ `yarn test` (all tests pass) -3. ✅ `yarn build:dev` (builds successfully) -4. ✅ Target `develop` branch for PRs (not `master`) - -## Documentation Sync - -**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..f22698f28f7f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,134 @@ +# Sentry JavaScript SDK + +This is the official Sentry JavaScript SDK monorepo — a critical production SDK used by thousands of applications. It contains 40+ packages in the `@sentry/*` namespace, managed with Yarn workspaces and Nx. + +## Setup + +- Uses [Volta](https://volta.sh/) for Node.js/Yarn/PNPM version management +- Requires `VOLTA_FEATURE_PNPM=1` environment variable for PNPM support +- After cloning: `yarn install && yarn build` (initial build required for TypeScript linking) +- Never change Volta, Yarn, or package manager versions unless explicitly asked + +## Build & Test Commands + +- `yarn build` — Full production build with package verification +- `yarn build:dev` — Development build (transpile + types) +- `yarn build:dev:filter @sentry/` — Build specific package and dependencies +- `yarn build:bundle` — Build browser bundles only +- `yarn test` — Run all unit tests +- `yarn lint` — Run ESLint and Oxfmt checks +- `yarn fix` — Auto-fix linting and formatting issues +- `yarn format` — Auto-fix formatting with Oxfmt + +### Testing a Single Package + +```bash +cd packages/ && yarn test +yarn build:dev:filter @sentry/ +``` + +### E2E Testing + +E2E tests live in `dev-packages/e2e-tests/` and use [Verdaccio](https://verdaccio.org/) (local npm registry in Docker). Every test application needs an `.npmrc` file: + +``` +@sentry:registry=http://127.0.0.1:4873 +@sentry-internal:registry=http://127.0.0.1:4873 +``` + +```bash +yarn build && yarn build:tarball # Build and pack tarballs +cd dev-packages/e2e-tests +yarn test:run # Run a specific test app +``` + +Common pitfalls: missing `.npmrc` (most common), stale tarballs (re-run `yarn build:tarball` after changes). + +To run E2E tests, prefer using the `/e2e` skill which handles building and running automatically. + +## Architecture + +### Core Packages + +- `packages/core/` — Base SDK: interfaces, type definitions, core functionality +- `packages/types/` — Shared TypeScript types (**deprecated — never modify**) +- `packages/browser-utils/` — Browser-specific utilities and instrumentation +- `packages/node-core/` — Node core logic (excluding OpenTelemetry instrumentation) + +### Platform SDKs + +- `packages/browser/` — Browser SDK with CDN bundle variants +- `packages/node/` — Node.js SDK (OpenTelemetry instrumentation on top of node-core; general Node code goes in node-core) +- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` — Runtime-specific SDKs + +### Framework Integrations + +- `packages/{framework}/` — React, Vue, Angular, Next.js, Nuxt, SvelteKit, Remix, etc. +- Some have client/server entry points (nextjs, nuxt, sveltekit) + +### AI Integrations + +- `packages/core/src/tracing/{provider}/` — Core instrumentation logic (OpenAI, Anthropic, Vercel AI, LangChain, etc.) +- `packages/node/src/integrations/tracing/{provider}/` — Node.js-specific integration + OTel instrumentation +- `packages/cloudflare/src/integrations/tracing/{provider}.ts` — Edge runtime support +- Patterns: OTEL Span Processors, Client Wrapping, Callback/Hook Based + +### User Experience Packages + +- `packages/replay-internal/` — Session replay +- `packages/replay-canvas/` — Canvas recording for replay +- `packages/replay-worker/` — Web worker support for replay +- `packages/feedback/` — User feedback integration + +### Development Packages (`dev-packages/`) + +- `browser-integration-tests/` — Playwright browser tests +- `e2e-tests/` — E2E tests for 70+ framework combinations +- `node-integration-tests/` — Node.js integration tests +- `test-utils/` — Shared testing utilities +- `rollup-utils/` — Build utilities + +### Package Structure Pattern + +Each package typically contains: + +- `src/index.ts` — Main entry point +- `src/sdk.ts` — SDK initialization logic +- `rollup.npm.config.mjs` — Build configuration +- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` +- `test/` directory with corresponding test files + +## Build System + +- Rollup for bundling (`rollup.*.config.mjs`) +- TypeScript with multiple tsconfig files per package +- Nx for task orchestration and caching +- Vitest for unit testing + +## Git Workflow + +This repository uses **Git Flow** (see `docs/gitflow.md`). + +- **All PRs target the `develop` branch** (NOT `master`) +- `master` represents the last released state — never merge directly into it +- Feature branches: `feat/descriptive-name` +- Release branches: `release/X.Y.Z` +- Avoid changing `package.json` on `develop` during pending releases +- Never update dependencies, `package.json` content, or build scripts unless explicitly asked + +## Coding Standards + +- Follow existing code conventions in each package +- Check imports and dependencies — only use libraries already in the codebase +- Look at neighboring files for patterns and style +- Never introduce code that exposes secrets or keys +- When modifying a set of files, ensure all occurrences in the codebase are covered (including `src/` and `test/` directories) + +## Before Every Commit + +1. `yarn format` — fix formatting +2. `yarn lint` — fix linting +3. `yarn test` — all tests pass +4. `yarn build:dev` — builds successfully +5. NEVER push on develop +6. Target `develop` branch for PRs diff --git a/CLAUDE.md b/CLAUDE.md index 8f16ed4ff986..9cc16c4971f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,190 +1,9 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +This file provides guidance to Claude Code when working with this repository. -# SDK Development Rules +## SDK Development Rules -You are working on the Sentry JavaScript SDK, a critical production SDK used by thousands of applications. Follow these rules strictly. +@AGENTS.md -## Code Quality Requirements (MANDATORY) - -**CRITICAL**: All changes must pass these checks before committing: - -1. **Always run `yarn lint`** - Fix all linting issues -2. **Always run `yarn test`** - Ensure all tests pass -3. **Always run `yarn build:dev`** - Verify TypeScript compilation - -## Development Commands - -### Build Commands - -- `yarn build` - Full production build with package verification -- `yarn build:dev` - Development build (transpile + types) -- `yarn build:dev:watch` - Development build in watch mode (recommended) -- `yarn build:dev:filter ` - Build specific package and dependencies -- `yarn build:bundle` - Build browser bundles only - -### Testing - -- `yarn test` - Run all unit tests - -### Linting and Formatting - -- `yarn lint` - Run ESLint and Oxfmt checks -- `yarn fix` - Auto-fix linting and formatting issues -- `yarn format:check` - Check file formatting only -- `yarn format` - Auto-fix formatting issues -- `yarn lint:es-compatibility` - Check ES compatibility - -## Git Flow Branching Strategy - -This repository uses **Git Flow**. See [docs/gitflow.md](docs/gitflow.md) for details. - -### Key Rules - -- **All PRs target `develop` branch** (NOT `master`) -- `master` represents the last released state -- Never merge directly into `master` (except emergency fixes) -- Avoid changing `package.json` files on `develop` during pending releases -- Never update dependencies, package.json content or build scripts unless explicitly asked for -- When asked to do a task on a set of files, always make sure that all occurences in the codebase are covered. Double check that no files have been forgotten. -- Unless explicitly asked for, make sure to cover all files, including files in `src/` and `test/` directories. - -### Branch Naming - -- Features: `feat/descriptive-name` -- Releases: `release/X.Y.Z` - -## Repository Architecture - -This is a monorepo with 40+ packages in the `@sentry/*` namespace, managed with Yarn workspaces and Nx. - -### Core Packages - -- `packages/core/` - Base SDK with interfaces, type definitions, core functionality -- `packages/types/` - Shared TypeScript type definitions - this is deprecated, never modify this package -- `packages/browser-utils/` - Browser-specific utilities and instrumentation -- `packages/node-core/` - Node Core SDK which contains most of the node-specific logic, excluding OpenTelemetry instrumentation. - -### Platform SDKs - -- `packages/browser/` - Browser SDK with bundled variants -- `packages/node/` - Node.js SDK. All general Node code should go into node-core, the node package itself only contains OpenTelemetry instrumentation on top of that. -- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` - Runtime-specific SDKs - -### Framework Integrations - -- Framework packages: `packages/{framework}/` (react, vue, angular, etc.) -- Client/server entry points where applicable (nextjs, nuxt, sveltekit) -- Integration tests use Playwright (Remix, browser-integration-tests) - -### User Experience Packages - -- `packages/replay-internal/` - Session replay functionality -- `packages/replay-canvas/` - Canvas recording for replay -- `packages/replay-worker/` - Web worker support for replay -- `packages/feedback/` - User feedback integration - -### Development Packages (`dev-packages/`) - -- `browser-integration-tests/` - Playwright browser tests -- `e2e-tests/` - End-to-end tests for 70+ framework combinations -- `node-integration-tests/` - Node.js integration tests -- `test-utils/` - Shared testing utilities -- `bundle-analyzer-scenarios/` - Bundle analysis -- `rollup-utils/` - Build utilities -- GitHub Actions packages for CI/CD automation - -## Development Guidelines - -### Build System - -- Uses Rollup for bundling (`rollup.*.config.mjs`) -- TypeScript with multiple tsconfig files per package -- Nx orchestrates task execution across packages with caching -- Vite for testing with `vitest` - -### Package Structure Pattern - -Each package typically contains: - -- `src/index.ts` - Main entry point -- `src/sdk.ts` - SDK initialization logic -- `rollup.npm.config.mjs` - Build configuration -- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` -- `test/` directory with corresponding test files - -### Key Development Notes - -- Uses Volta for Node.js/Yarn version management -- Requires initial `yarn build` after `yarn install` for TypeScript linking -- Integration tests use Playwright extensively -- Never change the volta, yarn, or package manager setup in general unless explicitly asked for - -### E2E Testing - -E2E tests are located in `dev-packages/e2e-tests/` and verify SDK behavior in real-world framework scenarios. - -#### How Verdaccio Registry Works - -E2E tests use [Verdaccio](https://verdaccio.org/), a lightweight npm registry running in Docker. Before tests run: - -1. SDK packages are built and packed into tarballs (`yarn build && yarn build:tarball`) -2. Tarballs are published to Verdaccio at `http://127.0.0.1:4873` -3. Test applications install packages from Verdaccio instead of public npm - -#### The `.npmrc` Requirement - -Every E2E test application needs an `.npmrc` file with: - -``` -@sentry:registry=http://127.0.0.1:4873 -@sentry-internal:registry=http://127.0.0.1:4873 -``` - -Without this file, pnpm installs from the public npm registry instead of Verdaccio, so your local changes won't be tested. This is a common cause of "tests pass in CI but fail locally" or vice versa. - -#### Running a Single E2E Test - -Run the e2e skill. - -#### Common Pitfalls and Debugging - -1. **Missing `.npmrc`**: Most common issue. Always verify the test app has the correct `.npmrc` file. - -2. **Stale tarballs**: After SDK changes, must re-run `yarn build:tarball`. - -3. **Debugging tips**: - - Check browser console logs for SDK initialization errors - - Use `debug: true` in Sentry config - - Verify installed package version: check `node_modules/@sentry/*/package.json` - -### Notes for Background Tasks - -- Make sure to use [volta](https://volta.sh/) for development. Volta is used to manage the node, yarn and pnpm version used. -- Make sure that [PNPM support is enabled in volta](https://docs.volta.sh/advanced/pnpm). This means that the `VOLTA_FEATURE_PNPM` environment variable has to be set to `1`. -- Yarn, Node and PNPM have to be used through volta, in the versions defined by the volta config. NEVER change any versions unless explicitly asked to. - -## Testing Single Packages - -- Test specific package: `cd packages/{package-name} && yarn test` -- Build specific package: `yarn build:dev:filter @sentry/{package-name}` - -## Code Style Rules - -- Follow existing code conventions in each package -- Check imports and dependencies - only use libraries already in the codebase -- Look at neighboring files for patterns and style -- Never introduce code that exposes secrets or keys -- Follow security best practices - -## Before Every Commit Checklist - -1. ✅ `yarn lint` (fix all issues) -2. ✅ `yarn test` (all tests pass) -3. ✅ `yarn build:dev` (builds successfully) -4. ✅ Target `develop` branch for PRs (not `master`) - -## Documentation Sync - -**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync. +**IMPORTANT**: `AGENTS.md` is the single source of truth for SDK development rules. Only add Claude-specific instructions here. From a36c64d0b55d42fab7f681ed9b36b9294baa3c27 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 25 Feb 2026 15:50:44 +0100 Subject: [PATCH 2/5] clanker knows best --- AGENTS.md | 150 ++++++++++++++++++++++++------------------------------ CLAUDE.md | 10 +--- 2 files changed, 67 insertions(+), 93 deletions(-) mode change 100644 => 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index f22698f28f7f..2f3145860cba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,65 +1,69 @@ # Sentry JavaScript SDK -This is the official Sentry JavaScript SDK monorepo — a critical production SDK used by thousands of applications. It contains 40+ packages in the `@sentry/*` namespace, managed with Yarn workspaces and Nx. +Monorepo with 40+ packages in `@sentry/*`, managed with Yarn workspaces and Nx. ## Setup -- Uses [Volta](https://volta.sh/) for Node.js/Yarn/PNPM version management -- Requires `VOLTA_FEATURE_PNPM=1` environment variable for PNPM support -- After cloning: `yarn install && yarn build` (initial build required for TypeScript linking) +- [Volta](https://volta.sh/) for Node.js/Yarn/PNPM version management +- Requires `VOLTA_FEATURE_PNPM=1` +- After cloning: `yarn install && yarn build` - Never change Volta, Yarn, or package manager versions unless explicitly asked -## Build & Test Commands +## Package Manager -- `yarn build` — Full production build with package verification -- `yarn build:dev` — Development build (transpile + types) -- `yarn build:dev:filter @sentry/` — Build specific package and dependencies -- `yarn build:bundle` — Build browser bundles only -- `yarn test` — Run all unit tests -- `yarn lint` — Run ESLint and Oxfmt checks -- `yarn fix` — Auto-fix linting and formatting issues -- `yarn format` — Auto-fix formatting with Oxfmt +Use **yarn**: `yarn install`, `yarn build`, `yarn test`, `yarn lint` -### Testing a Single Package +| Command | Purpose | +|---------|---------| +| `yarn build` | Full production build | +| `yarn build:dev` | Dev build (transpile + types) | +| `yarn build:dev:filter @sentry/` | Build one package + deps | +| `yarn build:bundle` | Browser bundles only | +| `yarn test` | All unit tests | +| `yarn lint` | ESLint + Oxfmt | +| `yarn fix` | Auto-fix lint + format | +| `yarn format` | Auto-fix formatting (Oxfmt) | -```bash -cd packages/ && yarn test -yarn build:dev:filter @sentry/ -``` - -### E2E Testing +Single package: `cd packages/ && yarn test` -E2E tests live in `dev-packages/e2e-tests/` and use [Verdaccio](https://verdaccio.org/) (local npm registry in Docker). Every test application needs an `.npmrc` file: +## Commit Attribution +AI commits MUST include: ``` -@sentry:registry=http://127.0.0.1:4873 -@sentry-internal:registry=http://127.0.0.1:4873 +Co-Authored-By: ``` -```bash -yarn build && yarn build:tarball # Build and pack tarballs -cd dev-packages/e2e-tests -yarn test:run # Run a specific test app -``` +## Git Workflow + +Uses **Git Flow** (see `docs/gitflow.md`). + +- **All PRs target `develop`** (NOT `master`) +- `master` = last released state — never merge directly +- Feature branches: `feat/descriptive-name` +- Never update dependencies, `package.json`, or build scripts unless explicitly asked -Common pitfalls: missing `.npmrc` (most common), stale tarballs (re-run `yarn build:tarball` after changes). +## Before Every Commit -To run E2E tests, prefer using the `/e2e` skill which handles building and running automatically. +1. `yarn format` +2. `yarn lint` +3. `yarn test` +4. `yarn build:dev` +5. NEVER push on `develop` ## Architecture -### Core Packages +### Core -- `packages/core/` — Base SDK: interfaces, type definitions, core functionality -- `packages/types/` — Shared TypeScript types (**deprecated — never modify**) -- `packages/browser-utils/` — Browser-specific utilities and instrumentation -- `packages/node-core/` — Node core logic (excluding OpenTelemetry instrumentation) +- `packages/core/` — Base SDK: interfaces, types, core functionality +- `packages/types/` — Shared types (**deprecated — never modify**) +- `packages/browser-utils/` — Browser utilities and instrumentation +- `packages/node-core/` — Node core logic (excludes OTel instrumentation) ### Platform SDKs -- `packages/browser/` — Browser SDK with CDN bundle variants -- `packages/node/` — Node.js SDK (OpenTelemetry instrumentation on top of node-core; general Node code goes in node-core) -- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` — Runtime-specific SDKs +- `packages/browser/` — Browser SDK + CDN bundles +- `packages/node/` — Node.js SDK (OTel instrumentation on top of node-core) +- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` ### Framework Integrations @@ -68,67 +72,45 @@ To run E2E tests, prefer using the `/e2e` skill which handles building and runni ### AI Integrations -- `packages/core/src/tracing/{provider}/` — Core instrumentation logic (OpenAI, Anthropic, Vercel AI, LangChain, etc.) -- `packages/node/src/integrations/tracing/{provider}/` — Node.js-specific integration + OTel instrumentation -- `packages/cloudflare/src/integrations/tracing/{provider}.ts` — Edge runtime support -- Patterns: OTEL Span Processors, Client Wrapping, Callback/Hook Based +- `packages/core/src/tracing/{provider}/` — Core instrumentation +- `packages/node/src/integrations/tracing/{provider}/` — Node.js integration + OTel +- `packages/cloudflare/src/integrations/tracing/{provider}.ts` — Edge runtime +- See `.cursor/rules/adding-a-new-ai-integration.mdc` for implementation guide -### User Experience Packages +### User Experience -- `packages/replay-internal/` — Session replay -- `packages/replay-canvas/` — Canvas recording for replay -- `packages/replay-worker/` — Web worker support for replay -- `packages/feedback/` — User feedback integration +- `packages/replay-internal/`, `packages/replay-canvas/`, `packages/replay-worker/` — Session replay +- `packages/feedback/` — User feedback -### Development Packages (`dev-packages/`) +### Dev Packages (`dev-packages/`) - `browser-integration-tests/` — Playwright browser tests -- `e2e-tests/` — E2E tests for 70+ framework combinations +- `e2e-tests/` — E2E tests (70+ framework combos) - `node-integration-tests/` — Node.js integration tests -- `test-utils/` — Shared testing utilities +- `test-utils/` — Shared test utilities - `rollup-utils/` — Build utilities -### Package Structure Pattern - -Each package typically contains: +## Coding Standards -- `src/index.ts` — Main entry point -- `src/sdk.ts` — SDK initialization logic -- `rollup.npm.config.mjs` — Build configuration -- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` -- `test/` directory with corresponding test files +- Follow existing conventions — check neighboring files +- Only use libraries already in the codebase +- Never expose secrets or keys +- When modifying files, cover all occurrences (including `src/` and `test/`) -## Build System +## Skills -- Rollup for bundling (`rollup.*.config.mjs`) -- TypeScript with multiple tsconfig files per package -- Nx for task orchestration and caching -- Vitest for unit testing +### E2E Testing -## Git Workflow +Use `/e2e` skill to run E2E tests. See `.claude/skills/e2e/SKILL.md` -This repository uses **Git Flow** (see `docs/gitflow.md`). +### Security Vulnerabilities -- **All PRs target the `develop` branch** (NOT `master`) -- `master` represents the last released state — never merge directly into it -- Feature branches: `feat/descriptive-name` -- Release branches: `release/X.Y.Z` -- Avoid changing `package.json` on `develop` during pending releases -- Never update dependencies, `package.json` content, or build scripts unless explicitly asked +Use `/fix-security-vulnerability` skill for Dependabot alerts. See `.claude/skills/fix-security-vulnerability/SKILL.md` -## Coding Standards +### Issue Triage -- Follow existing code conventions in each package -- Check imports and dependencies — only use libraries already in the codebase -- Look at neighboring files for patterns and style -- Never introduce code that exposes secrets or keys -- When modifying a set of files, ensure all occurrences in the codebase are covered (including `src/` and `test/` directories) +Use `/triage-issue` skill. See `.claude/skills/triage-issue/SKILL.md` -## Before Every Commit +### CDN Bundles -1. `yarn format` — fix formatting -2. `yarn lint` — fix linting -3. `yarn test` — all tests pass -4. `yarn build:dev` — builds successfully -5. NEVER push on develop -6. Target `develop` branch for PRs +Use `/add-cdn-bundle` skill. See `.claude/skills/add-cdn-bundle/SKILL.md` diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9cc16c4971f1..000000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code when working with this repository. - -## SDK Development Rules - -@AGENTS.md - -**IMPORTANT**: `AGENTS.md` is the single source of truth for SDK development rules. Only add Claude-specific instructions here. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000000..47dc3e3d863c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From d4d029319b0e203f5d7a3fd0331d7358146b9409 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 25 Feb 2026 15:55:47 +0100 Subject: [PATCH 3/5] .. --- AGENTS.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2f3145860cba..8c990d4f1658 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,22 +13,23 @@ Monorepo with 40+ packages in `@sentry/*`, managed with Yarn workspaces and Nx. Use **yarn**: `yarn install`, `yarn build`, `yarn test`, `yarn lint` -| Command | Purpose | -|---------|---------| -| `yarn build` | Full production build | -| `yarn build:dev` | Dev build (transpile + types) | -| `yarn build:dev:filter @sentry/` | Build one package + deps | -| `yarn build:bundle` | Browser bundles only | -| `yarn test` | All unit tests | -| `yarn lint` | ESLint + Oxfmt | -| `yarn fix` | Auto-fix lint + format | -| `yarn format` | Auto-fix formatting (Oxfmt) | +| Command | Purpose | +| ------------------------------------- | ----------------------------- | +| `yarn build` | Full production build | +| `yarn build:dev` | Dev build (transpile + types) | +| `yarn build:dev:filter @sentry/` | Build one package + deps | +| `yarn build:bundle` | Browser bundles only | +| `yarn test` | All unit tests | +| `yarn lint` | ESLint + Oxfmt | +| `yarn fix` | Auto-fix lint + format | +| `yarn format` | Auto-fix formatting (Oxfmt) | Single package: `cd packages/ && yarn test` ## Commit Attribution AI commits MUST include: + ``` Co-Authored-By: ``` From 9a29a0532061d2f0c734e55488a4c72fd6c8cb91 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Thu, 26 Feb 2026 10:08:53 +0100 Subject: [PATCH 4/5] Update AGENTS.md Co-authored-by: Sigrid <32902192+s1gr1d@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 8c990d4f1658..9ccede4dcee4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Monorepo with 40+ packages in `@sentry/*`, managed with Yarn workspaces and Nx. ## Package Manager -Use **yarn**: `yarn install`, `yarn build`, `yarn test`, `yarn lint` +Use **yarn**: `yarn install`, `yarn build:dev`, `yarn test`, `yarn lint` | Command | Purpose | | ------------------------------------- | ----------------------------- | From 41df2c40e89dae7c7b4d8f2251293275ab243d1d Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Thu, 26 Feb 2026 10:17:13 +0100 Subject: [PATCH 5/5] types --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9ccede4dcee4..42269f6abd6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,7 @@ Uses **Git Flow** (see `docs/gitflow.md`). ### Core - `packages/core/` — Base SDK: interfaces, types, core functionality -- `packages/types/` — Shared types (**deprecated — never modify**) +- `packages/types/` — Shared types (**deprecated, never modify – instead find types in packages/core**) - `packages/browser-utils/` — Browser utilities and instrumentation - `packages/node-core/` — Node core logic (excludes OTel instrumentation)