Skip to content

Commit 82834fb

Browse files
rozzarozza
committed
Added CLAUDE.md instructions
A global general instruction and one per project JAVA-6143
1 parent aea251f commit 82834fb

16 files changed

Lines changed: 432 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# CLAUDE.md - MongoDB Java Driver
2+
3+
Guidelines for AI agents working on the MongoDB Java Driver codebase.
4+
5+
## Project Overview
6+
7+
This is the official MongoDB JVM driver monorepo, providing Java, Kotlin, and Scala
8+
drivers for MongoDB. The driver implements the
9+
[MongoDB Driver Specifications](https://github.com/mongodb/specifications)
10+
and follows semantic versioning.
11+
12+
### Module Structure
13+
14+
| Module | Purpose |
15+
|----------------------------|-----------------------------------------------------------|
16+
| `bson` | BSON library (core serialization) |
17+
| `bson-kotlin` | Kotlin BSON extensions |
18+
| `bson-kotlinx` | Kotlin serialization BSON codec |
19+
| `bson-record-codec` | Java record codec support |
20+
| `bson-scala` | Scala BSON extensions |
21+
| `driver-core` | Core driver internals (connections, protocol, operations) |
22+
| `driver-sync` | Synchronous Java driver |
23+
| `driver-legacy` | Legacy MongoDB Java driver API |
24+
| `driver-reactive-streams` | Reactive Streams driver |
25+
| `driver-kotlin-coroutine` | Kotlin Coroutines driver |
26+
| `driver-kotlin-extensions` | Kotlin driver extensions |
27+
| `driver-kotlin-sync` | Kotlin synchronous driver |
28+
| `driver-scala` | Scala driver |
29+
| `mongodb-crypt` | Client-side field-level encryption |
30+
| `testing` | Shared test resources and MongoDB specifications |
31+
32+
### Internal API Convention
33+
34+
All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API.
35+
It can change at any time without notice. Never expose internal types in
36+
public APIs, and never advise users to depend on them.
37+
38+
### API Stability Annotations
39+
40+
- `@Alpha` - Early development, may be removed. Not for production use.
41+
- `@Beta` - Subject to change or removal. Libraries should not depend on these.
42+
- `@Deprecated` - Supported until next major release but should be migrated away from.
43+
44+
## General
45+
46+
- Follow existing conventions. Keep it simple.
47+
- When stuck: stop, explain the problem, propose alternatives, ask for guidance.
48+
- When uncertain: ask rather than assume. Present options with trade-offs.
49+
50+
## Build System
51+
52+
- **Build tool:** Gradle with Kotlin DSL
53+
- **Build JDK:** Java 17+
54+
- **Source compatibility (baseline):** Java 8 for most modules / main driver artifacts
55+
- **Version catalog:** `gradle/libs.versions.toml`
56+
- **Convention plugins:** `buildSrc/src/main/kotlin/conventions/`
57+
58+
### Essential Build Commands
59+
60+
```bash
61+
# Full validation (static checks + unit tests + integration tests)
62+
./gradlew check
63+
64+
# Integration tests (requires running MongoDB)
65+
./gradlew integrationTest
66+
67+
# Single module tests
68+
./gradlew :driver-core:test
69+
70+
# Format check only
71+
./gradlew spotlessCheck
72+
73+
# Auto-fix formatting
74+
./gradlew spotlessApply
75+
76+
# Test with alternative JDK
77+
./gradlew test -PjavaVersion=11
78+
```
79+
80+
## Code Style and Formatting
81+
82+
Formatting is checked automatically via `./gradlew spotlessCheck` which runs
83+
as part of `check`. Use `./gradlew spotlessApply` to auto-fix formatting issues.
84+
Do not manually reformat files outside the scope of your changes.
85+
86+
### Style Rules
87+
88+
- **Max line length:** 140 characters
89+
- **Indentation:** 4 spaces (no tabs)
90+
- **Line endings:** LF (Unix)
91+
- **Charset:** UTF-8
92+
- **Star imports:** Prohibited (AvoidStarImport)
93+
- **Final parameters:** Required (FinalParameters checkstyle rule)
94+
- **Braces:** Required for all control structures (NeedBraces)
95+
- **Else placement:** On its own line (not cuddled)
96+
- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
97+
98+
### Prohibited Patterns
99+
100+
- `System.out.println` / `System.err.println` — Use SLF4J logging
101+
- `e.printStackTrace()` — Use proper logging/error handling
102+
103+
## Testing
104+
105+
### Frameworks
106+
107+
- **JUnit 5** (Jupiter) - Primary unit test framework
108+
- **Spock** (Groovy) - Legacy, do not add new Spock tests.
109+
- **Mockito** - Mocking
110+
- **ScalaTest** - Scala module testing
111+
112+
### Writing Tests
113+
114+
- **Every code change must include tests.** New code needs new tests; modified code needs updated tests. Do not reduce test coverage.
115+
- Extend existing test patterns in the module you are modifying
116+
- Unit tests should not require a running MongoDB instance
117+
- Test methods should be descriptive:
118+
prefer `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`,
119+
use `@DisplayName` for a human readable name
120+
- Clean up test data in `@AfterEach` / `cleanup()` to prevent test pollution
121+
122+
### MongoDB Specifications and Specification Tests
123+
124+
The driver implements the [MongoDB Specifications](https://github.com/mongodb/specifications). Specification test data files live in
125+
`testing/resources/specifications/` — a git submodule for test resources. When modifying driver specification-related behavior: do
126+
not modify existing specification tests unless they test incorrect behavior. Create new tests instead.
127+
128+
## Core Development Principles
129+
130+
### Essential Rules
131+
132+
- **Read before modifying.** Understand existing code and patterns before making changes.
133+
- **Minimal changes only.** No drive-by refactoring.
134+
- **Preserve existing comments.** Only remove comments that are provably incorrect.
135+
- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of the task.
136+
- **No rewrites** without explicit permission.
137+
138+
### Search Before Implementing
139+
140+
Before writing new code, search the codebase for existing implementations:
141+
142+
- Check if a utility method already exists in `com.mongodb.internal.*`
143+
- Check if a similar pattern is established elsewhere in the module
144+
- Reuse existing well-tested infrastructure over creating duplicates
145+
146+
### API Design
147+
148+
- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
149+
- **Information hiding:** Bury complexity behind simple interfaces.
150+
- **Pull complexity downward:** Make the implementer work harder so callers work less.
151+
- **General-purpose over special-case:** Fewer flexible methods over many specialized ones.
152+
- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them.
153+
154+
## Dependency Management
155+
156+
Dependencies are managed centrally via `gradle/libs.versions.toml`.
157+
158+
- **Never add dependencies without justification.** Dependencies are liabilities.
159+
- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms.
160+
- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths.
161+
- Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime.
162+
163+
## Safety Rules - Do Not Modify Without Review
164+
165+
- Wire protocol implementation (connection/authentication handshakes)
166+
- Security-critical authentication and encryption code
167+
- Public API contracts (breaking changes require major version bump)
168+
- BSON specification compliance
169+
- Configuration files containing credentials or secrets
170+
- CI/CD pipeline configurations in `.evergreen/`
171+
- Release and publishing scripts
172+
173+
## CI/CD
174+
175+
### Evergreen (MongoDB Internal CI)
176+
177+
Primary CI runs on MongoDB's Evergreen system. Configuration is in `.evergreen/`.
178+
179+
### Before Submitting
180+
181+
Run locally at minimum:
182+
183+
```bash
184+
./gradlew spotlessApply # Fix formatting
185+
./gradlew check scalaCheck # Static checks + unit tests (Java + Scala)
186+
```

‎bson-kotlin/CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CLAUDE.md - bson-kotlin
2+
3+
Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support.
4+
5+
## Key Packages
6+
7+
- `org.bson.codecs.kotlin` — Kotlin-specific codecs with inline reified functions
8+
9+
## Notes
10+
11+
- Formatting: ktfmt dropbox style, max width 120

‎bson-kotlinx/CLAUDE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# CLAUDE.md - bson-kotlinx
2+
3+
Kotlinx serialization integration for BSON, providing a pluggable serialization format.
4+
5+
## Key Packages
6+
7+
- `org.bson.codecs.kotlinx` — Kotlinx serialization BSON format support
8+
- `org.bson.codecs.kotlinx.utils` — Helper utilities
9+
10+
## Notes
11+
12+
- Formatting: ktfmt dropbox style, max width 120

‎bson-record-codec/CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CLAUDE.md - bson-record-codec
2+
3+
Java record codec support for BSON serialization. **Requires Java 17+.**
4+
5+
## Key Packages
6+
7+
- `org.bson.codecs.record` — `RecordCodecProvider` and record field accessors
8+
9+
## Notes
10+
11+
- Every package must have a `package-info.java`

‎bson-scala/CLAUDE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# CLAUDE.md - bson-scala
2+
3+
Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs.
4+
5+
**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root `gradle.properties`). Default: 2.13.
6+
7+
See [README.md](./README.md) for full details on directory layout, formatting, and testing commands.
8+
9+
## Key Packages
10+
11+
- `org.mongodb.scala.bson` — Core Scala BSON wrappers
12+
- `org.mongodb.scala.bson.codecs` — Macro-based codecs (Scala 2/3)
13+
- `org.mongodb.scala.bson.collection` — Immutable/mutable collection support
14+
- `org.mongodb.scala.bson.annotations` — Field annotations
15+
16+
## Before Submitting
17+
18+
```bash
19+
./gradlew spotlessApply # Fix formatting
20+
./gradlew :bson-scala:scalaCheck # Static checks + tests (default Scala version)
21+
./gradlew :bson-scala:scalaCheck -PscalaVersion=<version> # Test specific Scala version
22+
```

‎bson/CLAUDE.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# CLAUDE.md - bson
2+
3+
Core BSON (Binary JSON) library. This is the foundation module — all other modules depend on it.
4+
5+
## Key Packages
6+
7+
- `org.bson` — Core BSON value types (`BsonDocument`, `BsonValue`, `BsonReader`, `BsonWriter`)
8+
- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`)
9+
- `org.bson.codecs.configuration` — Codec registry and provider infrastructure (`CodecRegistry`, `CodecProvider`)
10+
- `org.bson.codecs.pojo` — POJO codec support with conventions and property modeling
11+
- `org.bson.codecs.jsr310` — Java 8+ date/time codec support
12+
- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`, `JsonMode`)
13+
- `org.bson.io` — Binary I/O (`ByteBuffer`, `OutputBuffer`)
14+
- `org.bson.types` — Legacy types (`ObjectId`, `Decimal128`, etc.)
15+
- `org.bson.internal` — Private API (vector support, encoding utilities)
16+
17+
## Notes
18+
19+
- Every package must have a `package-info.java`
20+
- JUnit 5 + Spock (Groovy) tests in both unit and functional dirs
21+
22+
## Key Patterns
23+
24+
- Codec-based serialization with type-safe `BsonValue` hierarchy
25+
- `BsonDocument` implements `Map<String, BsonValue>`
26+
- All public types in `org.bson` — internal types in `org.bson.internal`

‎driver-core/CLAUDE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# CLAUDE.md - driver-core
2+
3+
Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module.
4+
5+
## Key Packages (Public API)
6+
7+
- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`, `Aggregates`, `Sorts`, `Indexes`
8+
- `com.mongodb.client.model.search` — Atlas Search configuration
9+
- `com.mongodb.client.result` — Operation result types (`InsertOneResult`, `DeleteResult`, etc.)
10+
- `com.mongodb.connection` — `ClusterSettings`, `ClusterDescription`
11+
- `com.mongodb.event` — Listeners for commands, connections, servers, cluster events
12+
- `com.mongodb.session` — `ClientSession` interface
13+
- `com.mongodb.bulk` — `WriteModel` hierarchy
14+
15+
## Key Packages (Internal — Private API)
16+
17+
- `com.mongodb.internal.connection` — Socket, wire protocol, command execution
18+
- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate, etc.)
19+
- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC
20+
- `com.mongodb.internal.async` — Async operation framework
21+
- `com.mongodb.internal.binding` — Server binding strategies
22+
- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection implementations
23+
24+
## Notes
25+
26+
- Every package must have a `package-info.java`
27+
- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito. Match surrounding patterns carefully.
28+
- `BuildConfig` is auto-generated by the `com.github.gmazzo.buildconfig` Gradle plugin — run `./gradlew generateBuildConfig` if missing
29+
- Never block in async code paths
30+
31+
## Key Patterns
32+
33+
- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
34+
- Fluent builders: `MongoClientSettings.builder()`
35+
- Abstract core with pluggable transports

‎driver-kotlin-coroutine/CLAUDE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# CLAUDE.md - driver-kotlin-coroutine
2+
3+
Kotlin Coroutines driver providing `suspend` function-based async API.
4+
5+
## Key Packages
6+
7+
- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, `MongoDatabase`, `MongoCollection`)
8+
9+
## Notes
10+
11+
- Formatting: ktfmt dropbox style, max width 120
12+
- Suspend functions wrapping `driver-reactive-streams` — never block
13+
- Built on `kotlinx-coroutines`

‎driver-kotlin-extensions/CLAUDE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# CLAUDE.md - driver-kotlin-extensions
2+
3+
Kotlin extensions providing type-safe DSLs for query and update construction.
4+
5+
## Key Packages
6+
7+
- `com.mongodb.kotlin.client.model` — Type-safe DSL builders (`Filters`, `Updates`, `Aggregates`, `Sorts`, `Projections`, `Indexes`)
8+
- `com.mongodb.kotlin.client.property` — `KPropertyPath` for property-based queries
9+
10+
## Notes
11+
12+
- Formatting: ktfmt dropbox style, max width 120
13+
- Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine`

‎driver-kotlin-sync/CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CLAUDE.md - driver-kotlin-sync
2+
3+
Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-sync`.
4+
5+
## Key Packages
6+
7+
- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`)
8+
9+
## Notes
10+
11+
- Formatting: ktfmt dropbox style, max width 120

0 commit comments

Comments
 (0)