Skip to content

Commit 6ea4329

Browse files
adinaueradinauer
authored
move contents of CLAUDE.md into AGENTS.md; force Claude to read AGENTS.md and some .cursor/skills (#5103)
1 parent 22f4345 commit 6ea4329

File tree

2 files changed

+156
-152
lines changed

2 files changed

+156
-152
lines changed

‎AGENTS.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI coding agents when working with code in this repository.
4+
5+
## STOP — Required Reading (Do This First)
6+
7+
Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load these files:
8+
1. `.cursor/rules/coding.mdc`
9+
2. `.cursor/rules/overview_dev.mdc`
10+
11+
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.
12+
13+
Do NOT skip this step. Do NOT proceed without reading these files first.
14+
15+
## Project Overview
16+
17+
This is the Sentry Java/Android SDK - a comprehensive error monitoring and performance tracking SDK for Java and Android applications. The repository contains multiple modules for different integrations and platforms.
18+
19+
## Build System
20+
21+
The project uses **Gradle** with Kotlin DSL. Key build files:
22+
- `build.gradle.kts` - Root build configuration
23+
- `settings.gradle.kts` - Multi-module project structure
24+
- `buildSrc/` and `build-logic/` - Custom build logic and plugins
25+
- `Makefile` - High-level build commands
26+
27+
## Essential Commands
28+
29+
### Development Workflow
30+
```bash
31+
# Format code and regenerate .api files (REQUIRED before committing)
32+
./gradlew spotlessApply apiDump
33+
34+
# Run all tests and linter
35+
./gradlew check
36+
37+
# Build entire project
38+
./gradlew build
39+
40+
# Create coverage reports
41+
./gradlew jacocoTestReport koverXmlReportRelease
42+
43+
# Generate documentation
44+
./gradlew aggregateJavadocs
45+
```
46+
47+
### Testing
48+
```bash
49+
# Run unit tests for a specific file
50+
./gradlew ':<module>:testDebugUnitTest' --tests="*<file name>*" --info
51+
52+
# Run system tests (requires Python virtual env)
53+
make systemTest
54+
55+
# Run specific test suites
56+
./gradlew :sentry-android-core:testDebugUnitTest
57+
./gradlew :sentry:test
58+
```
59+
60+
### Code Quality
61+
```bash
62+
# Check code formatting
63+
./gradlew spotlessJavaCheck spotlessKotlinCheck
64+
65+
# Apply code formatting
66+
./gradlew spotlessApply
67+
68+
# Update API dump files (after API changes)
69+
./gradlew apiDump
70+
71+
# Dependency updates check
72+
./gradlew dependencyUpdates -Drevision=release
73+
```
74+
75+
### Android-Specific Commands
76+
```bash
77+
# Assemble Android test APKs
78+
./gradlew :sentry-android-integration-tests:sentry-uitest-android:assembleRelease
79+
./gradlew :sentry-android-integration-tests:sentry-uitest-android:assembleAndroidTest -DtestBuildType=release
80+
81+
# Run critical UI tests
82+
./scripts/test-ui-critical.sh
83+
```
84+
85+
## Development Workflow Rules
86+
87+
### Planning and Implementation Process
88+
1. **First think through the problem**: Read the codebase for relevant files and propose a plan
89+
2. **Check in before beginning**: Verify the plan before starting implementation
90+
3. **Use todo tracking**: Work through todo items, marking them as complete as you go
91+
4. **High-level communication**: Give high-level explanations of changes made, not step-by-step descriptions
92+
5. **Simplicity first**: Make every task and code change as simple as possible. Avoid massive or complex changes. Impact as little code as possible.
93+
6. **Format and regenerate**: Once done, format code and regenerate .api files: `./gradlew spotlessApply apiDump`
94+
7. **Propose commit**: As final step, git stage relevant files and propose (but not execute) a single git commit command
95+
96+
## Module Architecture
97+
98+
The repository is organized into multiple modules:
99+
100+
### Core Modules
101+
- **`sentry`** - Core Java SDK implementation
102+
- **`sentry-android-core`** - Core Android SDK implementation
103+
- **`sentry-android`** - High-level Android SDK
104+
105+
### Integration Modules
106+
- **Spring Framework**: `sentry-spring*`, `sentry-spring-boot*`
107+
- **Logging**: `sentry-logback`, `sentry-log4j2`, `sentry-jul`
108+
- **Web**: `sentry-servlet*`, `sentry-okhttp`, `sentry-apache-http-client-5`
109+
- **GraphQL**: `sentry-graphql*`, `sentry-apollo*`
110+
- **Android UI**: `sentry-android-fragment`, `sentry-android-navigation`, `sentry-compose`
111+
- **Reactive**: `sentry-reactor`, `sentry-ktor-client`
112+
- **Monitoring**: `sentry-opentelemetry*`, `sentry-quartz`
113+
114+
### Utility Modules
115+
- **`sentry-test-support`** - Shared test utilities
116+
- **`sentry-system-test-support`** - System testing infrastructure
117+
- **`sentry-samples`** - Example applications
118+
- **`sentry-bom`** - Bill of Materials for dependency management
119+
120+
### Key Architectural Patterns
121+
- **Multi-platform**: Supports JVM, Android, and Kotlin Multiplatform (Compose modules)
122+
- **Modular Design**: Each integration is a separate module with minimal dependencies
123+
- **Options Pattern**: Features are opt-in via `SentryOptions` and similar configuration classes
124+
- **Transport Layer**: Pluggable transport implementations for different environments
125+
- **Scope Management**: Thread-safe scope/context management for error tracking
126+
127+
## Development Guidelines
128+
129+
### Code Style
130+
- **Languages**: Java 8+ and Kotlin
131+
- **Formatting**: Enforced via Spotless - always run `./gradlew spotlessApply` before committing
132+
- **API Compatibility**: Binary compatibility is enforced - run `./gradlew apiDump` after API changes
133+
134+
### Testing Requirements
135+
- Write comprehensive unit tests for new features
136+
- Android modules require both unit tests and instrumented tests where applicable
137+
- System tests validate end-to-end functionality with sample applications
138+
- Coverage reports are generated for both JaCoCo (Java/Android) and Kover (KMP modules)
139+
140+
### Contributing Guidelines
141+
1. Follow existing code style and language
142+
2. Do not modify API files (e.g. sentry.api) manually - run `./gradlew apiDump` to regenerate them
143+
3. Write comprehensive tests
144+
4. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters
145+
5. Consider backwards compatibility
146+
147+
## Useful Resources
148+
149+
- Main SDK documentation: https://develop.sentry.dev/sdk/overview/
150+
- Internal contributing guide: https://docs.sentry.io/internal/contributing/
151+
- Git commit message conventions: https://develop.sentry.dev/engineering-practices/commit-messages/
152+
153+
This SDK is production-ready and used by thousands of applications. Changes should be thoroughly tested and maintain backwards compatibility.

‎CLAUDE.md‎

Lines changed: 3 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1,156 +1,7 @@
11
# CLAUDE.md
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+
## STOP — Required Reading (Do This First)
44

5-
## Project Overview
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, including reading the required `.cursor/rules/*.mdc` files it references.
66

7-
This is the Sentry Java/Android SDK - a comprehensive error monitoring and performance tracking SDK for Java and Android applications. The repository contains multiple modules for different integrations and platforms.
8-
9-
## Build System
10-
11-
The project uses **Gradle** with Kotlin DSL. Key build files:
12-
- `build.gradle.kts` - Root build configuration
13-
- `settings.gradle.kts` - Multi-module project structure
14-
- `buildSrc/` and `build-logic/` - Custom build logic and plugins
15-
- `Makefile` - High-level build commands
16-
17-
## Essential Commands
18-
19-
### Development Workflow
20-
```bash
21-
# Format code and regenerate .api files (REQUIRED before committing)
22-
./gradlew spotlessApply apiDump
23-
24-
# Run all tests and linter
25-
./gradlew check
26-
27-
# Build entire project
28-
./gradlew build
29-
30-
# Create coverage reports
31-
./gradlew jacocoTestReport koverXmlReportRelease
32-
33-
# Generate documentation
34-
./gradlew aggregateJavadocs
35-
```
36-
37-
### Testing
38-
```bash
39-
# Run unit tests for a specific file
40-
./gradlew ':<module>:testDebugUnitTest' --tests="*<file name>*" --info
41-
42-
# Run system tests (requires Python virtual env)
43-
make systemTest
44-
45-
# Run specific test suites
46-
./gradlew :sentry-android-core:testDebugUnitTest
47-
./gradlew :sentry:test
48-
```
49-
50-
### Code Quality
51-
```bash
52-
# Check code formatting
53-
./gradlew spotlessJavaCheck spotlessKotlinCheck
54-
55-
# Apply code formatting
56-
./gradlew spotlessApply
57-
58-
# Update API dump files (after API changes)
59-
./gradlew apiDump
60-
61-
# Dependency updates check
62-
./gradlew dependencyUpdates -Drevision=release
63-
```
64-
65-
### Android-Specific Commands
66-
```bash
67-
# Assemble Android test APKs
68-
./gradlew :sentry-android-integration-tests:sentry-uitest-android:assembleRelease
69-
./gradlew :sentry-android-integration-tests:sentry-uitest-android:assembleAndroidTest -DtestBuildType=release
70-
71-
# Run critical UI tests
72-
./scripts/test-ui-critical.sh
73-
```
74-
75-
## Development Workflow Rules
76-
77-
### Planning and Implementation Process
78-
1. **First think through the problem**: Read the codebase for relevant files and propose a plan
79-
2. **Check in before beginning**: Verify the plan before starting implementation
80-
3. **Use todo tracking**: Work through todo items, marking them as complete as you go
81-
4. **High-level communication**: Give high-level explanations of changes made, not step-by-step descriptions
82-
5. **Simplicity first**: Make every task and code change as simple as possible. Avoid massive or complex changes. Impact as little code as possible.
83-
6. **Format and regenerate**: Once done, format code and regenerate .api files: `./gradlew spotlessApply apiDump`
84-
7. **Propose commit**: As final step, git stage relevant files and propose (but not execute) a single git commit command
85-
86-
## Module Architecture
87-
88-
The repository is organized into multiple modules:
89-
90-
### Core Modules
91-
- **`sentry`** - Core Java SDK implementation
92-
- **`sentry-android-core`** - Core Android SDK implementation
93-
- **`sentry-android`** - High-level Android SDK
94-
95-
### Integration Modules
96-
- **Spring Framework**: `sentry-spring*`, `sentry-spring-boot*`
97-
- **Logging**: `sentry-logback`, `sentry-log4j2`, `sentry-jul`
98-
- **Web**: `sentry-servlet*`, `sentry-okhttp`, `sentry-apache-http-client-5`
99-
- **GraphQL**: `sentry-graphql*`, `sentry-apollo*`
100-
- **Android UI**: `sentry-android-fragment`, `sentry-android-navigation`, `sentry-compose`
101-
- **Reactive**: `sentry-reactor`, `sentry-ktor-client`
102-
- **Monitoring**: `sentry-opentelemetry*`, `sentry-quartz`
103-
104-
### Utility Modules
105-
- **`sentry-test-support`** - Shared test utilities
106-
- **`sentry-system-test-support`** - System testing infrastructure
107-
- **`sentry-samples`** - Example applications
108-
- **`sentry-bom`** - Bill of Materials for dependency management
109-
110-
### Key Architectural Patterns
111-
- **Multi-platform**: Supports JVM, Android, and Kotlin Multiplatform (Compose modules)
112-
- **Modular Design**: Each integration is a separate module with minimal dependencies
113-
- **Options Pattern**: Features are opt-in via `SentryOptions` and similar configuration classes
114-
- **Transport Layer**: Pluggable transport implementations for different environments
115-
- **Scope Management**: Thread-safe scope/context management for error tracking
116-
117-
## Development Guidelines
118-
119-
### Code Style
120-
- **Languages**: Java 8+ and Kotlin
121-
- **Formatting**: Enforced via Spotless - always run `./gradlew spotlessApply` before committing
122-
- **API Compatibility**: Binary compatibility is enforced - run `./gradlew apiDump` after API changes
123-
124-
### Testing Requirements
125-
- Write comprehensive unit tests for new features
126-
- Android modules require both unit tests and instrumented tests where applicable
127-
- System tests validate end-to-end functionality with sample applications
128-
- Coverage reports are generated for both JaCoCo (Java/Android) and Kover (KMP modules)
129-
130-
### Contributing Guidelines
131-
1. Follow existing code style and language
132-
2. Do not modify API files (e.g. sentry.api) manually - run `./gradlew apiDump` to regenerate them
133-
3. Write comprehensive tests
134-
4. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters
135-
5. Consider backwards compatibility
136-
137-
## Domain-Specific Knowledge Areas
138-
139-
For complex SDK functionality, refer to the detailed cursor rules in `.cursor/rules/`:
140-
141-
- **Scopes and Hub Management**: See `.cursor/rules/scopes.mdc` for details on `IScopes`, scope types (global/isolation/current), thread-local storage, forking behavior, and v7→v8 migration patterns
142-
- **Event Deduplication**: See `.cursor/rules/deduplication.mdc` for `DuplicateEventDetectionEventProcessor` and `enableDeduplication` option
143-
- **Offline Behavior and Caching**: See `.cursor/rules/offline.mdc` for envelope caching, retry logic, transport behavior, and Android vs JVM differences
144-
- **OpenTelemetry Integration**: See `.cursor/rules/opentelemetry.mdc` for agent vs agentless modes, span processing, context propagation, and configuration
145-
- **System Testing (E2E)**: See `.cursor/rules/e2e_tests.mdc` for system test framework, mock server setup, and CI workflows
146-
147-
### Usage Pattern
148-
When working on these specific areas, read the corresponding cursor rule file first to understand the detailed architecture, then proceed with implementation.
149-
150-
## Useful Resources
151-
152-
- Main SDK documentation: https://develop.sentry.dev/sdk/overview/
153-
- Internal contributing guide: https://docs.sentry.io/internal/contributing/
154-
- Git commit message conventions: https://develop.sentry.dev/engineering-practices/commit-messages/
155-
156-
This SDK is production-ready and used by thousands of applications. Changes should be thoroughly tested and maintain backwards compatibility.
7+
Do NOT skip this step. Do NOT proceed without reading these files first.

0 commit comments

Comments
 (0)