Claude Code instructions for developing computer vision solutions for Star Battle puzzles with Python, pytest, and strict typing
Expert guidance for developing computer vision solutions for Star Battle puzzle games using Python with strict type checking and testing standards.
Use this skill when working on the starbattlecv repository or similar computer vision projects that require:
Before making any changes:
```bash
uv sync
uv run python -m pytest --version
```
**Test all code:**
```bash
make test
uv run python -m pytest --doctest-modules
```
**Test a single function:**
```bash
uv run python -m pytest tests/test_foo.py::test_function_name
```
**Test across Python versions:**
```bash
tox
```
**Run all checks:**
```bash
make check
uv run pre-commit run -a
```
**Type checking only:**
```bash
uv run mypy
```
Follow this sequence:
1. Read existing code to understand patterns
2. Write tests first (TDD approach when appropriate)
3. Implement changes with proper type annotations
4. Run tests and type checks
5. Fix any linting issues
6. Commit with descriptive messages
**REQUIRED for all functions.** Use mypy strict settings:
```python
def process_image(img: np.ndarray, threshold: int = 128) -> tuple[bool, list[int]]:
"""Process puzzle image and extract features.
Args:
img: Input image as numpy array
threshold: Binarization threshold (default: 128)
Returns:
Tuple of (success status, list of detected coordinates)
"""
...
```
Follow Tryceratops conventions (Ruff "TRY" selectors):
```python
try:
result = process_puzzle(image)
except ValueError as e:
logger.error(f"Invalid puzzle format: {e}")
raise
try:
result = process_puzzle(image)
except: # Bad - too broad
pass
```
```
starbattlecv/
├── starbattlecv/ # Source code
│ ├── __init__.py
│ ├── detection.py # Puzzle detection logic
│ └── processing.py # Image processing utilities
├── tests/ # Test files (prefix: test_*)
│ ├── test_detection.py
│ └── test_processing.py
├── examples/ # Sample images for testing
├── pyproject.toml # Project configuration
└── Makefile # Common commands
```
```python
import pytest
from starbattlecv.detection import find_grid
def test_find_grid_valid_image():
"""Test grid detection on valid puzzle image."""
img = load_test_image("examples/puzzle1.png")
grid = find_grid(img)
assert grid is not None
assert len(grid) == 10 # 10x10 grid expected
def test_find_grid_invalid_image():
"""Test grid detection handles invalid input."""
with pytest.raises(ValueError):
find_grid(None)
```
The test suite runs doctests in modules. Include examples in docstrings:
```python
def normalize_coordinates(coords: list[tuple[int, int]]) -> list[tuple[int, int]]:
"""Normalize coordinate list to grid indices.
Args:
coords: List of (x, y) pixel coordinates
Returns:
List of normalized (row, col) grid coordinates
Examples:
>>> normalize_coordinates([(100, 150), (200, 250)])
[(1, 1), (2, 2)]
"""
...
```
1. **Create feature detection function** with type annotations
2. **Add tests** in appropriate test file
3. **Add example images** to `examples/` if needed
4. **Document the algorithm** in docstring with references
5. **Run full test suite** to ensure no regressions
1. **Use example images** from `examples/` directory
2. **Add visualization code** (temporary, remove before commit):
```python
import cv2
cv2.imshow("Debug", processed_image)
cv2.waitKey(0)
```
3. **Write specific test cases** for edge cases
4. **Check type coverage** with mypy
1. **Profile first** - don't optimize prematurely
2. **Add benchmarks** as pytest fixtures
3. **Maintain type safety** during optimization
4. **Document trade-offs** in comments
```bash
uv sync # Install deps
uv run python -m pytest # Run tests
uv run mypy # Type check
uv run pre-commit run -a # Lint/format
git add . && git commit # Commit changes
make test # Run all tests
make check # Run all checks
```
**Import errors after adding dependencies:**
```bash
uv sync # Reinstall dependencies
```
**Type check failures:**
**Test discovery issues:**
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/star-battle-cv-development/raw