Updated to AGENTS.md

rozza · rozza · commit 9d2913260c51 · 2026-03-24T16:21:42.000Z
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,46 +1,50 @@
-# CLAUDE.md - MongoDB Java Driver
+# AGENTS.md - MongoDB Java Driver
 
 Guidelines for AI agents working on the MongoDB Java Driver codebase.
 
 ## Project Overview
 
 This is the official MongoDB JVM driver monorepo, providing Java, Kotlin, and Scala
 drivers for MongoDB. The driver implements the
-[MongoDB Driver Specifications](https://github.com/mongodb/specifications)
-and follows semantic versioning.
+[MongoDB Driver Specifications](https://github.com/mongodb/specifications) and follows
+semantic versioning.
 
 ### Module Structure
 
-| Module                     | Purpose                                                   |
-|----------------------------|-----------------------------------------------------------|
-| `bson`                     | BSON library (core serialization)                         |
-| `bson-kotlin`              | Kotlin BSON extensions                                    |
-| `bson-kotlinx`             | Kotlin serialization BSON codec                           |
-| `bson-record-codec`        | Java record codec support                                 |
-| `bson-scala`               | Scala BSON extensions                                     |
-| `driver-core`              | Core driver internals (connections, protocol, operations) |
-| `driver-sync`              | Synchronous Java driver                                   |
-| `driver-legacy`            | Legacy MongoDB Java driver API                            |
-| `driver-reactive-streams`  | Reactive Streams driver                                   |
-| `driver-kotlin-coroutine`  | Kotlin Coroutines driver                                  |
-| `driver-kotlin-extensions` | Kotlin driver extensions                                  |
-| `driver-kotlin-sync`       | Kotlin synchronous driver                                 |
-| `driver-scala`             | Scala driver                                              |
-| `mongodb-crypt`            | Client-side field-level encryption                        |
-| `testing`                  | Shared test resources and MongoDB specifications          |
+| Module | Purpose |
+| --- | --- |
+| `bson` | BSON library (core serialization) |
+| `bson-kotlin` | Kotlin BSON extensions |
+| `bson-kotlinx` | Kotlin serialization BSON codec |
+| `bson-record-codec` | Java record codec support |
+| `bson-scala` | Scala BSON extensions |
+| `driver-core` | Core driver internals (connections, protocol, operations) |
+| `driver-sync` | Synchronous Java driver |
+| `driver-legacy` | Legacy MongoDB Java driver API |
+| `driver-reactive-streams` | Reactive Streams driver |
+| `driver-kotlin-coroutine` | Kotlin Coroutines driver |
+| `driver-kotlin-extensions` | Kotlin driver extensions |
+| `driver-kotlin-sync` | Kotlin synchronous driver |
+| `driver-scala` | Scala driver |
+| `mongodb-crypt` | Client-side field-level encryption |
+| `testing` | Shared test resources and MongoDB specifications |
 
 ### Internal API Convention
 
-All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API.
-It can change at any time without notice. Never expose internal types in
-public APIs, and never advise users to depend on them.
+All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API. It can
+change at any time without notice.
+Never expose internal types in public APIs, and never advise users to depend on them.
 
 ### API Stability Annotations
 
-- `@Alpha` - Early development, may be removed. Not for production use.
-- `@Beta` - Subject to change or removal. Libraries should not depend on these.
-- `@Evolving` - May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk.
-- `@Sealed` - Must not be extended or implemented by consumers. Safe to use, but not to subclass.
+- `@Alpha` - Early development, may be removed.
+  Not for production use.
+- `@Beta` - Subject to change or removal.
+  Libraries should not depend on these.
+- `@Evolving` - May add abstract methods in future releases.
+  Safe to use, but implementing/extending bears upgrade risk.
+- `@Sealed` - Must not be extended or implemented by consumers.
+  Safe to use, but not to subclass.
 - `@Deprecated` - Supported until next major release but should be migrated away from.
 
 ## General
@@ -60,7 +64,7 @@ public APIs, and never advise users to depend on them.
 ### Essential Build Commands
 
 ```bash
-# Full validation (static checks + unit tests + integration tests)
+# Full validation (spotlessApply + static checks + unit tests + integration tests)
 ./gradlew check
 
 # Integration tests (requires running MongoDB)
@@ -69,22 +73,16 @@ public APIs, and never advise users to depend on them.
 # Single module tests
 ./gradlew :driver-core:test
 
-# Format check only
-./gradlew spotlessCheck
-
-# Auto-fix formatting
-./gradlew spotlessApply
-
 # Test with alternative JDK
 ./gradlew test -PjavaVersion=11
 ```
 
 ## Code Style and Formatting
 
 Formatting is enforced automatically because the Gradle `check` task depends on
-`./gradlew spotlessApply`, which formats sources. To run a check without modifying
-files, invoke `./gradlew spotlessCheck` manually. Do not manually reformat files
-outside the scope of your changes.
+`./gradlew spotlessApply`, which formats sources.
+To run a check without modifying files, invoke `./gradlew spotlessCheck` manually.
+Do not manually reformat files outside the scope of your changes.
 
 ### Style Rules
 
@@ -96,7 +94,8 @@ outside the scope of your changes.
 - **Final parameters:** Required (FinalParameters checkstyle rule)
 - **Braces:** Required for all control structures (NeedBraces)
 - **Else placement:** On its own line (not cuddled)
-- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
+- **Copyright header:** Every Java / Kotlin / Scala file must contain
+  `Copyright 2008-present MongoDB, Inc.`
 
 ### Prohibited Patterns
 
@@ -114,28 +113,35 @@ outside the scope of your changes.
 
 ### Writing Tests
 
-- **Every code change must include tests.** New code needs new tests; modified code needs updated tests. Do not reduce test coverage.
+- **Every code change must include tests.** New code needs new tests; modified code
+  needs updated tests. Do not reduce test coverage.
 - Extend existing test patterns in the module you are modifying
 - Unit tests should not require a running MongoDB instance
-- Test methods should be descriptive:
-  prefer `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`,
-  use `@DisplayName` for a human readable name
+- Test methods should be descriptive: prefer
+  `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`, use `@DisplayName` for a
+  human readable name
 - Clean up test data in `@AfterEach` / `cleanup()` to prevent test pollution
 
 ### MongoDB Specifications and Specification Tests
 
-The driver implements the [MongoDB Specifications](https://github.com/mongodb/specifications). Specification test data files live in
-`testing/resources/specifications/` — a git submodule for test resources. When modifying driver specification-related behavior: do
-not modify existing specification tests unless they test incorrect behavior. Create new tests instead.
+The driver implements the
+[MongoDB Specifications](https://github.com/mongodb/specifications).
+Specification test data files live in `testing/resources/specifications/` — a git
+submodule for test resources.
+When modifying driver specification-related behavior: do not modify existing
+specification tests unless they test incorrect behavior.
+Create new tests instead.
 
 ## Core Development Principles
 
 ### Essential Rules
 
-- **Read before modifying.** Understand existing code and patterns before making changes.
+- **Read before modifying.** Understand existing code and patterns before making
+  changes.
 - **Minimal changes only.** No drive-by refactoring.
 - **Preserve existing comments.** Only remove comments that are provably incorrect.
-- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of the task.
+- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of
+  the task.
 - **No rewrites** without explicit permission.
 
 ### Search Before Implementing
@@ -148,20 +154,19 @@ Before writing new code, search the codebase for existing implementations:
 
 ### API Design
 
-- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
+- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow
+  wrappers.
 - **Information hiding:** Bury complexity behind simple interfaces.
 - **Pull complexity downward:** Make the implementer work harder so callers work less.
-- **General-purpose over special-case:** Fewer flexible methods over many specialized ones.
-- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them.
+- **General-purpose over special-case:** Fewer flexible methods over many specialized
+  ones.
+- **Define errors out of existence:** Design APIs so errors cannot happen rather than
+  detecting and handling them.
 
 ## Dependency Management
 
 Dependencies are managed centrally via `gradle/libs.versions.toml`.
-
-- **Never add dependencies without justification.** Dependencies are liabilities.
-- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms.
-- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths.
-- Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime.
+Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime.
 
 ## Safety Rules - Do Not Modify Without Review
 
@@ -177,7 +182,8 @@ Dependencies are managed centrally via `gradle/libs.versions.toml`.
 
 ### Evergreen (MongoDB Internal CI)
 
-Primary CI runs on MongoDB's Evergreen system. Configuration is in `.evergreen/`.
+Primary CI runs on MongoDB’s Evergreen system.
+Configuration is in `.evergreen/`.
 
 ### Before Submitting
 
diff --git a/bom/AGENTS.md b/bom/AGENTS.md
@@ -0,0 +1,12 @@
+# AGENTS.md - bom
+
+Bill of Materials (BOM) POM for the MongoDB Java Driver, simplifying dependency version management.
+
+**Depends on:** All published driver modules (transitive version constraints only)
+
+## Notes
+
+- Java Platform plugin — no source code, only version constraints
+- Automatically includes all supported Scala version variants for `bson-scala` and `driver-scala`
+- Validates generated POM: all dependencies must be `org.mongodb`, no `<scope>` or `<optional>` elements
+- Do not add non-MongoDB dependencies to this module
diff --git a/bson-kotlin/AGENTS.md b/bson-kotlin/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - bson-kotlin
+# AGENTS.md - bson-kotlin
 
 Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support.
 
diff --git a/bson-kotlinx/AGENTS.md b/bson-kotlinx/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - bson-kotlinx
+# AGENTS.md - bson-kotlinx
 
 Kotlinx serialization integration for BSON, providing a pluggable serialization format.
 
diff --git a/bson-record-codec/AGENTS.md b/bson-record-codec/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - bson-record-codec
+# AGENTS.md - bson-record-codec
 
 Java record codec support for BSON serialization. **Requires Java 17+.**
 
diff --git a/bson-scala/AGENTS.md b/bson-scala/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - bson-scala
+# AGENTS.md - bson-scala
 
 Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs.
 
diff --git a/bson/AGENTS.md b/bson/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - bson
+# AGENTS.md - bson
 
 Core BSON (Binary JSON) library. This is the foundation module — all other modules depend on it.
 
diff --git a/buildSrc/AGENTS.md b/buildSrc/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - buildSrc
+# AGENTS.md - buildSrc
 
 Gradle build infrastructure providing convention plugins and shared configuration for all modules.
 
@@ -49,12 +49,12 @@ Gradle build infrastructure providing convention plugins and shared configuratio
 - `check` depends on `spotlessCheck` in buildSrc itself
 - Java toolchain is set to Java 17
 
-## Keeping CLAUDE.md Files in Sync
+## Keeping AGENTS.md Files in Sync
 
-When modifying buildSrc, you **must** update the relevant CLAUDE.md files if your changes affect:
+When modifying buildSrc, you **must** update the relevant AGENTS.md files if your changes affect:
 
-- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `CLAUDE.md` "Code Style and Formatting" section and any module CLAUDE.md files that reference formatting rules
-- **Convention plugins added or removed** — update this file's plugin table and the root `CLAUDE.md` if the change affects build commands or developer workflow
-- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `CLAUDE.md` "Testing" section and affected module CLAUDE.md files
+- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `AGENTS.md` "Code Style and Formatting" section and any module AGENTS.md files that reference formatting rules
+- **Convention plugins added or removed** — update this file's plugin table and the root `AGENTS.md` if the change affects build commands or developer workflow
+- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `AGENTS.md` "Testing" section and affected module AGENTS.md files
 - **Project plugins added or removed** — update this file's project plugin table
-- **Build commands or task names changed** — update the root `CLAUDE.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections
+- **Build commands or task names changed** — update the root `AGENTS.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections
diff --git a/driver-benchmarks/AGENTS.md b/driver-benchmarks/AGENTS.md
@@ -0,0 +1,20 @@
+# AGENTS.md - driver-benchmarks
+
+Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark framework.
+
+**Depends on:** `driver-sync`, `mongodb-crypt`
+
+## Key Packages
+
+- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, single/multi-doc, bulk operations)
+- `com.mongodb.benchmark.benchmarks.bulk` — Bulk write benchmarks
+- `com.mongodb.benchmark.benchmarks.netty` — Netty transport benchmarks
+- `com.mongodb.benchmark.framework` — Custom benchmark harness
+- `com.mongodb.benchmark.jmh` — JMH microbenchmarks
+
+## Notes
+
+- Not published — internal testing only
+- Non-standard source layout: `src/main` (no `java` subdirectory)
+- Run benchmarks: `./gradlew :driver-benchmarks:run` or `./gradlew :driver-benchmarks:jmh`
+- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system properties
diff --git a/driver-core/AGENTS.md b/driver-core/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-core
+# AGENTS.md - driver-core
 
 Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module.
 
diff --git a/driver-kotlin-coroutine/AGENTS.md b/driver-kotlin-coroutine/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-kotlin-coroutine
+# AGENTS.md - driver-kotlin-coroutine
 
 Kotlin Coroutines driver providing `suspend` function-based async API.
 
diff --git a/driver-kotlin-extensions/AGENTS.md b/driver-kotlin-extensions/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-kotlin-extensions
+# AGENTS.md - driver-kotlin-extensions
 
 Kotlin extensions providing type-safe DSLs for query and update construction.
 
diff --git a/driver-kotlin-sync/AGENTS.md b/driver-kotlin-sync/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-kotlin-sync
+# AGENTS.md - driver-kotlin-sync
 
 Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-sync`.
 
diff --git a/driver-lambda/AGENTS.md b/driver-lambda/AGENTS.md
@@ -0,0 +1,16 @@
+# AGENTS.md - driver-lambda
+
+AWS Lambda test application for validating the MongoDB Java Driver in Lambda environments.
+
+**Depends on:** `bson`, `driver-sync`
+
+## Key Packages
+
+- `com.mongodb.lambdatest` — Lambda test application entry point
+
+## Notes
+
+- Not published — internal testing only
+- Java 11 source/target compatibility
+- Built as a shadow JAR for Lambda deployment
+- Non-standard source layout: `src/main` (no `java` subdirectory)
diff --git a/driver-legacy/AGENTS.md b/driver-legacy/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-legacy
+# AGENTS.md - driver-legacy
 
 Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x API.
 
diff --git a/driver-reactive-streams/AGENTS.md b/driver-reactive-streams/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-reactive-streams
+# AGENTS.md - driver-reactive-streams
 
 Reactive Streams driver implementing the [Reactive Streams specification](https://www.reactive-streams.org/).
 
diff --git a/driver-scala/AGENTS.md b/driver-scala/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-scala
+# AGENTS.md - driver-scala
 
 Scala async driver providing Observable-based API wrapping `driver-reactive-streams`.
 
diff --git a/driver-sync/AGENTS.md b/driver-sync/AGENTS.md
@@ -1,4 +1,4 @@
-# CLAUDE.md - driver-sync
+# AGENTS.md - driver-sync
 
 Synchronous (blocking) Java driver — the most commonly used entry point for Java applications.
 
diff --git a/graalvm-native-image-app/AGENTS.md b/graalvm-native-image-app/AGENTS.md
@@ -0,0 +1,17 @@
+# AGENTS.md - graalvm-native-image-app
+
+GraalVM Native Image test application verifying driver compatibility with native compilation.
+
+**Depends on:** `bson`, `driver-core`, `driver-sync`, `driver-legacy`, `driver-reactive-streams`, `mongodb-crypt`
+
+## Key Packages
+
+- `com.mongodb.internal.graalvm` — Native image test app, GraalVM substitutions, and custom DNS support
+
+## Notes
+
+- Not published — internal testing only
+- Requires `-PincludeGraalvm` Gradle property to be included in the build
+- Requires GraalVM JDK 21+ installed and detected by Gradle toolchains
+- Reachability metadata in `src/main/resources/META-INF/native-image/`
+- Non-standard source layout: `src/main` (no `java` subdirectory)
diff --git a/gradle/AGENTS.md b/gradle/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md - gradle
+
+Gradle configuration and infrastructure for the build system.
+
+## Key Files
+
+- `libs.versions.toml` — Central version catalog defining all dependency versions, library coordinates, bundles, and plugin versions
+- `wrapper/` — Gradle wrapper JAR and properties (do not modify manually — use `./gradlew wrapper --gradle-version=<version>`)
+- `scala/lib/` — Bundled Scala Ant JAR for Scala compilation support
+
+## Notes
+
+- All dependency versions are managed in `libs.versions.toml` — never declare versions inline in `build.gradle.kts` files
+- **Never add dependencies without justification.** Dependencies are liabilities.
+- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms.
+- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths.
+- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` sections
+- Scala test libraries are declared per Scala version (v3, v2-v13, v2-v12, v2-v11)
+- When adding or updating dependencies, modify `libs.versions.toml` and reference via `libs.<alias>` in build scripts
diff --git a/mongodb-crypt/AGENTS.md b/mongodb-crypt/AGENTS.md
diff --git a/testing/AGENTS.md b/testing/AGENTS.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CLAUDE.md - bson-kotlin`
	`1`	`+# AGENTS.md - bson-kotlin`
`2`	`2`
`3`	`3`	`Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CLAUDE.md - bson-kotlinx`
	`1`	`+# AGENTS.md - bson-kotlinx`
`2`	`2`
`3`	`3`	`Kotlinx serialization integration for BSON, providing a pluggable serialization format.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CLAUDE.md - bson-record-codec`
	`1`	`+# AGENTS.md - bson-record-codec`
`2`	`2`
`3`	`3`	`Java record codec support for BSON serialization. Requires Java 17+.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CLAUDE.md - bson-scala`
	`1`	`+# AGENTS.md - bson-scala`
`2`	`2`
`3`	`3`	`Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CLAUDE.md - bson`
	`1`	`+# AGENTS.md - bson`
`2`	`2`
`3`	`3`	`Core BSON (Binary JSON) library. This is the foundation module — all other modules depend on it.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CLAUDE.md - driver-core`
	`1`	`+# AGENTS.md - driver-core`
`2`	`2`
`3`	`3`	`Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module.`
`4`	`4`