diff --git a/.github/code-review.md b/.github/code-review.md
new file mode 100644
index 000000000..f8beb756e
--- /dev/null
+++ b/.github/code-review.md
@@ -0,0 +1,39 @@
+# 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.
+
+## BSON-specific Concerns
+- This library includes C native extensions. When reviewing changes to serialization or deserialization, verify that both the Ruby and C implementations remain consistent.
+- Look for potential issues with binary data handling: endianness, buffer overflows, encoding mismatches.
+- BSON types must conform to the BSON specification. Verify that type IDs, serialization formats, and edge cases match the spec.
+
+## 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/spec_tests/data/` directory; these are test fixtures shared between all BSON implementations and are not owned by this repository.
+
+Always prioritize security vulnerabilities and performance issues that could impact users.
+
+Always suggest changes to improve readability and testability.
+
+When reviewing code, be encouraging.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..d855be5e4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,70 @@
+# Project Description
+
+This is the Ruby implementation of the BSON (Binary JSON) specification. BSON is the binary-encoded serialization format used by MongoDB. This library provides serialization and deserialization of BSON data, Ruby type extensions for BSON-compatible types, and a C native extension for performance-critical operations. The library targets Ruby 2.6+. Do not use syntax or stdlib features unavailable in Ruby 2.6.
+
+# Project Structure
+
+- `lib/`: the main Ruby codebase
+- `ext/bson/`: C native extension for MRI Ruby (performance-critical serialization)
+- `src/`: Java extension source for JRuby
+- `spec/`: RSpec tests and shared test data
+- `spec/spec_tests/`: specification-driven tests with YAML fixtures from the BSON specification
+- `perf/`: benchmarking scripts
+
+
+# Development Workflow
+
+## Running tests
+
+Tests do not require a running MongoDB instance. Run specs with:
+
+```
+bundle exec rake spec
+```
+
+This compiles the native extension and runs the full test suite. To run a single spec file:
+
+```
+bundle exec rspec spec/path/to/spec.rb
+```
+
+Note: the native extension must be compiled before running specs directly with `rspec`. Use `bundle exec rake compile` first if needed.
+
+## Linting
+
+Run RuboCop after making changes, and always before committing:
+
+```
+bundle exec rubocop lib/bson/changed_file.rb spec/bson/changed_file_spec.rb
+```
+
+Pass the specific files you modified.
+
+RuboCop is configured with performance, rake, and rspec plugins (`.rubocop.yml`).
+
+## Commit convention
+
+Prefix commit messages with the JIRA ticket: `RUBY-#### Short description`. The ticket number is typically in the branch name.
+
+## Prose style
+
+When writing prose — commit messages, code comments, documentation — be concise, write as a human would, avoid overly complicated sentences, and use no emojis.
+
+## Definition of done
+
+Always run the relevant spec file(s) before considering a task complete. Running tests is not optional. "Relevant" means: the spec file for each class you changed, plus any spec tests in `spec/spec_tests/` that exercise the affected type. If the native extension fails to compile, report this to the user rather than trying to work around it.
+
+## Native extensions
+
+This library includes a C extension (`ext/bson/`) for MRI and a Java extension (`src/`) for JRuby. When modifying serialization or deserialization behavior, check whether the native extension also needs updating. The C extension must remain compatible with the pure-Ruby fallback in `lib/`.
+
+## Spec fixtures
+
+BSON specification test YAML fixtures live in `spec/spec_tests/data/`. These are shared across all BSON implementations and are not owned by this repository. Do not modify them.
+
+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 specification test format.
+
+
+# Code Reviews
+
+See [.github/code-review.md](.github/code-review.md) for code review guidelines.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..43c994c2d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md