agentleFS
andrew-blakeandrew-blake/melcloudhome/CLAUDE.md

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:

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
  1. Very specific:

    Test entities through hass.states and hass.services ONLY

    line 96
  2. Distinctive:

    Import/test coordinator or entity classes directly

    line 101
  3. Distinctive:

    If you need to make more edits, return to step 2

    line 115
  4. Distinctive:

    NEVER work around pre-commit hooks - they are important code quality checks

    line 119
  5. Very specific:

    Run /security-review on substantive PRs (new code paths, auth/API changes, workflow changes) before merge.

    line 123
  6. Distinctive:

    Never commit cassettes/captures without confirming VCR scrubbing covered them (gitleaks pre-commit hook is a backstop, not the primary …

    line 125
  7. Distinctive:

    Keep under ~150 lines - this is a guide, not detailed documentation

    line 136
  8. Distinctive:

    NO file trees - they go stale immediately

    line 137
  9. Distinctive:

    NO duplicated content - link to detailed docs instead

    line 138
  10. Distinctive:

    Only include content that doesn't exist elsewhere: command quick reference, Claude-specific reminders

    line 140

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 coverage

Documentation 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-design skill 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-body skill 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.states and hass.services ONLY
  • Mock MELCloudHomeClient at 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.data directly

Study working examples: tests/integration/test_climate_ata.py, tests/integration/test_climate_atw.py

Pre-commit Hooks

CRITICAL WORKFLOW RULE:

  1. Make all your changes
  2. Run make pre-commit
  3. DO NOT make ANY edits after this point
  4. Immediately run git commit
  5. 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-review on 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?"

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.