CLAUDE.md

# Development Guidelines ## Code Principles ### SOLID Principles - **S**ingle Responsibility: One purpose per function/class - **O**pen/Closed: Extend via composition, not modification - **L**iskov Substitution: Subtypes must be substitutable - **I**nterface Segregation: Small, focused interfaces - **D**ependency Inversion: Depend on abstractions, not concretions ### Code Style - Follow PEP 8 (enforced by ruff) - Follow PEP 257 for docstrings - Type hints required (PEP 484) - KISS: Keep it simple and stupid - One purpose per function ### Documentation - **Add docstrings:** Public APIs, complex logic, non-obvious behavior - **Skip docstrings:** Self-explanatory functions (getters, simple utils) - **Format:** Google-style docstrings ```python # Good - needs docstring def calculate_focus_time(events: List[Event], threshold_minutes: float) -> Dict[str, float]: """Calculate uninterrupted focus time per app. Args: events: List of app usage events sorted by start time threshold_minutes: Gap duration to separate sessions Returns: Dict mapping app name to total focus minutes """ # Good - no docstring needed def get_app_name(event: Event) -> str: return event.app_name ``` ## Testing - Unit tests for each module - Test coverage > 80% - Use pytest + pytest-cov - Mock external dependencies (DB, filesystem) **MUST: Always verify after making changes** ```bash # Run all tests uv run pytest # Lint and format uv run ruff check --fix . # Type check uv run mypy src/ ``` Run this verification after every code change before considering the work complete. ## Project Structure ``` src/sense/ � core/ # Business logic (KnowledgeC analysis) � api/ # FastAPI routes � web/ # Dashboard templates + routes � models/ # Pydantic schemas � config.py # Configuration tests/ � unit/ # Unit tests (mirrors src/) � integration/ # API integration tests � conftest.py # Pytest fixtures ``` ## Dependencies - Managed via `pyproject.toml` - Use `uv` for fast package management - Pin major versions, allow minor updates ## Code Quality Tools - **ruff**: Linting + formatting (replaces flake8, black, isort) - **mypy**: Static type checking - **pytest**: Testing framework ```bash # Format code uv run ruff format . # Lint uv run ruff check . # Type check uv run mypy src/ ``` ## Git Workflow - Small, focused commits - Descriptive commit messages - One feature per branch (when applicable) ### Commit Message Format ``` : ``` **Types:** - `feat`: New feature - `fix`: Bug fix - `refactor`: Code refactoring - `test`: Add/update tests - `docs`: Documentation changes - `chore`: Build/tooling changes **Example:** ``` feat: add timeline API with pagination and filtering - Implement GET /timeline and GET /timeline/{app_name} - Add date range validation (max 7 days) - Support pagination, sorting, and system app filtering - Include 20 unit and integration tests ``` **Rules:** - Keep summary under 72 characters - Use imperative mood ("add" not "added") - No Co-Authored-By or AI attribution - Body is optional for simple changes