CLAUDE.md

Development Guidelines

This document contains critical information about working with this codebase. Follow these guidelines precisely.

Core Development Rules

1. Package Management

   • ONLY use uv, NEVER pip
   • Installation: uv add package
   • Running tools: uv run tool
   • Upgrading: uv add --dev package --upgrade-package package
   • FORBIDDEN: uv pip install, @latest syntax

2. Code Quality

   • Type hints required for all code
   • Functions must be focused and small
   • Follow existing patterns exactly
   • Line length: 88 chars maximum

3. Testing Requirements

   • Framework: uv run --frozen pytest
   • Coverage: test edge cases and errors
   • New features require tests
   • Bug fixes require regression tests

Python Tools

Code Formatting

1. Ruff
   • Format: uv run --frozen ruff format .
   • Check: uv run --frozen ruff check .
   • Fix: uv run --frozen ruff check . --fix
   • Critical issues:
     • Line length (88 chars)
     • Import sorting (I001)
     • Unused imports
   • Line wrapping:
     • Strings: use parentheses
     • Function calls: multi-line with proper indent
     • Imports: split into multiple lines

Error Resolution

2. Common Issues

   • Line length:
     • Break strings with parentheses
     • Multi-line function calls
     • Split imports
   • Types:
     • Add None checks
     • Narrow string types
     • Match existing patterns
   • Pytest
     • we use automatic detection of async defs

3. Best Practices

   • Check git status before commits
   • Always create git branch for changes. don't push to main directly.
   • Run formatters before type checks
   • Keep changes minimal
   • Follow existing patterns
   • Test thoroughly
   • Use Context7 mcp server if available to get latest documents.

• Don't mention claude code any where in code, commit messages or in PR description or comment