# CLAUDE.md - Development Guidelines for Bose SoundTouch Project

## Documentation Overview

This document contains important development guidelines for working on the Bose SoundTouch project. Please also read the following documentation:

- **[PLAN.md](archive/PLAN.md)** - Project planning and roadmap
- **[PROJECT-PATTERNS.md](PROJECT-PATTERNS.md)** - Project structure and design patterns
- **[API-ENDPOINTS.md](reference/API-ENDPOINTS.md)** - API endpoints overview
- **[SoundTouch Web API.pdf](2025.12.18%20SoundTouch%20Web%20API.pdf)** - Official API documentation

## Development Guidelines

### 1. Tests are Mandatory

- **Implementation always with tests**: Every new functionality must be developed with corresponding tests
- **Unit tests preferred**: Where possible, unit tests should be written
- **Integration tests as alternative**: If unit tests are not practical, implement integration tests via mock servers
- **Sample data from live system**: Request/response data can be taken from a real SoundTouch system as examples
- **Respect privacy**: All personal data must be anonymized before use in tests

### 2. Cross-Platform Compatibility

The project must work on the following platforms:
- **Windows**
- **macOS** 
- **Linux**
- **WASM** (WebAssembly)

Platform-specific implementations are only allowed in justified exceptional cases.

### 3. KISS Principle (Keep It Simple, Stupid)

- Simplicity has top priority
- Complex solutions only when absolutely necessary
- Code should be self-explanatory and well readable
- Avoid over-engineering

### 4. Small Steps and Communication

- **Small, iterative steps**: Break large features into smaller, testable units
- **Don't hallucinate**: Don't make assumptions about unclear requirements
- **Ask instead of guess**: Always ask when unclear instead of speculating
- **Transparency**: Openly communicate uncertainties and limitations

### 5. Use Current Libraries

- Use current and well-maintained libraries where possible
- Regularly update outdated dependencies
- Apply security updates promptly
- Ensure compatibility with Go modules

### 6. Web-Specific Implementation

For web components:
- **Prefer plain HTML/JS/CSS**: Avoid heavy frameworks where possible
- Use modern web standards (ES6+, CSS Grid/Flexbox)
- Apply progressive enhancement
- Consider accessibility (a11y)
- Implement responsive design

## Build and Development Guidelines

### 7. Build Directory Structure

- **Use Makefile for building**: Always use `make build` instead of direct `go build` commands
- **Build directory**: All binaries must be created in the `./build/` directory
- **Example**: Use `make build` to create `./build/soundtouch-cli`, not `./soundtouch-cli`
- **Cross-platform builds**: Use `make build-all` for multi-platform binaries

### 8. Real Device Test Data

When creating test data for API endpoints, prefer real device responses over hypothetical examples:

- **Available test endpoints**:
  - `http://192.168.178.28:8090/now_playing` - Different response type 1
  - `http://192.168.178.35:8090/now_playing` - Different response type 2
- **Usage**: Fetch real responses to create accurate test fixtures
- **Privacy**: Anonymize any personal data (account names, personal playlists, etc.)
- **Coverage**: Use multiple real devices to cover different response variations
- **Non-responsive endpoints**: Some endpoints like `/trackInfo` may not respond or exist on all devices

### 9. File Operations Safety

- **Never delete files** - use move/rename instead when possible
- **Ask before destructive operations** - especially for config files (.env, *.config, etc.)
- **Prefer non-destructive operations** - copy, move, rename over delete
- **Respect user data** - treat all user files as potentially containing sensitive data
- **Configuration files are sacred** - .env, config files may contain secrets and personal settings

## Additional Notes

- **Language: English** for code, commits, labels, and text in code
- Code comments in English
- **Documentation**: Completely in English for international accessibility
- Conduct regular code reviews
- Consider performance from the beginning
