From c92a83289c9532117ea659ee27e9768062d860dd Mon Sep 17 00:00:00 2001
From: yinlixin <ylx3020129@gmail.com>
Date: Thu, 28 May 2026 13:47:12 +0800
Subject: [PATCH] docs: add CONTRIBUTING.md with dev setup, lint, test, and PR
 guidelines

Surface dev-dependency install command, manual lint/typecheck/test
commands, and PR title conventions. Previously this information was
scattered across CLAUDE.md (agent-facing), pyproject.toml, and
merged PR history.

Closes #966
---
 CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  3 +++
 2 files changed, 51 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..e05a426d8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,48 @@
+# Contributing to claude-agent-sdk
+
+## Development Setup
+
+1. Clone the repo and install with dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+2. Install the pre-push git hook (runs lint checks before push, matching CI):
+
+```bash
+./scripts/initial-setup.sh
+```
+
+To skip the hook temporarily: `git push --no-verify`.
+
+## Lint & Format
+
+```bash
+python -m ruff check src/ tests/ --fix
+python -m ruff format src/ tests/
+```
+
+## Type Checking
+
+```bash
+python -m mypy src/
+```
+
+Type checking is only enforced for `src/` (not `tests/`).
+
+## Tests
+
+```bash
+# All tests
+python -m pytest tests/
+
+# Single test file
+python -m pytest tests/test_client.py
+```
+
+## PR Guidelines
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for PR titles (e.g., `fix:`, `feat:`, `docs:`, `chore:`).
+- Keep PRs focused on a single change.
+- Make sure lint, typecheck, and tests pass before opening the PR.
diff --git a/README.md b/README.md
index 8d8445238..3384e9b1c 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 the full development setup, including dev-dependency install, lint, typecheck, and test commands.
+
+
 If you're contributing to this project, run the initial setup script to install git hooks:
 
 ```bash