diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..8417c2cd3e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,56 @@
+# AGENTS.md - PyMongo (mongo-python-driver)
+
+## Overview
+Official Python driver for MongoDB.
+
+## Tech Stack
+- **Build/env:** `hatch` — use `hatch run test:test` and `hatch run test:test-async`, not `pytest` directly
+- **Task runner:** `just` (Justfile at repo root)
+- **Linter/formatter:** `ruff` via pre-commit
+- **Type checker:** `mypy` (strict)
+- **Docs:** Sphinx / reStructuredText; use Sphinx docstring format for all docstrings
+
+> **Never** run `pip install bson`. PyMongo ships its own `bson`; the PyPI `bson` package silently breaks things.
+
+## Project Structure
+- `pymongo/synchronous/` — sync driver (MongoClient, Collection, Database, etc.) generated from `pymongo/asynchronous/` using unasync
+- `pymongo/asynchronous/` — async API, mirrors `pymongo/synchronous/`
+- `bson/` — BSON implementation
+- `gridfs/` — GridFS API
+- `test/` — sync test suite
+- `test/asynchronous/` — async test suite, mirrors `test/`
+- `test/unified_format/` — cross-driver spec tests (Unified Test Format)
+- `tools/convert_test_to_async.py` — generates async test stubs from sync tests
+
+## Commands
+```bash
+just install          # set up venv + pre-commit hook
+just typing-mypy      # type check
+just run lint-manual  # ruff linter
+
+hatch run test:test         # run sync tests
+hatch run test:test-async   # run async tests
+
+MONGODB_VERSION=8.0 just run-server  # start a local MongoDB server
+```
+
+## Testing
+Tests require a live MongoDB server (`just run-server` above).
+
+Never modify pymongo/synchronous code first; update the async counterpart and run our `tools/synchro.py` script:
+1. Make changes in `pymongo/asynchronous` or top-level `pymongo/` files and `test/`.
+2. Run `tools/convert_test_to_async.py` on the sync test file to generate a starting-point async version.
+3. Manually complete the async version in `test/asynchronous/`.
+
+Do not edit files in `pymongo/synchronous/` or mirrored files in `test/` directly — they are auto-generated by `tools/synchro.py` from `pymongo/asynchronous/` and `test/asynchronous/`. Only edit them if the change includes a `_IS_SYNC` statement.
+
+Async functions must not call blocking I/O.
+
+New features need integration tests. Bug fixes need regression tests.
+
+## Commit and PR Conventions
+- Prefix commits and PR titles with the JIRA ticket: `PYTHON-1234 Fix retryable write on mongos`
+- Backport PRs: append the target branch in brackets — `PYTHON-1234 [v4.9] Fix retryable write`
+- Merge via **Squash and Merge** only
+
+See .github/copilot-instructions.md for more details.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md