From c3acc6735f22a6acdf46e242f0e7f89d259727db Mon Sep 17 00:00:00 2001
From: Hoi Hin Ip Adrian <adrian@Hois-Mac-mini.local>
Date: Mon, 18 May 2026 10:13:21 +0800
Subject: [PATCH] docs: add contributing workflow

---
 CONTRIBUTING.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  3 +++
 2 files changed, 54 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..c22bdc705
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,51 @@
+# Contributing
+
+Thanks for helping improve the Claude Agent SDK for Python.
+
+## Development setup
+
+Install the package with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+To install the pre-push hook used by this repository, run:
+
+```bash
+./scripts/initial-setup.sh
+```
+
+## Local checks
+
+Run the checks that match your change before opening a pull request:
+
+```bash
+# Lint and automatically fix issues
+python -m ruff check src/ tests/ --fix
+
+# Format source and tests
+python -m ruff format src/ tests/
+
+# Typecheck the SDK package
+python -m mypy src/
+
+# Run the test suite
+python -m pytest tests/
+```
+
+For a focused test run, pass a specific test file:
+
+```bash
+python -m pytest tests/test_client.py
+```
+
+## Pull request titles
+
+Use a short, descriptive title. Recent pull requests generally follow
+Conventional Commits style, such as:
+
+- `fix(query): surface result error text`
+- `docs(types): clarify hooks dispatch behavior`
+- `deps: bump mcp lower bound`
+
diff --git a/README.md b/README.md
index 8d8445238..067bbdf8b 100644
--- a/README.md
+++ b/README.md
@@ -289,6 +289,9 @@ If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the
 
 ## Development
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, local checks,
+and pull request title guidance.
+
 If you're contributing to this project, run the initial setup script to install git hooks:
 
 ```bash