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 - Project planning and roadmap
• PROJECT-PATTERNS.md - Project structure and design patterns
• API-ENDPOINTS.md - API endpoints overview
• SoundTouch Web API.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