From a8daeb79c34599551d347cfd85877b828a249343 Mon Sep 17 00:00:00 2001
From: Shalabh Gupta <marketingshalabh@gmail.com>
Date: Thu, 28 May 2026 14:13:33 +0530
Subject: [PATCH] docs(readme): expand Development section with dev-deps,
 manual checks, PR conventions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README's Development section previously documented only the initial
git-hook setup. The dev-dependency install command, the manual lint /
typecheck / test commands, and the PR title convention all existed in
the repo (pyproject.toml dev extras, CLAUDE.md, merged PR history) but
external contributors had to reverse-engineer them from those sources.

This consolidates the existing information under three new subsections:

- Setting up — pip install -e ".[dev]" + a pointer to the dev extras
- Running checks manually — the four ruff/mypy/pytest commands from
  CLAUDE.md, plus a single-test-file invocation
- Pull request conventions — Conventional Commits prefix in PR titles,
  scoping, and the expectation that behavior changes get tests

No commands are introduced that aren't already used somewhere in the
repo. The existing Git hooks, Building Wheels Locally, and Release
Workflow subsections are unchanged.

Fixes #966
---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8d8445238..51866539e 100644
--- a/README.md
+++ b/README.md
@@ -289,13 +289,61 @@ 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:
+### Setting up
+
+Clone the repository and install the package in editable mode with the `dev`
+extras to pull in the test, lint, and type-check tools:
+
+```bash
+git clone https://github.com/anthropics/claude-agent-sdk-python.git
+cd claude-agent-sdk-python
+pip install -e ".[dev]"
+```
+
+The `dev` extras are declared under `[project.optional-dependencies]` in
+`pyproject.toml` and include `pytest`, `pytest-asyncio`, `pytest-cov`, `mypy`,
+`ruff`, and `anyio[trio]`.
+
+### Git hooks
+
+Run the initial setup script once to install the pre-push hook, which runs the
+same lint checks as the `lint` CI workflow before each push:
 
 ```bash
 ./scripts/initial-setup.sh
 ```
 
-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`.
+To skip the hook temporarily, use `git push --no-verify`.
+
+### Running checks manually
+
+The pre-push hook covers `ruff` only. Run `mypy` and `pytest` yourself before
+opening a PR:
+
+```bash
+# Lint — check and auto-fix
+python -m ruff check src/ tests/ --fix
+
+# Format
+python -m ruff format src/ tests/
+
+# Type-check (src/ only)
+python -m mypy src/
+
+# Tests
+python -m pytest tests/
+
+# A single test file
+python -m pytest tests/test_client.py
+```
+
+### Pull request conventions
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) prefixes in
+  the PR title — `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.
+  This matches the merge-commit history on `main`.
+- Keep PRs scoped to one feature or fix.
+- Behavior changes should include or update a test under `tests/`.
 
 ### Building Wheels Locally