docs: improve CLAUDE.md structure and clarity
This commit is contained in:
David Soria Parra
parent
d64b0679b8
commit
57c3aa2f0d
1 changed files with 87 additions and 61 deletions
148
CLAUDE.md
148
CLAUDE.md
|
|
@ -1,73 +1,99 @@
|
||||||
# Tool Usage Learnings
|
# Development Guidelines
|
||||||
|
|
||||||
This file is intended to be used by an LLM such as Claude.
|
This document contains critical information about working with this codebase. Follow these guidelines precisely.
|
||||||
|
|
||||||
## UV Package Manager
|
## Core Development Rules
|
||||||
|
|
||||||
- Use `uv run` to run Python tools without activating virtual environments
|
1. Package Management
|
||||||
- For formatting: `uv run ruff format .`
|
- ONLY use uv, NEVER pip
|
||||||
- For type checking: `uv run pyright`
|
- Installation: `uv add package`
|
||||||
- For upgrading packages:
|
- Running tools: `uv run tool`
|
||||||
- `uv add --dev package --upgrade-package package` to upgrade a specific package
|
- Upgrading: `uv add --dev package --upgrade-package package`
|
||||||
- Don't use `@latest` syntax - it doesn't work
|
- FORBIDDEN: `uv pip install`, `@latest` syntax
|
||||||
- Be careful with `uv pip install` as it may downgrade packages
|
|
||||||
|
|
||||||
## Git and GitHub CLI
|
2. Code Quality
|
||||||
|
- Type hints required for all code
|
||||||
|
- Public APIs must have docstrings
|
||||||
|
- Functions must be focused and small
|
||||||
|
- Follow existing patterns exactly
|
||||||
|
- Line length: 88 chars maximum
|
||||||
|
|
||||||
- When using gh CLI for PRs, always quote title and body:
|
3. Testing Requirements
|
||||||
```bash
|
- Framework: `uv run pytest`
|
||||||
gh pr create --title "\"my title\"" --body "\"my body\""
|
- Async testing: use anyio, not asyncio
|
||||||
```
|
- Coverage: test edge cases and errors
|
||||||
- For git commits, use double quotes and escape inner quotes:
|
- New features require tests
|
||||||
```bash
|
- Bug fixes require regression tests
|
||||||
git commit -am "\"fix: my commit message\""
|
|
||||||
```
|
|
||||||
|
|
||||||
## Python Tools
|
4. Version Control
|
||||||
|
- Commit messages: conventional format (fix:, feat:)
|
||||||
|
- PR scope: minimal, focused changes
|
||||||
|
- PR requirements: description, test plan
|
||||||
|
- Always include issue numbers
|
||||||
|
- Quote handling:
|
||||||
|
```bash
|
||||||
|
git commit -am "\"fix: message\""
|
||||||
|
gh pr create --title "\"title\"" --body "\"body\""
|
||||||
|
```
|
||||||
|
|
||||||
### Ruff
|
## Code Formatting
|
||||||
- Handles both formatting and linting
|
|
||||||
- For formatting: `uv run ruff format .`
|
|
||||||
- For checking: `uv run ruff check .`
|
|
||||||
- For auto-fixing: `uv run ruff check . --fix`
|
|
||||||
- Common issues:
|
|
||||||
- Line length (default 88 chars)
|
|
||||||
- Import sorting (I001 errors)
|
|
||||||
- Unused imports
|
|
||||||
- When line length errors occur:
|
|
||||||
- For strings, use parentheses and line continuation
|
|
||||||
- For function calls, use multiple lines with proper indentation
|
|
||||||
- For imports, split into multiple lines
|
|
||||||
|
|
||||||
### Pyright
|
1. Ruff
|
||||||
- Type checker
|
- Format: `uv run ruff format .`
|
||||||
- Run with: `uv run pyright`
|
- Check: `uv run ruff check .`
|
||||||
- Version warnings can be ignored if type checking passes
|
- Fix: `uv run ruff check . --fix`
|
||||||
- Common issues:
|
- Critical issues:
|
||||||
- Optional types need explicit None checks
|
- Line length (88 chars)
|
||||||
- String operations need type narrowing
|
- Import sorting (I001)
|
||||||
|
- Unused imports
|
||||||
|
- Line wrapping:
|
||||||
|
- Strings: use parentheses
|
||||||
|
- Function calls: multi-line with proper indent
|
||||||
|
- Imports: split into multiple lines
|
||||||
|
|
||||||
## Pre-commit Hooks
|
2. Type Checking
|
||||||
|
- Tool: `uv run pyright`
|
||||||
|
- Requirements:
|
||||||
|
- Explicit None checks for Optional
|
||||||
|
- Type narrowing for strings
|
||||||
|
- Version warnings can be ignored if checks pass
|
||||||
|
|
||||||
- Configuration in `.pre-commit-config.yaml`
|
3. Pre-commit
|
||||||
- Runs automatically on git commit
|
- Config: `.pre-commit-config.yaml`
|
||||||
- Includes:
|
- Runs: on git commit
|
||||||
- Prettier for YAML/JSON formatting
|
- Tools: Prettier (YAML/JSON), Ruff (Python)
|
||||||
- Ruff for Python formatting and linting
|
- Ruff updates:
|
||||||
- When updating ruff version:
|
- Check PyPI versions
|
||||||
- Check available versions on PyPI
|
- Update config rev
|
||||||
- Update `rev` in config to match available version
|
- Commit config first
|
||||||
- Add and commit config changes before other changes
|
|
||||||
|
|
||||||
## Best Practices
|
## Error Resolution
|
||||||
|
|
||||||
1. Always check git status and diff before committing
|
1. CI Failures
|
||||||
2. Run formatters before type checkers
|
- Fix order:
|
||||||
3. When fixing CI:
|
1. Formatting
|
||||||
- Start with formatting issues
|
2. Type errors
|
||||||
- Then fix type errors
|
3. Linting
|
||||||
- Then address any remaining linting issues
|
- Type errors:
|
||||||
4. For type errors:
|
- Get full line context
|
||||||
- Get full context around error lines
|
- Check Optional types
|
||||||
- Consider optional types
|
- Add type narrowing
|
||||||
- Add type narrowing checks when needed
|
- Verify function signatures
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
3. Best Practices
|
||||||
|
- Check git status before commits
|
||||||
|
- Run formatters before type checks
|
||||||
|
- Keep changes minimal
|
||||||
|
- Follow existing patterns
|
||||||
|
- Document public APIs
|
||||||
|
- Test thoroughly
|
||||||
Loading…
Reference in a new issue