CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

sleap-io is a standalone utility library for working with animal pose tracking data. It provides:

Reading/writing pose tracking data in various formats (SLEAP, NWB, Label Studio, JABS)
Data structure manipulation and conversion
Video I/O operations
Minimal dependencies (no labeling, training, or inference functionality)

Formatting: Use ruff format with max line length of 88
Docstrings: Google style, document "Attributes" section in class-level docstring
Type hints: Always include for function arguments and return types
Import order: Standard library, third-party, local (enforced by ruff)

Never work in main, always create a scoped feature branch (e.g., feature/x or fix/y if not specified explicitly).
After creating the branch, make sure to plan for the tasks you will be doing.
When experimenting and introspecting, feel free to create a directory in tmp/{BRANCH_NAME} for prototyping, exploration, and note-taking. This will not be checked into the git history.
When committing, never commit all changes. Always carefully analyze the files and hunks that changed and create specific and multiple PRs to avoid committing unintended work, or bundling changes together that would make it hard to revert them.
After making your changes, be sure to lint and maximize coverage.
If there are enhancements or API changes, be sure to update the docs/ appropriately.
Create a PR using the gh CLI when the changes are close to ready.
When finishing up, use gh to check the CI every 30 seconds until it finishes running and check the logs if CI failed.
When the user says to go ahead and merge, then squash merge with gh pr merge --delete-branch.

When updating PR descriptions (from .claude/commands/pr-description.md):

Fetch current PR metadata and linked issues using gh CLI
Include: Summary, Key Changes, Example Usage, API Changes, Testing, and Design Decisions
Document reasoning behind implementation choices for future reference

Use existing fixtures from tests/fixtures/ when possible. Read the modules there to learn about relevant fixtures.
Create minimal synthetic data for new tests rather than files when there is no appropriate existing fixture.
Use tmp_path for any I/O operations in tests.
Write multiple focused tests rather than one complex test.
Place tests in corresponding module under tests/ (e.g., sleap_io/io/slp.py → tests/io/test_slp.py)
Never create new test modules unless a new package module was created.
When adding tests, use global imports at the module-level rather than importing locally within a test function unless strictly needed (e.g., for import checking). Analyze current imports to find the best place to add the import statement and do not duplicate existing imports.
Use pytest function-style testing rather than unittest-style tests.
NEVER use mocking or monkey patching as a quick fix for increasing coverage. If the condition or execution branch can't be reproduced (e.g., defensive coding, rare edge cases), re-evaluate whether that condition should exist. Code branches that are difficult to test are an anti-pattern.