Add more instructions

Author: comandeo-mongo

.github/code-review.md

@@ -0,0 +1,38 @@
+# Code Reviews
+
+When reviewing code, focus on:
+
+## Security Critical Issues
+- Check for hardcoded secrets, API keys, or credentials
+- Check for instances of potential method call injection, dynamic code execution, symbol injection or other code injection vulnerabilities.
+
+## Performance Red Flags
+- Spot inefficient loops and algorithmic issues.
+- Check for memory leaks and resource cleanup.
+
+## Code Quality Essentials
+- Methods should be focused and appropriately sized. If a method is doing too much, suggest refactorings to split it up.
+- Use clear, descriptive naming conventions.
+- Avoid encapsulation violations and ensure proper separation of concerns.
+- All public classes, modules, and methods should have clear documentation in YARD format.
+- If `method_missing` is implemented, ensure that `respond_to_missing?` is also implemented.
+- Rubocop is used by this project to enforce code style. Always refer to the project's .rubocop.yml file for guidance on the project's style preferences.
+
+## Driver-specific Concerns
+- Look for code that might cause issues in a multi-threaded (or multi-fiber) environment.
+
+## Review Style
+- Be specific and actionable in feedback
+- Explain the "why" behind recommendations
+- Acknowledge good patterns when you see them
+- Ask clarifying questions when code intent is unclear
+- When possible, suggest that the pull request be labeled as a `bug`, a `feature`, or a `bcbreak` (a "backwards-compatibility break").
+- PR's with no user-visible effect do not need to be labeled.
+- Do not review or suggest changes to YAML files under the `spec/` directory; these are test fixtures shared between all drivers and are not owned by this repository.
+- Flag any new Ruby specs that appear to duplicate behavior already covered by YAML spec tests in `spec/spec_tests/data/`.
+
+Always prioritize security vulnerabilities and performance issues that could impact users.
+
+Always suggest changes to improve readability and testability.
+
+When reviewing code, be encouraging.

AGENTS.md

@@ -1,6 +1,6 @@
 # Project Description
 
-This is the Ruby driver for the MongoDB database. It provides a Ruby interface for connecting to MongoDB, performing CRUD operations, and managing database connections. The API is standardized across all MongoDB drivers, via the specifications defined in the MongoDB Specifications repository: https://github.com/mongodb/specifications.
+This is the Ruby driver for the MongoDB database. It provides a Ruby interface for connecting to MongoDB, performing CRUD operations, and managing database connections. The API is standardized across all MongoDB drivers, via the specifications defined in the MongoDB Specifications repository: https://github.com/mongodb/specifications. The driver targets Ruby 2.7+. Do not use syntax or stdlib features unavailable in Ruby 2.7.
 
 # Project Structure
 
@@ -14,41 +14,53 @@ The project is organized into the following directories:
 - `profile/`: profiling scripts and results
 
 
-# Code Reviews
+# Development Workflow
+
+## Running tests
+
+Tests require a running MongoDB instance. Set the URI via the `MONGODB_URI` environment variable:
+
+```
+MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27019/" bundle exec rspec spec/path/to/spec.rb
+```
+
+A replica set is typically available locally at `localhost:27017,27018,27019`.
+
+## Linting
+
+Run RuboCop after making changes, and always before committing:
+
+```
+bundle exec rubocop lib/mongo/changed_file.rb spec/mongo/changed_file_spec.rb
+```
 
-When reviewing code, focus on:
+Pass the specific files you modified.
 
-## Security Critical Issues
-- Check for hardcoded secrets, API keys, or credentials
-- Check for instances of potential method call injection, dynamic code execution, symbol injection or other code injection vulnerabilities.
+RuboCop is configured with performance, rake, and rspec plugins (`.rubocop.yml`).
 
-## Performance Red Flags
-- Spot inefficient loops and algorithmic issues.
-- Check for memory leaks and resource cleanup.
+## Commit convention
 
-## Code Quality Essentials
-- Methods should be focused and appropriately sized. If a method is doing too much, suggest refactorings to split it up.
-- Use clear, descriptive naming conventions.
-- Avoid encapsulation violations and ensure proper separation of concerns.
-- All public classes, modules, and methods should have clear documentation in YARD format.
-- If `method_missing` is implemented, ensure that `respond_to_missing?` is also implemented.
-- Rubocop is used by this project to enforce code style. Always refer to the project's .rubocop.yml file for guidance on the project's style preferences.
+Prefix commit messages with the JIRA ticket: `RUBY-#### Short description`. The ticket number is typically in the branch name (e.g., branch `3795-foo` means `RUBY-3795`).
 
-## Driver-specific Concerns
-- Look for code that might cause issues in a multi-threaded (or multi-fiber) environment.
+## Prose style
 
-## Review Style
-- Be specific and actionable in feedback
-- Explain the "why" behind recommendations
-- Acknowledge good patterns when you see them
-- Ask clarifying questions when code intent is unclear
-- When possible, suggest that the pull request be labeled as a `bug`, a `feature`, or a `bcbreak` (a "backwards-compatibility break").
-- PR's with no user-visible effect do not need to be labeled.
-- Do not review YAML files under the `spec/` directory; these are test fixtures shared between all drivers.
+When writing prose — commit messages, code comments, documentation — be concise, write as a human would, avoid overly complicated sentences, and use no emojis.
 
-Always prioritize security vulnerabilities and performance issues that could impact users.
+## Definition of done
 
-Always suggest changes to improve readability and testability.
+Always run the relevant spec file(s) against the local cluster before considering a task complete. Running tests is not optional. "Relevant" means: the spec file for each class you changed, plus any integration specs in `spec/integration/` that exercise the affected feature. If MongoDB is not reachable, report this to the user rather than trying to work around it.
 
-Be encouraging.
+## Thread and fiber safety
+
+This driver runs in multi-threaded and multi-fiber environments. When writing or modifying code that touches connection pools, server monitors, or any shared state, always consider concurrent access. Use existing synchronization primitives in the codebase rather than introducing new ones.
+
+## Spec fixtures
+
+Unified test format YAML fixtures live in `spec/spec_tests/data/<suite_name>/`. To add new fixtures, copy YAML files from `specifications/source/<spec-name>/tests/unified/` into that directory. The runner loads all `*.yml` files automatically — no runner changes needed.
+
+Do not write Ruby specs that duplicate behavior already covered by YAML spec tests. New Ruby specs should cover behavior that cannot be expressed in the unified test format.
+
+
+# Code Reviews
 
+See [.github/code-review.md](.github/code-review.md) for code review guidelines.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md