Skip to content

Commit 1646567

Browse files
rozzarozza
committed
Add AI agent instructions using the AGENTS.md open standard
Adds structured AI agent documentation across the MongoDB Java Driver using the AGENTS.md convention — an open standard for providing codebase context to AI coding agents. - Root AGENTS.md with build commands, style rules, testing policy, API design guidelines, safety-critical code boundaries, and dependency rules - Per-module AGENTS.md files (bson, driver-core, driver-sync, etc.) with module-specific packages, dependencies, and patterns - CLAUDE.md files that reference AGENTS.md (for Claude Code compatibility) - `.agents/references/` for passive knowledge (contextually loaded): project-guide, style-reference, api-design, testing-guide, spec-tests - `.agents/skills/` for procedural workflows: evergreen (CI validation), sync-agents-docs (documentation sync checklist) - `scripts/symlink-claude-md.sh` for maintaining CLAUDE.md symlinks - References over skills for static knowledge: references are loaded contextually based on description relevance rather than requiring explicit invocation. This avoids bloating every conversation with all documentation while still surfacing it when needed. - Flat file layout for references (.agents/references/api-design.md) rather than directory-per-reference (.agents/references/api-design/REFERENCE.md): simpler structure; supplementary files use name-prefixing (e.g. testing-guide-examples.md) instead of subdirectories. - Markdown links (See [name](path)) rather than @ syntax for referencing from AGENTS.md: @ auto-includes file contents on every load, which defeats contextual loading. Links let agents follow them on demand. - Skills retained only for procedural workflows that have tool constraints (allowed-tools) or explicit trigger conditions (disable-model-invocation), not for passive knowledge lookup. JAVA-6143
1 parent 91c312c commit 1646567

114 files changed

Lines changed: 1816 additions & 2042 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/references/api-design.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: api-design
3+
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.
4+
---
5+
# API Design
6+
7+
## API Stability Annotations
8+
9+
- `@Alpha` — Early development, may be removed.
10+
Not recommended for production use.
11+
- `@Beta` — Subject to change or removal.
12+
It's not recommended for Libraries to depend on these APIs.
13+
- `@Evolving` — May add abstract methods in future releases.
14+
Safe to use, but implementing/extending bears upgrade risk.
15+
- `@Sealed` — Must not be extended or implemented by consumers.
16+
Safe to use, but not to subclass.
17+
- `@Deprecated` — Supported until next major release but should be migrated away from.
18+
19+
## Design Principles
20+
21+
- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
22+
- **Information hiding:** Bury complexity behind simple interfaces.
23+
- **Pull complexity downward:** Make the implementer work harder so callers work less.
24+
- **General-purpose over special-case:** Fewer flexible methods over many specialized ones.
25+
- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them.
26+
27+
## Key Patterns
28+
29+
- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
30+
- Fluent builders: `MongoClientSettings.builder()` is the primary entry point
31+
- Abstract core with pluggable transports

‎.agents/references/project-guide.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
name: project-guide
3+
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.
4+
---
5+
# Project Guide
6+
7+
## Project Structure
8+
9+
| Project | Purpose |
10+
| --- | --- |
11+
| `bson` | BSON library (core serialization) |
12+
| `bson-kotlin` | Kotlin BSON extensions |
13+
| `bson-kotlinx` | Kotlin serialization BSON codec |
14+
| `bson-record-codec` | Java record codec support |
15+
| `bson-scala` | Scala BSON extensions |
16+
| `driver-core` | Core driver internals (connections, protocol, operations) |
17+
| `driver-sync` | Synchronous Java driver |
18+
| `driver-legacy` | Legacy MongoDB Java driver API |
19+
| `driver-reactive-streams` | Reactive Streams driver |
20+
| `driver-kotlin-coroutine` | Kotlin Coroutines driver |
21+
| `driver-kotlin-extensions` | Kotlin driver extensions |
22+
| `driver-kotlin-sync` | Kotlin synchronous driver |
23+
| `driver-scala` | Scala driver |
24+
| `mongodb-crypt` | Client-side field-level encryption |
25+
| `bom` | Bill of Materials for dependency management |
26+
| `testing` | Shared test resources and MongoDB specifications |
27+
| `buildSrc` | Gradle convention plugins and build infrastructure |
28+
| `driver-benchmarks` | JMH and custom performance benchmarks (not published) |
29+
| `driver-lambda` | AWS Lambda test application (not published) |
30+
| `graalvm-native-image-app` | GraalVM Native Image compatibility testing (not published) |
31+
32+
## Dependency Graph (simplified)
33+
34+
```
35+
bson
36+
├── bson-kotlin
37+
├── bson-kotlinx
38+
├── bson-record-codec
39+
├── bson-scala
40+
└── driver-core
41+
├── driver-sync
42+
│ ├── driver-legacy
43+
│ ├── driver-kotlin-sync
44+
│ └── driver-lambda
45+
├── driver-reactive-streams
46+
│ ├── driver-kotlin-coroutine
47+
│ └── driver-scala
48+
└── driver-kotlin-extensions
49+
```
50+
51+
## Finding the Right Module
52+
53+
- **BSON serialization/codecs:** `bson` (or `bson-kotlin`/`bson-kotlinx`/`bson-scala` for language-specific)
54+
- **Query builders, filters, aggregates:** `driver-core` (`com.mongodb.client.model`)
55+
- **Sync Java API:** `driver-sync`
56+
- **Reactive API:** `driver-reactive-streams`
57+
- **Kotlin coroutines:** `driver-kotlin-coroutine`
58+
- **Kotlin DSL builders:** `driver-kotlin-extensions`
59+
- **Scala driver:** `driver-scala`
60+
- **Connection, protocol, auth internals:** `driver-core` (`com.mongodb.internal.*`)
61+
- **Build plugins, formatting, test infra:** `buildSrc`
62+
63+
Each module has its own `AGENTS.md` with module-specific packages, patterns, and notes.

‎.agents/references/spec-tests.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: spec-tests
3+
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.
4+
---
5+
# MongoDB Specification Tests
6+
7+
## Overview
8+
9+
The driver implements the [MongoDB Driver Specifications](https://github.com/mongodb/specifications).
10+
Specification test data files live in `testing/resources/specifications/` — a git submodule.
11+
12+
## Rules
13+
14+
- **Do not modify spec test data files** (JSON/YAML in `testing/resources/specifications/`) — managed upstream
15+
- Test runners (Java code) may be modified to fix bugs or add support for new spec tests
16+
- Update the submodule via `git submodule update`
17+
18+
## Structure
19+
20+
Spec test data is organized by specification area:
21+
22+
- CRUD, SDAM, auth, CSFLE, retryable operations, and more
23+
- Each spec area has JSON/YAML test data files defining inputs and expected outputs
24+
- Driver test runners parse these files and execute against the driver
25+
26+
## Test Data Location
27+
28+
```
29+
testing/
30+
resources/
31+
specifications/ # Git submodule — do not edit directly
32+
logback-test.xml # Shared logback configuration for tests
33+
```
34+
35+
## Adding Spec Test Support
36+
37+
1. Check `testing/resources/specifications/` for the relevant spec test data
38+
2. Find existing test runners in the module (look for `*SpecificationTest*` or similar)
39+
3. Extend existing patterns — each module handles spec tests slightly differently
40+
4. Ensure tests run with `./gradlew check` or the module’s test task

‎.agents/references/style-reference.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
name: style-reference
3+
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.
4+
---
5+
# Style Reference
6+
7+
## Java Style Rules
8+
9+
- **Max line length:** 140 characters
10+
- **Indentation:** 4 spaces (no tabs)
11+
- **Line endings:** LF (Unix)
12+
- **Charset:** UTF-8
13+
- **Star imports:** Prohibited (AvoidStarImport)
14+
- **Final parameters:** Required (FinalParameters checkstyle rule)
15+
- **Braces:** Required for all control structures (NeedBraces)
16+
- **Else placement:** `} else {` on the same line (Palantir Java Format default)
17+
- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
18+
- **Formatter:** Palantir Java Format
19+
20+
## Kotlin Style Rules
21+
22+
- **Formatter:** ktfmt dropbox style, max width 120
23+
- **Static analysis:** detekt
24+
25+
## Scala Style Rules
26+
27+
- **Formatter:** scalafmt
28+
- **Supported versions:** 2.11, 2.12, 2.13, 3 (default: 2.13)
29+
30+
## Groovy Style Rules
31+
32+
- **Static analysis:** CodeNarc
33+
34+
## Javadoc / KDoc / Scaladoc
35+
36+
- All public classes and interfaces **must** have class-level Javadoc (enforced by checkstyle)
37+
- Public methods should have Javadoc with `@param`, `@return`, and `@since` tags
38+
- Use `@since X.Y` to indicate the version when the API was introduced
39+
- Use `@mongodb.driver.manual <path> <label>` for MongoDB manual links
40+
- Use `@mongodb.server.release <version>` to indicate the minimum server version required
41+
- Scala modules use Scaladoc — follow Scaladoc conventions (`@param`, `@return`, `@since`, `@see`)
42+
- Internal packages (`com.mongodb.internal.*`, `org.bson.internal.*`) are excluded from doc generation
43+
- Run `./gradlew doc` to validate Javadoc/KDoc/Scaladoc builds cleanly
44+
45+
## Prohibited Patterns
46+
47+
- `System.out.println` / `System.err.println` — Use SLF4J logging
48+
- `e.printStackTrace()` — Use proper logging/error handling
49+
50+
## Formatting Commands
51+
52+
```bash
53+
./gradlew spotlessApply # Auto-fix all formatting
54+
./gradlew spotlessCheck # Check without modifying
55+
```

‎.agents/references/testing-guide-examples.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
name: testing-guide-examples
3+
description: Test skeleton templates for Java (JUnit 5), Scala (ScalaTest), and Kotlin (kotlin.test) in the MongoDB Java Driver. Use when writing new tests to match structural conventions.
4+
---
5+
# Test Skeletons
6+
7+
Match these structural conventions when writing new tests.
8+
9+
## Java — JUnit 5
10+
11+
```java
12+
public class FeatureUnderTestTest extends OperationTest {
13+
14+
private ResourceType resource;
15+
16+
@BeforeEach
17+
void setup() {
18+
// Insert test data, acquire resources
19+
}
20+
21+
@AfterEach
22+
void cleanup() {
23+
// Release resources to prevent leaks
24+
}
25+
26+
@Test
27+
@DisplayName("should do expected behavior")
28+
void shouldDoExpectedBehavior() {
29+
// given
30+
// when
31+
// then
32+
}
33+
34+
@ParameterizedTest(name = "{index} => input={0}, expected={1}")
35+
@MethodSource
36+
@DisplayName("should handle varied inputs")
37+
void shouldHandleVariedInputs(final int input, final int expected) {
38+
assertEquals(expected, methodUnderTest(input));
39+
}
40+
41+
private static Stream<Arguments> shouldHandleVariedInputs() {
42+
return Stream.of(arguments(1, 1), arguments(2, 4));
43+
}
44+
}
45+
```
46+
47+
## Scala — ScalaTest with Mockito
48+
49+
```scala
50+
class FeatureUnderTestSpec extends BaseSpec with MockitoSugar {
51+
52+
val wrapped = mock[JWrappedType]
53+
val underTest = new ScalaWrapper(wrapped)
54+
55+
"ScalaWrapper" should "have the same methods as the wrapped type" in {
56+
val wrappedMethods = classOf[JWrappedType].getMethods.map(_.getName).toSet
57+
val localMethods = classOf[ScalaWrapper].getMethods.map(_.getName)
58+
// Assert parity
59+
}
60+
61+
it should "delegate to underlying method" in {
62+
underTest.someMethod("arg")
63+
verify(wrapped).someMethod("arg")
64+
}
65+
}
66+
```
67+
68+
## Kotlin — kotlin.test with Mockito-Kotlin
69+
70+
```kotlin
71+
class FeatureUnderTestTest {
72+
73+
companion object {
74+
@Mock internal val wrapped: com.mongodb.client.MongoCollection<MyType> = mock()
75+
lateinit var collection: MongoCollection<MyType>
76+
77+
@JvmStatic
78+
@BeforeAll
79+
internal fun setUpMocks() {
80+
collection = MongoCollection(wrapped)
81+
whenever(wrapped.namespace).doReturn(MongoNamespace("db", "coll"))
82+
}
83+
}
84+
85+
@Test
86+
fun shouldProduceCorrectBson() {
87+
assertEquals(BsonDocument.parse("""{"expected": 1}"""), resultUnderTest.toBsonDocument())
88+
}
89+
90+
data class MyType(val id: String, val name: String)
91+
}
92+
```

‎.agents/references/testing-guide.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: testing-guide
3+
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.
4+
---
5+
# Testing Guide
6+
7+
## Frameworks
8+
9+
| Framework | Usage | Notes |
10+
| --- | --- | --- |
11+
| JUnit 5 (Jupiter) | Primary unit test framework | All new tests |
12+
| Spock (Groovy) | Legacy tests | Do not add new Spock tests |
13+
| Mockito | Mocking | Use `mockito-junit-jupiter` integration |
14+
| ScalaTest | Scala module testing | FlatSpec + ShouldMatchers |
15+
| Project Reactor | Reactive test utilities | `driver-reactive-streams` tests |
16+
17+
## Assertions
18+
19+
- **JUnit Jupiter Assertions** (`org.junit.jupiter.api.Assertions`) is the standard for all new tests
20+
- Hamcrest matchers appear in older tests but should not be used in new code
21+
- AssertJ is in the dependency catalog but is not used — do not introduce it
22+
- Spock tests use Spock's built-in `expect:`/`then:` assertions (no external assertion library)
23+
24+
## Writing Tests
25+
26+
- Every code change must include tests
27+
- Extend existing test patterns in the module you are modifying
28+
- Unit tests must not require a running MongoDB instance
29+
- Descriptive method names: `shouldReturnEmptyListWhenNoDocumentsMatch()` not `test1()`
30+
- Use `@DisplayName` for human-readable names
31+
- Clean up test data in `@AfterEach` / `cleanup()` to prevent pollution
32+
33+
## Running Tests
34+
35+
```bash
36+
# All tests (unit + integration)
37+
./gradlew check
38+
39+
# Single module
40+
./gradlew :driver-core:test
41+
42+
# Integration tests (requires MongoDB)
43+
./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
44+
45+
# Specific test class
46+
./gradlew :driver-core:test --tests "com.mongodb.internal.operation.FindOperationTest"
47+
48+
# Alternative JDK
49+
./gradlew test -PjavaVersion=11
50+
51+
# Scala tests (all versions)
52+
./gradlew scalaCheck
53+
```
54+
55+
## Module-Specific Notes
56+
57+
- **driver-core:** Largest test suite — JUnit 5 + Spock + Mockito
58+
- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don’t add new)
59+
- **driver-reactive-streams:** JUnit 5 + Spock + Project Reactor
60+
- **bson-scala / driver-scala:** ScalaTest, test per Scala version
61+
- **Kotlin modules:** JUnit 5 + mockito-kotlin
62+
63+
## Integration Tests
64+
65+
- Require a running MongoDB instance
66+
- Set connection URI: `-Dorg.mongodb.test.uri="mongodb://localhost:27017"`
67+
- Integration test source set configured via `conventions/testing-integration.gradle.kts`
68+
69+
See [testing-guide-examples.md](testing-guide-examples.md) for Java, Scala, and Kotlin test skeletons.

‎.agents/skills/evergreen/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: evergreen
3+
description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix.
4+
disable-model-invocation: true
5+
allowed-tools: Bash(evergreen *)
6+
---
7+
# Evergreen
8+
9+
## Evergreen (MongoDB Internal CI)
10+
11+
Primary CI runs on MongoDB’s Evergreen system.
12+
Configuration lives in `.evergreen/`.
13+
14+
- Do not modify `.evergreen/` configuration without review
15+
- Evergreen runs the full test matrix across MongoDB versions, OS platforms, and JDK versions
16+
17+
## Validating Evergreen Configuration
18+
19+
After modifying `.evergreen/` files, validate the config locally:
20+
21+
```bash
22+
evergreen validate .evergreen/.evg.yml
23+
```
24+
25+
Always run this before submitting changes to `.evergreen/` to catch syntax errors and invalid task definitions.
26+
27+
## Testing with a Patch Build
28+
29+
To test your changes on Evergreen before merging, create a patch build:
30+
31+
```bash
32+
evergreen patch -u
33+
```
34+
35+
This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI
36+
test matrix against your branch.

0 commit comments

Comments
 (0)