diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..01d8f62c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# data-diff
+
+Cross-database data comparison tool (CLI + Python library). Efficiently diffs rows across 13+ database engines using bisection and checksumming.
+
+## Development Setup
+
+```bash
+uv sync                      # install dependencies
+uv run pre-commit install    # set up pre-commit hooks
+```
+
+## Test Commands
+
+```bash
+make test-unit               # unit tests only (no DB required)
+make test                    # full suite against PG + MySQL (starts containers)
+uv run pytest tests/ -x      # run all tests, stop on first failure
+uv run pytest -k <name>      # run a specific test
+```
+
+## Linting & Formatting
+
+```bash
+uv run ruff check .          # lint
+uv run ruff format .         # format
+```
+
+Ruff config: `ruff.toml` -- line-length 120, target Python 3.10.
+
+## Code Style
+
+- Format with `ruff format .`; lint with `ruff check .`
+- Follow existing patterns in the codebase
+- Imports sorted by ruff isort (first-party: `data_diff`)
+
+## Project Structure
+
+- `data_diff/` -- main package
+- `data_diff/databases/` -- database driver modules
+- `tests/` -- pytest test suite
+- `docker-compose.yml` -- local test databases (PG, MySQL, ClickHouse, etc.)
+
+## Contributing
+
+1. Fork and create a feature branch
+2. Write tests for changes
+3. Ensure `uv run ruff check .` and `uv run pytest` pass
+4. Open a PR with a clear description
diff --git a/README.md b/README.md
index 7c29ab7a..076fa0fa 100644
--- a/README.md
+++ b/README.md
@@ -80,6 +80,12 @@ pip install 'data-diff[dbt]'
 
 See the [full documentation](https://data-diff.readthedocs.io/) for configuration details.
 
+## Windows Support
+
+The `pip install data-diff` command works natively on Windows, macOS, and Linux. Database-specific extras install the same way across all platforms.
+
+For development, the `Makefile` and `docker compose` workflow assumes a Unix-like shell. On Windows, use **WSL** (recommended) or **Git Bash** to run `make test`, `make up`, and other development commands.
+
 ## Documentation
 
 - [Full Documentation](https://data-diff.readthedocs.io/)