melcloudhome
CLAUDE.md143 starsChanged 38 days agoMITView on GitHub
This file provides quick orientation and navigation for Claude Code when working with this repository. MELCloud Home integration for Home Assistant, distributed via HACS. Supports Air-to-Air (ATA) air conditioning units and Air-to-Water (ATW) heat pumps with full HVAC control, energy monitoring, and zone management. Repository: <https://github.com/andrew-blake/melcloudhome> Key patterns:
In this repository2 other files it gives its agents.
- grounding-a-designSkill
- pr-bodySkill
The file
We split this CLAUDE.md into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 96
Test entities through hass.states and hass.services ONLY
- Distinctive: line 101
Import/test coordinator or entity classes directly
- Distinctive: line 115
If you need to make more edits, return to step 2
- Distinctive: line 119
NEVER work around pre-commit hooks - they are important code quality checks
- Very specific: line 123
Run /security-review on substantive PRs (new code paths, auth/API changes, workflow changes) before merge.
- Distinctive: line 125
Never commit cassettes/captures without confirming VCR scrubbing covered them (gitleaks pre-commit hook is a backstop, not the primary …
- Distinctive: line 136
Keep under ~150 lines - this is a guide, not detailed documentation
- Distinctive: line 137
NO file trees - they go stale immediately
- Distinctive: line 138
NO duplicated content - link to detailed docs instead
- Distinctive: line 140
Only include content that doesn't exist elsewhere: command quick reference, Claude-specific reminders
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides quick orientation and navigation for Claude Code when working with this repository.
What This Repo Is
MELCloud Home integration for Home Assistant, distributed via HACS. Supports Air-to-Air (ATA) air conditioning units and Air-to-Water (ATW) heat pumps with full HVAC control, energy monitoring, and zone management.
Repository: https://github.com/andrew-blake/melcloudhome
Project Context
Distribution & Workflow
- Distribution: HACS (Home Assistant Community Store)
- Branching: GitHub Flow - always use feature branches, never commit directly to main
- Pre-commit hooks: Enforced by git hooks
- Personal setup: See
CLAUDE.local.md(gitignored) for remote HA deployment and diagnostics
Quick Commands
# Setup
uv sync # Install dependencies
source .venv/bin/activate # Activate environment
# Local dev environment (Mock API + Home Assistant)
make dev-up # Start dev environment
make dev-restart # Restart HA after code changes
make dev-logs # View logs
make dev-reset # Clear entity registry, fresh start
# ⚠️ CRITICAL: Enable Advanced Mode in user profile
# to see "Connect to Mock Server" checkbox during setup
# See DEV-SETUP.md section 2.1 for details
# Code quality
make format # Format with ruff
make lint # Lint with ruff
make type-check # Type check with mypy
make pre-commit # Run all pre-commit checks
make zizmor # Security scan workflows (run before pushing workflow changes)
uv run python tools/prose_check.py FILE # Prose conventions for docs, ADRs, PR/issue text (advisory)
# Testing
make test-build # Build Docker test images (after dep changes)
make test-api # API unit tests (VCR, no Docker)
make test-integration # Integration tests (Docker, mocked API)
make test-integration-floor # Same suite on the hacs.json HA floor
make test-e2e # E2E tests (Docker, mock server)
make test # All tests with coverageDocumentation Navigator
Architecture & Design
- Architecture overview:
docs/architecture.md- System architecture, multi-device patterns, 3-way valve behavior - Entity reference:
docs/entities.md- All entities, entity ID convention, capabilities - Architecture decisions:
docs/decisions/- ADRs documenting key technical decisions - Before proposing or reviewing a design: the
grounding-a-designskill in.claude/skills/grounding-a-design/- inventory every ADR and record the design touches before writing any design text - Code structure: Browse
custom_components/melcloudhome/- Multi-device architecture with ATA/ATW separation
Key patterns:
- Bundled API client: Library in
api/subfolder - facade pattern composing ATA + ATW clients - Multi-device architecture: Platform routers dispatch to device-specific implementations
- Entity IDs: UUID-based for stability - see
docs/entities.md
API Documentation
- ATA (Air-to-Air) API:
docs/api/ata-api-reference.md - ATW (Air-to-Water) API:
docs/api/atw-api-reference.md - Device comparison:
docs/api/device-type-comparison.md
Development Guides
- Local dev setup:
DEV-SETUP.md- Mock server, Docker Compose environment, Advanced Mode setup - Testing standards:
docs/testing-best-practices.md- HA-specific testing patterns, anti-patterns, debugging - Testing strategy:
docs/testing-strategy.md- Test types, when to use each - Deployment tools:
tools/README.md- Automated deployment, remote testing - Release process:
docs/release-process.md- Release + beta workflows - Writing a PR description: the
pr-bodyskill in.claude/skills/pr-body/- required sections, the title as an H1, and what a Testing box may claim
Research & Tools
- Reverse engineering:
docs/research/REVERSE_ENGINEERING.md- API discovery without hardware - RE tools:
tools/reverse-engineering/- Chrome overrides, request proxying - Research archive:
docs/archive/research/- Historical planning docs
Home Assistant Integration Testing
Critical anti-patterns (Claude commonly violates these):
✅ DO:
- Test entities through
hass.statesandhass.servicesONLY - Mock
MELCloudHomeClientat API boundary
❌ NEVER:
- Import/test coordinator or entity classes directly
- Assert internal method calls (e.g.,
coordinator.async_set_temperature.assert_called_once()) - Manipulate
coordinator.datadirectly
Study working examples: tests/integration/test_climate_ata.py, tests/integration/test_climate_atw.py
Pre-commit Hooks
CRITICAL WORKFLOW RULE:
- Make all your changes
- Run
make pre-commit - DO NOT make ANY edits after this point
- Immediately run
git commit - If you need to make more edits, return to step 2
Why: Pre-commit hooks only check staged files during commit. If you run make pre-commit, then edit files, then commit - the commit hooks will catch unformatted code and fail.
- NEVER work around pre-commit hooks - they are important code quality checks
Security Practices
- Run
/security-reviewon substantive PRs (new code paths, auth/API changes, workflow changes) before merge. - Never commit cassettes/captures without confirming VCR scrubbing covered them (gitleaks pre-commit hook is a backstop, not the primary control).
About This File
Purpose: Navigation index and quick command reference for Claude Code.
Principles:
- Keep under ~150 lines - this is a guide, not detailed documentation
- NO file trees - they go stale immediately
- NO duplicated content - link to detailed docs instead
- Personal setup (SSH, deployment) goes in
CLAUDE.local.md(gitignored) - Only include content that doesn't exist elsewhere: command quick reference, Claude-specific reminders
When adding content, ask: "Does this belong in a detailed doc that I should link to instead?"
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

