Add CLAUDE.md with development guidance

also add uv based tooling to ease things

Co-Authored-By: Claude <[email protected]>

- add ruff/mypy
- allow claude to run some commands directly

Author: RonnyPfannschmidt

.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run pytest:*)",
+      "Bash(git add:*)",
+      "Bash(uv run mypy:*)",
+      "Bash(uv run pre-commit:*)"
+
+    ],
+    "deny": []
+  }
+}

.gitignore

@@ -67,3 +67,6 @@ pip-wheel-metadata/
 
 # pytest-benchmark
 .benchmarks/
+
+# Claude Code local settings
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Pluggy is a minimalist production-ready plugin system that serves as the core framework for pytest, datasette and devpi.
+It provides hook specification and implementation mechanisms through a plugin manager system.
+
+## Development Commands
+
+### Testing
+- `uv run pytest` - Run all tests, prefer runnign all tests to quickly get feedback
+- `uv run pytest testing/benchmark.py` runs the benchmark tests
+
+### Code Quality
+- `uv run pre-commit run -a` - Run all pre-commit hooks - gives linting and typing errors + corrects files
+- reread files that get fixed by pre-commit
+
+
+## Development process
+
+- always read `src/pluggy/*.py` to get a full picture
+- consider backward compatibility
+- always run all tests
+- always run pre-commit before try to commit
+- prefer running full pre-commit over ruff/mypy alone
+
+
+
+## Core Architecture
+
+### Main Components
+
+- **PluginManager** (`src/pluggy/_manager.py`): Central registry that manages plugins and coordinates hook calls
+- **HookCaller** (`src/pluggy/_hooks.py`): Executes hook implementations with proper argument binding
+- **HookImpl/HookSpec** (`src/pluggy/_hooks.py`): Represent hook implementations and specifications
+- **Result** (`src/pluggy/_result.py`): Handles hook call results and exception propagation
+- **Multicall** (`src/pluggy/_callers.py`): Core execution engine for calling multiple hook implementations
+
+### Package Structure
+- `src/pluggy/` - Main package source
+- `testing/` - Test suite using pytest
+- `docs/` - Sphinx documentation and examples
+- `changelog/` - Towncrier fragments for changelog generation
+
+## Configuration Files
+- `pyproject.toml` - Project metadata, build system, tool configuration (ruff, mypy, setuptools-scm)
+- `tox.ini` - Multi-environment testing configuration
+- `.pre-commit-config.yaml` - Code quality automation (ruff, mypy, flake8, etc.)

pyproject.toml

@@ -35,10 +35,11 @@ readme = {file = "README.rst", content-type = "text/x-rst"}
 requires-python = ">=3.9"
 
 dynamic = ["version"]
-[project.optional-dependencies]
-dev = ["pre-commit", "tox"]
+[dependency-groups]
+dev = ["pre-commit", "tox", "mypy", "ruff"]
 testing = ["pytest", "pytest-benchmark", "coverage"]
 
+
 [tool.setuptools]
 packages = ["pluggy"]
 package-dir =  {""="src"}
@@ -67,6 +68,9 @@ lines-after-imports = 2
 
 [tool.setuptools_scm]
 
+[tool.uv]
+default-groups = ["dev", "testing"]
+
 [tool.towncrier]
 package = "pluggy"
 package_dir = "src/pluggy"

tox.ini

@@ -9,7 +9,7 @@ commands=
 setenv=
   _PYTEST_SETUP_SKIP_PLUGGY_DEP=1
   coverage: _PLUGGY_TOX_CMD=coverage run -m pytest
-extras=testing
+dependency_groups=testing
 deps=
   coverage: coverage
   pytestmain: git+https://github.com/pytest-dev/pytest.git@main