mongodb · rozza · Mar 23, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
@@ -0,0 +1,45 @@
+---
+name: api-design
+description: API stability annotations, design principles, and patterns for the MongoDB Java Driver. Use when adding or modifying public API surface — new classes, methods, interfaces, or changing method signatures.
+---
+# API Design
+
+## 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.
+- `@Deprecated` — Supported until next major release but should be migrated away from.
+
+## Design Principles
+
+- **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.
+
+## Search Before Implementing
+
+Before writing new code, search the codebase for existing implementations:
+
+- Check if a utility method already exists in `com.mongodb.internal.*`
+- Check if a similar pattern is established elsewhere in the module
+- Reuse existing well-tested infrastructure over creating duplicates
+
+## Key Patterns
+
+- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
+- Fluent builders: `MongoClientSettings.builder()` is the primary entry point
+- Abstract core with pluggable transports
+
+## Public API Rules
+
+- Breaking changes require a major version bump - ALWAYS warn if breaking binary compatibility
+- All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in public APIs
+- Every public package must have a `package-info.java`
@@ -0,0 +1,34 @@
+---
+name: evergreen
+description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix.
+---
+# Evergreen
+
+## Evergreen (MongoDB Internal CI)
+
+Primary CI runs on MongoDB’s Evergreen system.
+Configuration lives in `.evergreen/`.
+
+- Do not modify `.evergreen/` configuration without review
+- Evergreen runs the full test matrix across MongoDB versions, OS platforms, and JDK versions
+
+## Validating Evergreen Configuration
+
+After modifying `.evergreen/` files, validate the config locally:
+
+```bash
+evergreen validate $PROJECT_PATH/.evergreen/.evg.yml
+```
+
+Always run this before submitting changes to `.evergreen/` to catch syntax errors and invalid task definitions.
+
+## Testing with a Patch Build
+
+To test your changes on Evergreen before merging, create a patch build:
+
+```bash
+evergreen patch -u
+```
+
+This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI
+test matrix against your branch.
@@ -0,0 +1,63 @@
+---
+name: project-guide
+description: Project structure, dependency graph, and guide for finding the right project to work in. Use when starting a task and unsure which project owns the relevant code, or when you need to understand cross-project dependencies.
+---
+# Project Guide
+
+## Project Structure
+
+| Project | 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 |
+| `bom` | Bill of Materials for dependency management |
+| `testing` | Shared test resources and MongoDB specifications |
+| `buildSrc` | Gradle convention plugins and build infrastructure |
+| `driver-benchmarks` | JMH and custom performance benchmarks (not published) |
+| `driver-lambda` | AWS Lambda test application (not published) |
+| `graalvm-native-image-app` | GraalVM Native Image compatibility testing (not published) |
+
+## Dependency Graph (simplified)
+
+```
+bson
+ ├── bson-kotlin
+ ├── bson-kotlinx
+ ├── bson-record-codec
+ ├── bson-scala
+ └── driver-core
+      ├── driver-sync
+      │    ├── driver-legacy
+      │    ├── driver-kotlin-sync
+      │    └── driver-lambda
+      ├── driver-reactive-streams
+      │    ├── driver-kotlin-coroutine
+      │    └── driver-scala
+      └── driver-kotlin-extensions
+```
+
+## Finding the Right Module
+
+- **BSON serialization/codecs:** `bson` (or `bson-kotlin`/`bson-kotlinx`/`bson-scala` for language-specific)
+- **Query builders, filters, aggregates:** `driver-core` (`com.mongodb.client.model`)
+- **Sync Java API:** `driver-sync`
+- **Reactive API:** `driver-reactive-streams`
+- **Kotlin coroutines:** `driver-kotlin-coroutine`
+- **Kotlin DSL builders:** `driver-kotlin-extensions`
+- **Scala driver:** `driver-scala`
+- **Connection, protocol, auth internals:** `driver-core` (`com.mongodb.internal.*`)
+- **Build plugins, formatting, test infra:** `buildSrc`
+
+Each module has its own `AGENTS.md` with module-specific packages, patterns, and notes.
@@ -0,0 +1,41 @@
+---
+name: spec-tests
+description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications, or when working with the test data in testing/resources/specifications/.
+---
+# MongoDB Specification Tests
+
+## Overview
+
+The driver implements the [MongoDB Driver Specifications](https://github.com/mongodb/specifications).
+Specification test data files live in `testing/resources/specifications/` — a git submodule.
+
+## Rules
+
+- **Do not modify existing specification tests** unless they test incorrect behavior
+- **Do not modify spec test data** — it is managed upstream
+- Create new tests instead of modifying existing ones
+- Update the submodule via `git submodule update`
+
+## Structure
+
+Spec test data is organized by specification area:
+
+- CRUD, SDAM, auth, CSFLE, retryable operations, and more
+- Each spec area has JSON/YAML test data files defining inputs and expected outputs
+- Driver test runners parse these files and execute against the driver
+
+## Test Data Location
+
+```
+testing/
+  resources/
+    specifications/    # Git submodule — do not edit directly
+    logback-test.xml   # Shared logback configuration for tests
+```
+
+## Adding Spec Test Support
+
+1. Check `testing/resources/specifications/` for the relevant spec test data
+2. Find existing test runners in the module (look for `*SpecificationTest*` or similar)
+3. Extend existing patterns — each module handles spec tests slightly differently
+4. Ensure tests run with `./gradlew check` or the module’s test task
@@ -0,0 +1,44 @@
+---
+name: style-reference
+description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style, or language-specific formatter configuration. Spotless auto-enforces most rules.
+---
+# Style Reference
+
+## Java Style Rules
+
+- **Max line length:** 140 characters
+- **Indentation:** 4 spaces (no tabs)
+- **Line endings:** LF (Unix)
+- **Charset:** UTF-8
+- **Star imports:** Prohibited (AvoidStarImport)
+- **Final parameters:** Required (FinalParameters checkstyle rule)
+- **Braces:** Required for all control structures (NeedBraces)
+- **Else placement:** `} else {` on the same line (Palantir Java Format default)
+- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
+- **Formatter:** Palantir Java Format
+
+## Kotlin Style Rules
+
+- **Formatter:** ktfmt dropbox style, max width 120
+- **Static analysis:** detekt
+
+## Scala Style Rules
+
+- **Formatter:** scalafmt
+- **Supported versions:** 2.11, 2.12, 2.13, 3 (default: 2.13)
+
+## Groovy Style Rules
+
+- **Static analysis:** CodeNarc
+
+## Prohibited Patterns
+
+- `System.out.println` / `System.err.println` — Use SLF4J logging
+- `e.printStackTrace()` — Use proper logging/error handling
+
+## Formatting Commands
+
+```bash
+./gradlew spotlessApply    # Auto-fix all formatting
+./gradlew spotlessCheck    # Check without modifying
+```
@@ -0,0 +1,60 @@
+---
+name: testing-guide
+description: Testing frameworks, conventions, and commands for the MongoDB Java Driver. Use when writing or running tests — covers framework selection per module, test naming conventions, integration test setup, and how to run specific test subsets.
+---
+# Testing Guide
+
+## Frameworks
+
+| Framework | Usage | Notes |
+| --- | --- | --- |
+| JUnit 5 (Jupiter) | Primary unit test framework | All new tests |
+| Spock (Groovy) | Legacy tests | Do not add new Spock tests |
+| Mockito | Mocking | Use `mockito-junit-jupiter` integration |
+| ScalaTest | Scala module testing | FlatSpec + ShouldMatchers |
+| Project Reactor | Reactive test utilities | `driver-reactive-streams` tests |
+
+## Writing Tests
+
+- Every code change must include tests
+- Extend existing test patterns in the module you are modifying
+- Unit tests must not require a running MongoDB instance
+- Descriptive method names: `shouldReturnEmptyListWhenNoDocumentsMatch()` not `test1()`
+- Use `@DisplayName` for human-readable names
+- Clean up test data in `@AfterEach` / `cleanup()` to prevent pollution
+
+## Running Tests
+
+```bash
+# All tests (unit + integration)
+./gradlew check
+
+# Single module
+./gradlew :driver-core:test
+
+# Integration tests (requires MongoDB)
+./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
+
+# Specific test class
+./gradlew :driver-core:test --tests "com.mongodb.internal.operation.FindOperationTest"
+
+# Alternative JDK
+./gradlew test -PjavaVersion=11
+
+# Scala tests (all versions)
+./gradlew scalaCheck
+```
+
+## Module-Specific Notes
+
+- **driver-core:** Largest test suite — JUnit 5 + Spock + Mockito
+- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don’t add new)
+- **driver-reactive-streams:** JUnit 5 + Spock + Project Reactor
+- **bson-scala / driver-scala:** ScalaTest, test per Scala version
+- **Kotlin modules:** JUnit 5 + mockito-kotlin
+
+## Integration Tests
+
+- Require a running MongoDB instance
+- Set connection URI: `-Dorg.mongodb.test.uri="mongodb://localhost:27017"`
+- Integration test source set configured via `conventions/testing-integration.gradle.kts`
@@ -0,0 +1 @@
+../.agents/skills
@@ -55,6 +55,9 @@ local.properties
 # security-sensitive files
 *.gpg
 
+# per-developer agent overrides
+.AGENTS.md
+
 # bin build directories
 **/bin
 
@@ -0,0 +1,71 @@
+# AGENTS.md - MongoDB Java Driver
+
+All changes require human review.
+Breaking changes to public API require a major version bump — always warn if binary compatibility is affected.
+Also consult `.AGENTS.md` / `~/.AGENTS.md` if present for local agent settings.
+
+See [`.agents/skills/project-guide`](.agents/skills/project-guide/SKILL.md) for module structure and dependency graph.
+Each module has its own `AGENTS.md`.
+
+## Core Rules
+
+- Read before modifying.
+  Understand existing code and patterns first.
+- Minimal changes only.
+  No drive-by refactoring or unrelated changes.
+- Preserve existing comments.
+  Only remove if provably incorrect.
+- No rewrites without explicit permission.
+- When stuck or uncertain: stop, explain, propose alternatives, ask.
+
+## Build
+
+Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in `gradle/libs.versions.toml`.
+
+```bash
+./gradlew check                        # Full validation (format + static checks + tests)
+./gradlew :driver-core:test            # Single module tests
+./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
+```
+
+## Style
+
+`check` runs `spotlessCheck` to verify formatting — run `./gradlew spotlessApply` to auto-format when needed.
+Do not reformat outside your changes.
+See [`.agents/skills/style-reference`](.agents/skills/style-reference/SKILL.md) for full rules.
+
+- No `System.out.println` / `System.err.println` — use SLF4J
+- No `e.printStackTrace()` — use proper error handling
+- Copyright header required: `Copyright 2008-present MongoDB, Inc.`
+- Every public package must have a `package-info.java`
+
+## Testing
+
+- Every code change must include tests.
+  Do not reduce coverage.
+- See [`.agents/skills/testing-guide`](.agents/skills/testing-guide/SKILL.md) for framework details and running specific
+  tests.
+- See [`.agents/skills/spec-tests`](.agents/skills/spec-tests/SKILL.md) for MongoDB specification test conventions.
+
+## API
+
+All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in public APIs.
+See [`.agents/skills/api-design`](.agents/skills/api-design/SKILL.md) for stability annotations and design principles.
+
+## Do Not Modify Without Human Approval
+
+- Wire protocol / authentication handshakes (`com.mongodb.internal.connection`)
+- Connection pool core code (`com.mongodb.internal.connection.pool`)
+- Security-critical encryption code / JNA bindings (`mongodb-crypt`)
+- Public API contracts (breaking changes need major version bump)
+- BSON specification compliance
+- Spec test data submodule (`testing/resources/specifications/`)
+- Release/versioning scripts, `.evergreen/` config, credentials/secrets
+
+See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation and patch builds.
+
+## Before Submitting
+
+```bash
+./gradlew spotlessApply doc check scalaCheck   # formatting + Docs + static checks + all tests
+```
@@ -0,0 +1 @@
+@AGENTS.md
@@ -125,6 +125,18 @@ $ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend
 If you encounter `"Too many open files"` errors when running the tests then you will need to increase 
 the number of available file descriptors prior to starting mongod as described in [https://www.mongodb.com/docs/manual/reference/ulimit/](https://www.mongodb.com/docs/manual/reference/ulimit/)
 
+## AI Agent Configuration
+
+This repository uses [agentskills.io](https://agentskills.io) conventions for AI coding
+agent instructions. `AGENTS.md` is the canonical source of truth — tool-specific files
+like `CLAUDE.md` are generated references.
+
+### Adding a nested AGENTS.md
+
+1. Create an `AGENTS.md` in the target directory.
+2. Run `scripts/symlink-claude-md.sh` to generate the companion `CLAUDE.md`.
+3. Stage and commit both files.
+
 ## IntelliJ IDEA
 
 A couple of manual configuration steps are required to run the code in IntelliJ: