135 lines
6.5 KiB
Markdown
135 lines
6.5 KiB
Markdown
# Claude Code Instructions - Python Development Standards
|
|
|
|
## Environment Setup
|
|
- **Virtual Environment**: Always activate the virtual environment at `.venv/bin/activate` before any operations
|
|
- **Package Management**: Use `uv` exclusively for package management (not pip, poetry, or conda)
|
|
- **Pre-execution**: Always activate venv before running make targets or any Python commands
|
|
|
|
## Type Safety & Linting Standards
|
|
|
|
### Forbidden Practices
|
|
- **Type Suppression**: Using `# type: ignore` is strictly forbidden
|
|
- **Generic Types**: Using `Any` as a type is forbidden unless absolutely no other option exists
|
|
- **Lint Circumvention**: Never skip, circumvent, bypass, avoid, ignore, or sidestep precommit checks and lint errors
|
|
- **Precommit Bypass**: Using `--no-verify` to skip precommit checks is absolutely forbidden
|
|
|
|
### Type Annotation Requirements
|
|
- Use modern typing with specific, descriptive types
|
|
- Prefer union types (`str | None`) over `Optional[str]` (Python 3.10+)
|
|
- Use generic type parameters for collections: `list[str]`, `dict[str, int]`
|
|
- Leverage `typing.Protocol` for structural typing when appropriate
|
|
- Use `typing.Final` for constants
|
|
- Apply `@overload` for functions with multiple valid signatures
|
|
|
|
### Linting Tools
|
|
- **Primary Linter**: Use Pyright (Pylance) for type linting
|
|
- **Code Quality**: Address all refactorlint suggestions without exception
|
|
- **Error Handling**: Never skip linter errors and failed tests unless explicitly instructed otherwise
|
|
|
|
## Code Architecture & Design
|
|
|
|
### File Organization
|
|
- **Size Limit**: If a file exceeds 700 lines, convert it into a package in its own self-contained directory
|
|
- Example: `foo.py` becomes `foo/` with `__init__.py` and sub-modules
|
|
- **Module Creation**: Creating new files and modules is forbidden without valid justification and explicit approval
|
|
- **Code Reuse**: Enabling redundancy is strictly forbidden
|
|
- Recursively inspect neighboring/adjacent/tangential files and folders
|
|
- Ensure reuse of existing code instead of creating new implementations
|
|
|
|
### Implementation Standards
|
|
- **No Shortcuts**: Taking shortcuts or circumventing implementation design is forbidden
|
|
- **Complete Implementation**: If task 1 requires subtask C, then subtask C becomes part of the requirements
|
|
- **No TODOs**: Do not leave TODO comments; build the functionality instead
|
|
- **Model Names**: Do not change language model names (training data may not reflect current resources)
|
|
|
|
## Code Style Conventions
|
|
|
|
### Function Design
|
|
- **Inline Returns**: Use inline variable returns as functions to keep code neat
|
|
- **Single Responsibility**: Functions should have one clear purpose
|
|
- **Pure Functions**: Prefer pure functions where possible
|
|
- **Named Expressions**: Use walrus operator (`:=`) for complex conditions (addressing `use-named-expression`)
|
|
|
|
### Control Flow Patterns
|
|
- **Simplify Comparisons**: Use direct length checks instead of comparing to zero (`if items:` not `if len(items) > 0`)
|
|
- **Boolean Logic**: Simplify boolean comparisons (`if flag:` not `if flag is True`)
|
|
- **Conditional Merging**: Merge nested if statements when logical
|
|
- **Early Returns**: Use guard clauses and early returns to reduce nesting
|
|
- **Loop Optimization**: Hoist statements from loops when possible
|
|
|
|
### Data Structures
|
|
- **Collections**: Use appropriate collection types (`set()` for uniqueness, `dict` for mappings)
|
|
- **Comprehensions**: Prefer list/dict/set comprehensions over loops when readable
|
|
- **Constant Sums**: Use `sum()` for adding sequences of numbers
|
|
- **Set Operations**: Convert collections to sets for membership testing when appropriate
|
|
|
|
### Error Handling
|
|
- **Specific Exceptions**: Raise specific errors instead of generic exceptions
|
|
- **Custom Exceptions**: Create domain-specific exception classes when needed
|
|
- **Exception Chaining**: Use `raise ... from ...` for exception chaining
|
|
- **Context Managers**: Use context managers for resource management
|
|
|
|
## Testing Standards
|
|
|
|
### Test Structure
|
|
- **No Loops**: Never use loops in tests (addressing `no-loop-in-tests`)
|
|
- **No Conditionals**: Never use conditional statements in tests (addressing `no-conditionals-in-tests`)
|
|
- **Assertion Clarity**: Use specific assertions (`assert x == y` not `assert True`)
|
|
- **Test Isolation**: Each test should be independent and atomic
|
|
- **Module Imports**: Do not import test modules in production code (addressing `dont-import-test-modules`)
|
|
|
|
### Test Patterns
|
|
- **Arrange-Act-Assert**: Follow the AAA pattern consistently
|
|
- **Parameterization**: Use `pytest.mark.parametrize` for multiple test cases
|
|
- **Fixtures**: Create reusable fixtures for common test setup
|
|
- **Mocking**: Use appropriate mocking for external dependencies
|
|
|
|
## Documentation Standards
|
|
|
|
### Docstring Requirements
|
|
- **Imperative Style**: Write docstrings imperatively with proper punctuation
|
|
- **Completeness**: Document all public functions, classes, and modules
|
|
- **Examples**: Include usage examples in docstrings when helpful
|
|
- **Type Information**: Docstrings should complement, not duplicate, type annotations
|
|
|
|
### Code Comments
|
|
- **Explain Why**: Comments should explain why, not what
|
|
- **Business Logic**: Document complex business rules and algorithms
|
|
- **Edge Cases**: Explain handling of edge cases and special conditions
|
|
|
|
## Development Workflow
|
|
|
|
### Required Tools Integration
|
|
- **Sequential Thinking**: Use the sequential thinking MCP to evaluate design and technical decisions
|
|
- **Context7**: Use the context7 MCP religiously for modern code patterns and libraries
|
|
- **Documentation Research**: Leverage latest documentation for current best practices
|
|
|
|
### Quality Gates
|
|
- **Pre-commit Hooks**: All pre-commit hooks must pass
|
|
- **Type Checking**: Code must pass type checking without warnings
|
|
- **Test Coverage**: Maintain appropriate test coverage
|
|
- **Linting**: All linting rules must be satisfied
|
|
|
|
### Refactoring Priorities
|
|
Based on common issues identified, prioritize fixing:
|
|
1. Test module imports in production code
|
|
2. Length comparisons that can be simplified
|
|
3. Constant sum calculations
|
|
4. Loop and conditional usage in tests
|
|
5. Generic assertion statements
|
|
6. Opportunities for named expressions
|
|
7. Code hoisting opportunities
|
|
8. List comprehension improvements
|
|
|
|
## Code Review Checklist
|
|
- [ ] Virtual environment activated
|
|
- [ ] All type annotations specific (no `Any`)
|
|
- [ ] No `# type: ignore` suppressions
|
|
- [ ] Docstrings written imperatively
|
|
- [ ] No TODOs remaining
|
|
- [ ] Tests contain no loops or conditionals
|
|
- [ ] Specific exceptions used
|
|
- [ ] File under 700 lines or properly modularized
|
|
- [ ] Code reuse verified (no redundancy)
|
|
- [ ] All linting rules satisfied
|
|
- [ ] Pre-commit hooks passing |