From 03949b6e45b236816741ff360d48ceb670e155d6 Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Tue, 11 Aug 2026 11:51:19 +0200 Subject: [PATCH 1/4] docs(agents): Remove duplicated agent rule files coding.mdc was almost entirely a subset of AGENTS.md: the contributing guidelines, coding rules, useful resources, and key commands sections were near-verbatim copies. overview_dev.mdc re-described every rule three times (once per rule bullet list, once in a keyword table) even though each rule file already carries the same information in its frontmatter description, and it pointed agents at fetch_rules, a Cursor-only tool. Reduce coding.mdc to a pointer, delete overview_dev.mdc, and move the rule index into AGENTS.md as a single table. Agents now read one file to get started instead of three. --- .cursor/rules/coding.mdc | 49 +----------- .cursor/rules/overview_dev.mdc | 133 --------------------------------- AGENTS.md | 33 +++++--- CLAUDE.md | 7 +- 4 files changed, 30 insertions(+), 192 deletions(-) delete mode 100644 .cursor/rules/overview_dev.mdc diff --git a/.cursor/rules/coding.mdc b/.cursor/rules/coding.mdc index 70ac39e43a2..36276800f1d 100644 --- a/.cursor/rules/coding.mdc +++ b/.cursor/rules/coding.mdc @@ -5,49 +5,6 @@ description: Cursor Coding Rules # Contributing Rules for Agents -## Overview - -sentry-java is the Java and Android SDK for Sentry. This repository contains the source code and examples for SDK usage. - -## Tech Stack - -- **Language**: Java and Kotlin -- **Build Framework**: Gradle - -## Key Commands - -```bash -# Format code and regenerate .api files -./gradlew spotlessApply apiDump - -# Run all tests and linter -./gradlew check - -# Run unit tests for a specific file -./gradlew '::testReleaseUnitTest' --tests="**" --info -``` - -## Contributing Guidelines - -1. Follow existing code style and language -2. Do not modify the API files (e.g. sentry.api) manually, instead run `./gradlew apiDump` to regenerate them -3. Write comprehensive tests. For assertions in new unit tests, prefer Google Truth (`com.google.common.truth.Truth.assertThat`) over `kotlin.test`/JUnit assertions; keep `kotlin.test` for test structure like `@Test` and `assertFailsWith`. Add `testImplementation(libs.google.truth)` to a module's `build.gradle.kts` if it isn't already present. -4. New features should always be opt-in by default, extend `SentryOptions` or similar Option classes with getters and setters to enable/disable a new feature -5. Consider backwards compatibility - -## Coding rules - -1. First think through the problem, read the codebase for relevant files, and propose a plan -2. Before you begin working, check in with me and I will verify the plan -3. Then, begin working on the todo items, marking them as complete as you go -4. Please do not describe every step of the way and just give me a high level explanation of what changes you made -5. Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity. -6. Once you're done, format the code and regenerate the .api files using the following command `./gradlew spotlessApply apiDump` -7. As a last step, git stage the relevant files and propose (but not execute) a single git commit command (e.g. `git commit -m ""`) - - -## Useful Resources - -- Main SDK documentation: https://develop.sentry.dev/sdk/overview/ -- Internal contributing guide: https://docs.sentry.io/internal/contributing/ -- Git commit messages conventions: https://develop.sentry.dev/engineering-practices/commit-messages/ +Read [AGENTS.md](../../AGENTS.md) in the repository root. It is the single source of +truth for build commands, contributing guidelines, workflow rules, and the index of +the domain-specific rules in this directory. diff --git a/.cursor/rules/overview_dev.mdc b/.cursor/rules/overview_dev.mdc deleted file mode 100644 index b837be34add..00000000000 --- a/.cursor/rules/overview_dev.mdc +++ /dev/null @@ -1,133 +0,0 @@ ---- -alwaysApply: true -description: Sentry Java SDK - Development Rules Overview ---- - -# Sentry Java SDK Development Rules - -## Always Applied Rules - -These rules are automatically included in every conversation: -- **coding.mdc**: General contributing guidelines, build commands, and workflow rules - -## Domain-Specific Rules (Fetch Only When Needed) - -Use the `fetch_rules` tool to include these rules when working on specific areas: - -### Core SDK Functionality -- **`api`**: Use when working with: - - Adding or modifying public API surface - - Binary compatibility, `.api` files, `apiDump` - - Understanding which classes to modify for new API (interfaces, implementations, no-ops, adapters) - - `IScope`, `IScopes`, `Sentry` static API - - Attributes, logging API, protocol classes - -- **`options`**: Use when working with: - - Adding or modifying SDK options (`SentryOptions`, namespaced options) - - External options (`ExternalOptions`, `sentry.properties`, environment variables) - - Android manifest metadata (`ManifestMetadataReader`) - - Spring Boot properties (`SentryProperties`) - -- **`scopes`**: Use when working with: - - Hub/Scope management, forking, or lifecycle - - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()` - - `ScopeType` (GLOBAL, ISOLATION, CURRENT) - - Thread-local storage, scope bleeding issues - - Migration from Hub API (v7 → v8) - -- **`deduplication`**: Use when working with: - - Duplicate event detection/prevention - - `DuplicateEventDetectionEventProcessor` - - `enableDeduplication` option - -- **`offline`**: Use when working with: - - Caching, envelope storage/retrieval - - Network failure handling, retry logic - - `AsyncHttpTransport`, `EnvelopeCache` - - Rate limiting, cache rotation - - Android vs JVM caching differences - -- **`feature_flags`**: Use when working with: - - Feature flag tracking and evaluation - - `addFeatureFlag()`, `getFeatureFlags()` methods - - `FeatureFlagBuffer`, `SpanFeatureFlagBuffer`, `FeatureFlag` protocol - - `maxFeatureFlags` option and buffer management - - Feature flag merging across scope types - - Scope-based vs span-based feature flag APIs - - Scope-based API: `Sentry`, `IScopes`, `IScope` APIs - - Span-based API: `ISpan`, `ITransaction` APIs - - Integrations: LaunchDarkly (Android/JVM), OpenFeature (JVM) - -- **`metrics`**: Use when working with: - - Metrics API (`Sentry.metrics()`, `IScopes.metrics()`) - - `IMetricsApi`, `MetricsApi` implementation - - Metrics types: `count`, `distribution`, `gauge` - - `MetricsBatchProcessor`, batching and queue management - - `SentryMetricsEvent`, `SentryMetricsEvents` - - `SentryOptions.getMetrics()`, `beforeSend` callback - -- **`queues`**: Use when working with: - - Sentry Queues product data or messaging span conventions - - Queue tracing spans/transactions (`queue.publish`, `queue.process`) - - `enableQueueTracing` option and `sentry.enable-queue-tracing` - - Kafka instrumentation (`sentry-kafka`, `SentryKafkaProducer`, `SentryKafkaConsumerTracing`) - - Spring Kafka queue auto-instrumentation and `SentryKafkaRecordInterceptor` - - Messaging span data (`messaging.system`, `messaging.destination.name`, receive latency, retry count) - - `sentry-task-enqueued-time` header and distributed trace propagation through queues - -- **`continuous_profiling_jvm`**: Use when working with: - - JVM continuous profiling (`sentry-async-profiler` module) - - `IContinuousProfiler`, `JavaContinuousProfiler` - - `ProfileChunk`, chunk rotation, JFR file handling - - `ProfileLifecycle` (MANUAL vs TRACE modes) - - async-profiler integration, ServiceLoader discovery - - Rate limiting, offline caching, scopes integration - -- **Android profiling**: There is currently no dedicated rule for this area yet. - - Inspect the relevant `sentry-android-core` profiling code directly - - Fetch other related rules as needed (for example `options`, `offline`, or `api`) - -### Integration & Infrastructure -- **`opentelemetry`**: Use when working with: - - OpenTelemetry modules (`sentry-opentelemetry-*`) - - Agent vs agentless configurations - - Span processing, sampling, context propagation - - `OtelSpanFactory`, `SentrySpanExporter` - - Tracing, distributed tracing - -- **`new_module`**: Use when adding a new integration or sample module - -### Workflow -- **`pr`**: Use when working with: - - Creating pull requests - - Stacked PRs, PR naming, stack comments - - PR changelog entries - - Merging or syncing stacked branches - -### Testing -- **`e2e_tests`**: Use when working with: - - System tests, sample applications - - `system-test-runner.py`, mock Sentry server - - End-to-end test infrastructure - - CI system test workflows - -## Usage Guidelines - -1. **Start minimal**: Only include `coding.mdc` (auto-applied) for general tasks -2. **Fetch on-demand**: Use `fetch_rules ["rule_name"]` when you identify specific domain work -3. **Multiple rules**: Fetch multiple rules if task spans domains (e.g., `["scopes", "opentelemetry"]` for tracing scope issues) -4. **Context clues**: Look for these keywords in requests to determine relevant rules: - - Public API/apiDump/.api files/binary compatibility/new method → `api` - - Options/SentryOptions/ExternalOptions/ManifestMetadataReader/sentry.properties → `options` - - Scope/Hub/forking → `scopes` - - Duplicate/dedup → `deduplication` - - OpenTelemetry/tracing/spans → `opentelemetry` - - new module/integration/sample → `new_module` - - Cache/offline/network → `offline` - - System test/e2e/sample → `e2e_tests` - - Feature flag/addFeatureFlag/flag evaluation → `feature_flags` - - Metrics/count/distribution/gauge → `metrics` - - Queues/queue tracing/Kafka/Spring Kafka/queue.publish/queue.process/enableQueueTracing/messaging spans → `queues` - - PR/pull request/stacked PR/stack → `pr` - - JVM continuous profiling/async-profiler/JFR/ProfileChunk → `continuous_profiling_jvm` - - Android continuous profiling/AndroidProfiler/frame metrics/method tracing → no dedicated rule yet; inspect the code directly diff --git a/AGENTS.md b/AGENTS.md index 4f938ceff2d..f785961eceb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,30 @@ This file provides guidance to AI coding agents when working with code in this repository. -## STOP — Required Reading (Do This First) - -Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load these files: -1. `.cursor/rules/coding.mdc` -2. `.cursor/rules/overview_dev.mdc` - -Then identify and read any topically relevant `.cursor/rules/*.mdc` files for the area you're working on (e.g., `opentelemetry.mdc` for OTel work, `metrics.mdc` for metrics work). Use the Glob tool on `.cursor/rules/*.mdc` to discover available rule files. - -Do NOT skip this step. Do NOT proceed without reading these files first. +## Domain-Specific Rules + +This file covers the whole repository. Before working on a specific area, read the matching +rule file in `.cursor/rules/`: + +| Rule | Read it when working on | +|---|---| +| `api` | Public API surface, binary compatibility, `.api` files, `apiDump`, `IScope`/`IScopes`/`Sentry` static API, protocol classes | +| `options` | `SentryOptions`, namespaced options, `ExternalOptions`, `sentry.properties`, `ManifestMetadataReader`, Spring Boot properties | +| `scopes` | Scope management, forking, lifecycle, `ScopeType`, thread-local storage, scope bleeding, Hub → Scopes migration | +| `deduplication` | Duplicate event detection, `DuplicateEventDetectionEventProcessor`, `enableDeduplication` | +| `offline` | Caching, envelope storage, network failure handling, retries, `AsyncHttpTransport`, `EnvelopeCache`, rate limiting | +| `feature_flags` | `addFeatureFlag`, `FeatureFlagBuffer`, `maxFeatureFlags`, LaunchDarkly and OpenFeature integrations | +| `metrics` | `Sentry.metrics()`, `IMetricsApi`, count/distribution/gauge, `MetricsBatchProcessor` | +| `queues` | Queue tracing, `queue.publish`/`queue.process`, `enableQueueTracing`, Kafka instrumentation, messaging span data | +| `continuous_profiling_jvm` | `sentry-async-profiler`, `IContinuousProfiler`, `ProfileChunk`, JFR files, `ProfileLifecycle` | +| `opentelemetry` | `sentry-opentelemetry-*`, agent vs agentless, span processing, sampling, context propagation | +| `new_module` | Adding a new integration or sample module | +| `pr` | Creating pull requests, stacked PRs, changelog entries | +| `e2e_tests` | System tests, sample applications, `system-test-runner.py`, mock Sentry server | + +Rules can be combined — a tracing scope issue may need both `scopes` and `opentelemetry`. +There is no rule for Android profiling yet; read the `sentry-android-core` profiling code +directly and fetch related rules such as `options`, `offline`, or `api` as needed. ## Project Overview diff --git a/CLAUDE.md b/CLAUDE.md index 19507016af4..1b58162ca69 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,5 @@ # CLAUDE.md -## STOP — Required Reading (Do This First) - -Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load [AGENTS.md](AGENTS.md) and follow ALL of its instructions, including reading the required `.cursor/rules/*.mdc` files it references. -Do NOT skip this step. Do NOT proceed without reading these files first. +Read [AGENTS.md](AGENTS.md) and follow its instructions. It is the single source of truth +for build commands, contributing guidelines, workflow rules, and the index of the +domain-specific rules in `.cursor/rules/`. From 0b96a2ac8cae70874cd69f036b5873194b5faf6a Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Tue, 11 Aug 2026 14:14:54 +0200 Subject: [PATCH 2/4] docs(agents): Restore mandatory-reading language in CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dedupe commit softened the "STOP — Required Reading" block into a plain descriptive sentence. In practice an agent then treats AGENTS.md as optional background and answers questions without ever loading it, which is exactly what the original wording was there to prevent. Restore the imperative framing for AGENTS.md only. The old block also listed coding.mdc and overview_dev.mdc as required reading; those are gone, and the per-area rule files stay opt-in via the index table in AGENTS.md. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1b58162ca69..e4418234dd6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,9 @@ # CLAUDE.md -Read [AGENTS.md](AGENTS.md) and follow its instructions. It is the single source of truth +## STOP — Required Reading (Do This First) + +Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load +[AGENTS.md](AGENTS.md) and follow ALL of its instructions. It is the single source of truth for build commands, contributing guidelines, workflow rules, and the index of the domain-specific rules in `.cursor/rules/`. +Do NOT skip this step. Do NOT proceed without reading it first. From 5e81dabbd8ca0d5b0f3409d5a56a9ab6ffa63d5a Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Tue, 11 Aug 2026 14:16:56 +0200 Subject: [PATCH 3/4] docs(agents): Restore mandatory-reading language in coding.mdc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit coding.mdc is alwaysApply: true, making it Cursor's auto-injected entry point — the same role CLAUDE.md plays for Claude Code. Leaving it descriptive while CLAUDE.md is imperative means only one of the two agents is actually told to load AGENTS.md before doing anything. Phrased tool-neutrally rather than naming the Read tool, since Cursor's equivalent is read_file. Co-Authored-By: Claude Opus 5 (1M context) --- .cursor/rules/coding.mdc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.cursor/rules/coding.mdc b/.cursor/rules/coding.mdc index 36276800f1d..2dd768a999a 100644 --- a/.cursor/rules/coding.mdc +++ b/.cursor/rules/coding.mdc @@ -5,6 +5,10 @@ description: Cursor Coding Rules # Contributing Rules for Agents -Read [AGENTS.md](../../AGENTS.md) in the repository root. It is the single source of -truth for build commands, contributing guidelines, workflow rules, and the index of -the domain-specific rules in this directory. +## STOP — Required Reading (Do This First) + +Before doing ANYTHING else (including answering questions), you MUST read +[AGENTS.md](../../AGENTS.md) in the repository root and follow ALL of its instructions. +It is the single source of truth for build commands, contributing guidelines, workflow +rules, and the index of the domain-specific rules in this directory. +Do NOT skip this step. Do NOT proceed without reading it first. From 37e644d85c65dcde3a12f692d875782375491539 Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Tue, 11 Aug 2026 16:04:29 +0200 Subject: [PATCH 4/4] docs(agents): Remove redundant coding.mdc pointer file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor reads a root AGENTS.md automatically, so a .cursor/rules entry whose only content is 'go read AGENTS.md' instructs Cursor to load a file it has already merged into context. The domain-specific rules in .cursor/rules/ are unaffected — they are alwaysApply: false and are fetched on demand via the index table in AGENTS.md. CLAUDE.md stays: Claude Code does not read AGENTS.md natively. Co-Authored-By: Claude Opus 5 (1M context) --- .cursor/rules/coding.mdc | 14 -------------- CLAUDE.md | 2 +- 2 files changed, 1 insertion(+), 15 deletions(-) delete mode 100644 .cursor/rules/coding.mdc diff --git a/.cursor/rules/coding.mdc b/.cursor/rules/coding.mdc deleted file mode 100644 index 2dd768a999a..00000000000 --- a/.cursor/rules/coding.mdc +++ /dev/null @@ -1,14 +0,0 @@ ---- -alwaysApply: true -description: Cursor Coding Rules ---- - -# Contributing Rules for Agents - -## STOP — Required Reading (Do This First) - -Before doing ANYTHING else (including answering questions), you MUST read -[AGENTS.md](../../AGENTS.md) in the repository root and follow ALL of its instructions. -It is the single source of truth for build commands, contributing guidelines, workflow -rules, and the index of the domain-specific rules in this directory. -Do NOT skip this step. Do NOT proceed without reading it first. diff --git a/CLAUDE.md b/CLAUDE.md index e4418234dd6..f59e5a152f3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,5 +5,5 @@ Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load [AGENTS.md](AGENTS.md) and follow ALL of its instructions. It is the single source of truth for build commands, contributing guidelines, workflow rules, and the index of the -domain-specific rules in `.cursor/rules/`. +domain-specific rules. Do NOT skip this step. Do NOT proceed without reading it first.