From 438d805570eecb0bebd4cba55741b1e1a5007470 Mon Sep 17 00:00:00 2001
From: hexcreator <hexcr3at0r@gmail.com>
Date: Tue, 14 Jul 2026 22:07:20 -0400
Subject: [PATCH] docs: add CONTRIBUTING.md with dev setup, lint/test commands,
 and PR conventions

Consolidates the contributor workflow that previously lived only in
CLAUDE.md and pyproject.toml: dev-deps install command, manual
lint/format/typecheck/test commands, and the Conventional Commits PR
title format. Links it from the README's Development section.

Fixes #966

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  7 ++++---
 2 files changed, 59 insertions(+), 3 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..ae2133c33
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for contributing to the Claude Agent SDK for Python!
+
+## Setting up your environment
+
+Install the package in editable mode along with the development dependencies (pytest, mypy, ruff, and friends):
+
+```bash
+pip install -e ".[dev]"
+```
+
+Then install the git hooks:
+
+```bash
+./scripts/initial-setup.sh
+```
+
+This installs a pre-push hook that runs the same lint checks as CI before each push. To skip the hook temporarily, use `git push --no-verify`.
+
+## Linting and formatting
+
+```bash
+# Check for issues and fix automatically
+python -m ruff check src/ tests/ --fix
+
+# Format code
+python -m ruff format src/ tests/
+```
+
+CI (and the pre-push hook) runs `python -m ruff check src/ tests/` and `python -m ruff format --check src/ tests/`, so both must pass cleanly.
+
+## Typechecking
+
+Typechecking is only enforced for `src/`:
+
+```bash
+python -m mypy src/
+```
+
+## Running tests
+
+```bash
+# Run all tests
+python -m pytest tests/
+
+# Run a specific test file
+python -m pytest tests/test_client.py
+```
+
+## Pull requests
+
+PR titles follow the [Conventional Commits](https://www.conventionalcommits.org/) format, e.g. `fix: handle empty errors list in result messages` or `docs: document dev setup`. Common types used in this repo are `feat`, `fix`, `docs`, `chore`, and `ci`.
+
+Before opening a PR, make sure lint, typecheck, and tests all pass locally.
diff --git a/README.md b/README.md
index 8d8445238..58b430b75 100644
--- a/README.md
+++ b/README.md
@@ -289,13 +289,14 @@ If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the
 
 ## Development
 
-If you're contributing to this project, run the initial setup script to install git hooks:
+If you're contributing to this project, see [CONTRIBUTING.md](CONTRIBUTING.md) for dev environment setup, lint/typecheck/test commands, and PR conventions. In short:
 
 ```bash
-./scripts/initial-setup.sh
+pip install -e ".[dev]"   # install dev dependencies
+./scripts/initial-setup.sh  # install git hooks
 ```
 
-This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
+The setup script installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
 
 ### Building Wheels Locally