|
| 1 | +# CLAUDE.md - Project Guidelines for Claude Code |
| 2 | + |
| 3 | +## Project Overview |
| 4 | +This repository contains biomarker algorithms for health assessment, including PhenoAge and SCORE2 cardiovascular risk calculations. |
| 5 | + |
| 6 | +## Environment Setup |
| 7 | +**IMPORTANT**: Before starting work, ensure the virtual environment is activated: |
| 8 | +```bash |
| 9 | +# Activate the virtual environment |
| 10 | +source .venv/bin/activate |
| 11 | +``` |
| 12 | + |
| 13 | +## Python Style Guidelines |
| 14 | +**CRITICAL**: Follow the principles from `/vitals/specs/coding_style.md`. DO NOT OVERENGINEER. Always find the right balance between clarity and complexity. |
| 15 | + |
| 16 | +### Core Principles (from specs/coding_style.md) |
| 17 | +1. **Favor Simplicity Over Complexity** |
| 18 | + - Always choose simple, straightforward solutions |
| 19 | + - Avoid over-engineering and elaborate abstractions |
| 20 | + - No premature optimization |
| 21 | + - If there are two ways to solve a problem, choose the easier to understand |
| 22 | + |
| 23 | +2. **Clarity is Key** |
| 24 | + - Readable code beats clever code |
| 25 | + - Use clear, descriptive names |
| 26 | + - Reduce cognitive load |
| 27 | + - Code should express intent clearly at a glance |
| 28 | + |
| 29 | +3. **Write Pythonic Code** |
| 30 | + - Follow Python community standards and idioms |
| 31 | + - Use list comprehensions, generators, context managers appropriately |
| 32 | + - Write code that looks like Python wrote it |
| 33 | + |
| 34 | +4. **Don't Repeat Yourself (DRY)** |
| 35 | + - Avoid code duplication |
| 36 | + - Use functions and modules for common logic |
| 37 | + - But don't abstract too early |
| 38 | + |
| 39 | +5. **Focus on Readability First** |
| 40 | + - PEP8 is a guide, not a law |
| 41 | + - Readability trumps mechanical adherence to style rules |
| 42 | + - Consider the human reader first |
| 43 | + |
| 44 | +6. **Embrace Conventions** |
| 45 | + - Follow established patterns consistently |
| 46 | + - Use PEP8 as baseline but prioritize readability |
| 47 | + |
| 48 | +### Type Hints Guidelines |
| 49 | +**IMPORTANT**: Do not overengineer type hints. Find the right balance: |
| 50 | +- Use type hints for function signatures and class attributes |
| 51 | +- Keep type hints simple and readable |
| 52 | +- Don't create complex type aliases unless they add clarity |
| 53 | +- Avoid overly generic or abstract type definitions |
| 54 | +- If a type hint makes code harder to read, reconsider it |
| 55 | + |
| 56 | +## Project Structure |
| 57 | +``` |
| 58 | +vitals/ |
| 59 | +├── biomarkers/ # Common biomarker utilities |
| 60 | +│ ├── schemas.py # Pydantic models for biomarker data |
| 61 | +│ ├── helpers.py # Helper functions for biomarker extraction |
| 62 | +│ └── io.py # Input/output utilities |
| 63 | +├── phenoage/ # PhenoAge algorithm implementation |
| 64 | +│ └── compute.py # PhenoAge calculation logic |
| 65 | +├── score2/ # SCORE2 CVD risk algorithm |
| 66 | +│ └── compute.py # SCORE2 calculation logic |
| 67 | +└── specs/ # Project specifications |
| 68 | + ├── coding_style.md # Python coding style guide |
| 69 | + └── score2.md # SCORE2 algorithm specification |
| 70 | +``` |
| 71 | + |
| 72 | +## Development Workflow |
| 73 | + |
| 74 | +### Before Starting Work |
| 75 | +1. Activate virtual environment: `source .venv/bin/activate` |
| 76 | +2. Ensure git hooks are installed: `make install` (this also installs pre-commit hooks) |
| 77 | + |
| 78 | +### Running Tests |
| 79 | +```bash |
| 80 | +# Run tests with coverage report |
| 81 | +make test |
| 82 | + |
| 83 | +# Run linting |
| 84 | +make lint |
| 85 | +``` |
| 86 | + |
| 87 | +### Git Commit Process |
| 88 | +**CRITICAL**: Before ANY commit: |
| 89 | +1. Ensure pre-commit hooks are active (installed via `make install`) |
| 90 | +2. If pre-commit hooks are not running automatically: |
| 91 | + - STOP and inform that git hooks need to be activated |
| 92 | + - Uncommit any changes |
| 93 | + - Run: `make install` to install pre-commit hooks |
| 94 | +3. Pre-commit will run: |
| 95 | + - Code formatting (black, isort) |
| 96 | + - Linting (flake8, mypy) |
| 97 | + - Other configured checks |
| 98 | + |
| 99 | +### Code Quality Checks |
| 100 | +Before committing changes, ensure: |
| 101 | +- [ ] Virtual environment is activated |
| 102 | +- [ ] Code follows the style guidelines in `/vitals/specs/coding_style.md` |
| 103 | +- [ ] Type hints are balanced (not overengineered) |
| 104 | +- [ ] All functions have clear docstrings |
| 105 | +- [ ] No unnecessary code duplication |
| 106 | +- [ ] Variable and function names are descriptive |
| 107 | +- [ ] Tests pass: `make test` |
| 108 | +- [ ] Linting passes: `make lint` |
| 109 | +- [ ] Pre-commit hooks pass |
| 110 | + |
| 111 | +## Common Patterns |
| 112 | +- Use Pydantic BaseModel for data validation |
| 113 | +- Extract biomarkers using `helpers.extract_biomarkers_from_json()` |
| 114 | +- Follow the module structure established in phenoage when adding new algorithms |
| 115 | +- Use boolean types for binary values, not integers |
| 116 | +- Keep type hints simple and practical |
| 117 | + |
| 118 | +## Testing Approach |
| 119 | +When implementing new features: |
| 120 | +1. Check for existing test patterns in the codebase |
| 121 | +2. Write tests that are simple and clear |
| 122 | +3. Ensure edge cases are handled properly |
| 123 | +4. Validate calculations against known results when possible |
| 124 | +5. Run tests before committing: `make test` |
| 125 | + |
| 126 | +## Important Notes |
| 127 | +- The Score2 implementation uses Belgium (Low Risk region) calibration by default |
| 128 | +- Binary values (sex, smoking) should use boolean types in schemas |
| 129 | +- Always handle potential ValueError exceptions when extracting biomarkers |
| 130 | +- Balance code quality with pragmatism - don't overengineer solutions |
0 commit comments