Skip to content

Commit 935f140

Browse files
rozzarozza
committed
Added CLAUDE.md instructions
A global general instruction and one per project JAVA-6143
1 parent c956d94 commit 935f140

File tree

17 files changed

+521
-0
lines changed

17 files changed

+521
-0
lines changed

‎CLAUDE.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
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+
- `@Evolving` - May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk.
43+
- `@Sealed` - Must not be extended or implemented by consumers. Safe to use, but not to subclass.
44+
- `@Deprecated` - Supported until next major release but should be migrated away from.
45+
46+
## General
47+
48+
- Follow existing conventions. Keep it simple.
49+
- When stuck: stop, explain the problem, propose alternatives, ask for guidance.
50+
- When uncertain: ask rather than assume. Present options with trade-offs.
51+
52+
## Build System
53+
54+
- **Build tool:** Gradle with Kotlin DSL
55+
- **Build JDK:** Java 17+
56+
- **Source compatibility (baseline):** Java 8 for most modules / main driver artifacts
57+
- **Version catalog:** `gradle/libs.versions.toml`
58+
- **Convention plugins:** `buildSrc/src/main/kotlin/conventions/`
59+
60+
### Essential Build Commands
61+
62+
```bash
63+
# Full validation (static checks + unit tests + integration tests)
64+
./gradlew check
65+
66+
# Integration tests (requires running MongoDB)
67+
./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
68+
69+
# Single module tests
70+
./gradlew :driver-core:test
71+
72+
# Format check only
73+
./gradlew spotlessCheck
74+
75+
# Auto-fix formatting
76+
./gradlew spotlessApply
77+
78+
# Test with alternative JDK
79+
./gradlew test -PjavaVersion=11
80+
```
81+
82+
## Code Style and Formatting
83+
84+
Formatting is enforced automatically because the Gradle `check` task depends on
85+
`./gradlew spotlessApply`, which formats sources. To run a check without modifying
86+
files, invoke `./gradlew spotlessCheck` manually. Do not manually reformat files
87+
outside the scope of your changes.
88+
89+
### Style Rules
90+
91+
- **Max line length:** 140 characters
92+
- **Indentation:** 4 spaces (no tabs)
93+
- **Line endings:** LF (Unix)
94+
- **Charset:** UTF-8
95+
- **Star imports:** Prohibited (AvoidStarImport)
96+
- **Final parameters:** Required (FinalParameters checkstyle rule)
97+
- **Braces:** Required for all control structures (NeedBraces)
98+
- **Else placement:** On its own line (not cuddled)
99+
- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
100+
101+
### Prohibited Patterns
102+
103+
- `System.out.println` / `System.err.println` — Use SLF4J logging
104+
- `e.printStackTrace()` — Use proper logging/error handling
105+
106+
## Testing
107+
108+
### Frameworks
109+
110+
- **JUnit 5** (Jupiter) - Primary unit test framework
111+
- **Spock** (Groovy) - Legacy, do not add new Spock tests.
112+
- **Mockito** - Mocking
113+
- **ScalaTest** - Scala module testing
114+
115+
### Writing Tests
116+
117+
- **Every code change must include tests.** New code needs new tests; modified code needs updated tests. Do not reduce test coverage.
118+
- Extend existing test patterns in the module you are modifying
119+
- Unit tests should not require a running MongoDB instance
120+
- Test methods should be descriptive:
121+
prefer `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`,
122+
use `@DisplayName` for a human readable name
123+
- Clean up test data in `@AfterEach` / `cleanup()` to prevent test pollution
124+
125+
### MongoDB Specifications and Specification Tests
126+
127+
The driver implements the [MongoDB Specifications](https://github.com/mongodb/specifications). Specification test data files live in
128+
`testing/resources/specifications/` — a git submodule for test resources. When modifying driver specification-related behavior: do
129+
not modify existing specification tests unless they test incorrect behavior. Create new tests instead.
130+
131+
## Core Development Principles
132+
133+
### Essential Rules
134+
135+
- **Read before modifying.** Understand existing code and patterns before making changes.
136+
- **Minimal changes only.** No drive-by refactoring.
137+
- **Preserve existing comments.** Only remove comments that are provably incorrect.
138+
- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of the task.
139+
- **No rewrites** without explicit permission.
140+
141+
### Search Before Implementing
142+
143+
Before writing new code, search the codebase for existing implementations:
144+
145+
- Check if a utility method already exists in `com.mongodb.internal.*`
146+
- Check if a similar pattern is established elsewhere in the module
147+
- Reuse existing well-tested infrastructure over creating duplicates
148+
149+
### API Design
150+
151+
- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
152+
- **Information hiding:** Bury complexity behind simple interfaces.
153+
- **Pull complexity downward:** Make the implementer work harder so callers work less.
154+
- **General-purpose over special-case:** Fewer flexible methods over many specialized ones.
155+
- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them.
156+
157+
## Dependency Management
158+
159+
Dependencies are managed centrally via `gradle/libs.versions.toml`.
160+
161+
- **Never add dependencies without justification.** Dependencies are liabilities.
162+
- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms.
163+
- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths.
164+
- Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime.
165+
166+
## Safety Rules - Do Not Modify Without Review
167+
168+
- Wire protocol implementation (connection/authentication handshakes)
169+
- Security-critical authentication and encryption code
170+
- Public API contracts (breaking changes require major version bump)
171+
- BSON specification compliance
172+
- Configuration files containing credentials or secrets
173+
- CI/CD pipeline configurations in `.evergreen/`
174+
- Release and publishing scripts
175+
176+
## CI/CD
177+
178+
### Evergreen (MongoDB Internal CI)
179+
180+
Primary CI runs on MongoDB's Evergreen system. Configuration is in `.evergreen/`.
181+
182+
### Before Submitting
183+
184+
Run locally at minimum:
185+
186+
```bash
187+
./gradlew doc check scalaCheck # Generates docs, runs static checks + tests
188+
```

‎bson-kotlin/CLAUDE.md‎

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

‎bson-kotlinx/CLAUDE.md‎

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

‎bson-record-codec/CLAUDE.md‎

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

‎bson-scala/CLAUDE.md‎

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

‎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`

‎buildSrc/CLAUDE.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# CLAUDE.md - buildSrc
2+
3+
Gradle build infrastructure providing convention plugins and shared configuration for all modules.
4+
5+
## Key Directories
6+
7+
- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, testing, publishing, static analysis)
8+
- `src/main/kotlin/project/` — Base project plugins for Java, Kotlin, and Scala modules
9+
- `src/main/kotlin/ProjectExtensions.kt` — Shared Gradle extension utilities
10+
11+
## Convention Plugins
12+
13+
| Plugin | Purpose |
14+
|-----------------------------------------|-----------------------------------------------------------------------------------|
15+
| `spotless` | Code formatting (Java: Palantir; Kotlin: ktfmt dropbox, max 120; Scala: scalafmt) |
16+
| `codenarc` | Groovy static analysis |
17+
| `detekt` | Kotlin static analysis |
18+
| `spotbugs` | Java bug detection |
19+
| `bnd` | OSGi bundle metadata |
20+
| `dokka` | Kotlin documentation generation |
21+
| `javadoc` | Java documentation generation |
22+
| `scaladoc` | Scala documentation generation |
23+
| `publishing` | Maven Central publishing configuration |
24+
| `git-version` | Version derivation from git tags |
25+
| `optional` | Optional dependency support (`optionalImplementation`) |
26+
| `testing-base` | Shared test configuration |
27+
| `testing-integration` | Integration test source set and tasks |
28+
| `testing-junit` | JUnit 5 test setup |
29+
| `testing-junit-vintage` | JUnit 4 compatibility |
30+
| `testing-spock` | Spock framework setup |
31+
| `testing-spock-exclude-slow` | Spock with slow test exclusion |
32+
| `testing-mockito` | Mockito setup |
33+
| `test-artifacts` | Test artifact sharing between modules |
34+
| `test-artifacts-runtime-dependencies` | Runtime dependency sharing for tests |
35+
| `test-include-optionals` | Include optional dependencies in tests |
36+
37+
## Project Plugins
38+
39+
| Plugin | Purpose |
40+
|------------------|------------------------------------------------------------|
41+
| `project/base` | Common settings for all modules |
42+
| `project/java` | Java module conventions (source compatibility, checkstyle) |
43+
| `project/kotlin` | Kotlin module conventions |
44+
| `project/scala` | Scala module conventions (multi-version support) |
45+
46+
## Notes
47+
48+
- Formatting: ktfmt dropbox style, max width 120 (for buildSrc's own code)
49+
- `check` depends on `spotlessCheck` in buildSrc itself
50+
- Java toolchain is set to Java 17
51+
52+
## Keeping CLAUDE.md Files in Sync
53+
54+
When modifying buildSrc, you **must** update the relevant CLAUDE.md files if your changes affect:
55+
56+
- **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
57+
- **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
58+
- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `CLAUDE.md` "Testing" section and affected module CLAUDE.md files
59+
- **Project plugins added or removed** — update this file's project plugin table
60+
- **Build commands or task names changed** — update the root `CLAUDE.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections

‎driver-core/CLAUDE.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
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+
**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, `mongodb-crypt`
6+
7+
## Key Packages (Public API)
8+
9+
- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`, `Aggregates`, `Sorts`, `Indexes`
10+
- `com.mongodb.client.model.search` — Atlas Search configuration
11+
- `com.mongodb.client.result` — Operation result types (`InsertOneResult`, `DeleteResult`, etc.)
12+
- `com.mongodb.connection` — `ClusterSettings`, `ClusterDescription`
13+
- `com.mongodb.event` — Listeners for commands, connections, servers, cluster events
14+
- `com.mongodb.session` — `ClientSession` interface
15+
- `com.mongodb.bulk` — `WriteModel` hierarchy
16+
17+
## Key Packages (Internal — Private API)
18+
19+
- `com.mongodb.internal.connection` — Socket, wire protocol, command execution
20+
- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate, etc.)
21+
- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC
22+
- `com.mongodb.internal.async` — Async operation framework
23+
- `com.mongodb.internal.binding` — Server binding strategies
24+
- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection implementations
25+
26+
## Notes
27+
28+
- Every package must have a `package-info.java`
29+
- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito. Match surrounding patterns carefully.
30+
- `com.mongodb.internal.build.MongoDriverVersion` is auto-generated by the `com.github.gmazzo.buildconfig` Gradle plugin — run `./gradlew :driver-core:generateMongoDriverVersion` if missing
31+
- Never block in async code paths
32+
33+
## Key Patterns
34+
35+
- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
36+
- Fluent builders: `MongoClientSettings.builder()` is the primary entry point for configuring clients
37+
- Abstract core with pluggable transports

‎driver-kotlin-coroutine/CLAUDE.md‎

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

0 commit comments

Comments
 (0)