Improve CLAUDE.md (#2524)

Author: Kludex

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rg:*)",
+      "Bash(make:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run:*)",
+      "Bash(git push:*)",
+      "Bash(git checkout:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr view:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(gh pr comment:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh api:*)",
+      "Bash(pre-commit run:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(coverage:*)"
+    ],
+    "deny": []
+  }
+}

CLAUDE.md

@@ -5,23 +5,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Development Commands
 
 ### Core Development Tasks
+
 - **Install dependencies**: `make install` (requires uv, pre-commit, and deno)
-- **Run all checks**: `make` (format, lint, typecheck, test with coverage)
-- **Format code**: `make format`
-- **Lint code**: `make lint`
-- **Type checking**: `make typecheck` (uses pyright) or `make typecheck-both` (pyright + mypy)
-- **Run tests**: `make test` (with coverage)
+- **Run all checks**: `pre-commit run --all-files`
+- **Run tests**: `make test`
 - **Build docs**: `make docs` or `make docs-serve` (local development)
 
 ### Single Test Commands
 - **Run specific test**: `uv run pytest tests/test_agent.py::test_function_name -v`
 - **Run test file**: `uv run pytest tests/test_agent.py -v`
 - **Run with debug**: `uv run pytest tests/test_agent.py -v -s`
 
-### Multi-Python Testing
-- **Install all Python versions**: `make install-all-python`
-- **Test all Python versions**: `make test-all-python`
-
 ## Project Architecture
 
 ### Core Components
@@ -125,3 +119,26 @@ This is a uv workspace with multiple packages:
 - **Lock file**: `uv.lock` (commit this file)
 - **Sync command**: `make sync` to update dependencies
 - **Optional extras**: Define groups in `pyproject.toml` optional-dependencies
+
+## Best Practices
+
+This is the list of best practices for working with the codebase.
+
+### Rename a class
+
+When asked to rename a class, you need to rename the class in the code and add a deprecation warning to the old class.
+
+```python
+from typing_extensions import deprecated
+
+class NewClass: ...  # This class was renamed from OldClass.
+
+@deprecated("Use NewClass instead")
+class OldClass(NewClass): ...
+```
+
+In the test suite, you need to use the `NewClass` instead of the `OldClass`.
+
+### Writing documentation
+
+Always reference Python objects with the "`" (backticks) around them.