Skip to content

Commit 2fa4cda

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

File tree

16 files changed

+420
-0
lines changed

16 files changed

+420
-0
lines changed

‎CLAUDE.md‎

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

‎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 `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=<scalaVersion> # Per Scala version
22+
```

‎bson/CLAUDE.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
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`, `CodecRegistry`)
9+
- `org.bson.codecs.pojo` — POJO codec support with conventions and property modeling
10+
- `org.bson.codecs.jsr310` — Java 8+ date/time codec support
11+
- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`, `JsonMode`)
12+
- `org.bson.io` — Binary I/O (`ByteBuffer`, `OutputBuffer`)
13+
- `org.bson.types` — Legacy types (`ObjectId`, `Decimal128`, etc.)
14+
- `org.bson.internal` — Private API (vector support, encoding utilities)
15+
16+
## Notes
17+
18+
- Every package must have a `package-info.java`
19+
- JUnit 5 + Spock (Groovy) tests in both unit and functional dirs
20+
21+
## Key Patterns
22+
23+
- Codec-based serialization with type-safe `BsonValue` hierarchy
24+
- `BsonDocument` implements `Map<String, BsonValue>`
25+
- 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 — 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.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: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
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` — Query and update DSLs (`FilterDsl`, `UpdateDsl`, `AggregateBuilder`)
8+
9+
## Notes
10+
11+
- Formatting: ktfmt dropbox style, max width 120
12+
- 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)