Как я собрал интеграцию для Home Assistant с Claude Code

Когда нужной интеграции не существует

Вы купили устройство для умного дома, открыли браузер, зашли на HACS — и ничего не нашли. Интеграция отсутствует. В GitHub Issues висит тред «Add support for X» трёхлетней давности с пятнадцатью 👍 и нулём коммитов. Знакомая история.

Именно в такой ситуации оказался разработчик, за опытом которого мы наблюдаем в этом материале. Он несколько лет поддерживал ha-meural — кастомную интеграцию для цифровых фоторамок NETGEAR Meural Canvas в Home Assistant. Но потом появилось новое устройство, для которого не было совсем ничего. И тут в игру вошёл Claude Code.

«Я не собираюсь убеждать вас, что разработчики больше не нужны. Скорее — что теперь можно решить небольшую задачу, даже если знаний чуть-чуть не хватает.»

Что такое Claude Code и почему он меняет правила

Claude Code — это агентный инструмент для написания кода, который читает кодовую базу, редактирует файлы, запускает команды и интегрируется с вашими инструментами разработки. Но это лишь техническое определение. На практике разница куда более радикальная.

Традиционные AI-ассистенты вроде GitHub Copilot предлагают автодополнение внутри IDE. Claude Code использует принципиально другой подход — он работает прямо в терминале и взаимодействует с файловой системой и инструментами командной строки.

Claude Code работает на уровне проекта: читает всю кодовую базу, планирует подход охватывая несколько файлов сразу, вносит изменения, запускает тесты и итерирует при ошибках. Разработчик задаёт цель и проверяет результат, а не ведёт агента за руку на каждом шагу.

Запущенный в виде исследовательского превью в феврале 2025 года и получивший статус общедоступного в мае 2025-го, Claude Code быстро вырос из нишевого эксперимента до продукта с оборотом в миллиард долларов. К концу 2025 года он достиг $1 млрд в пересчёте на год всего за шесть месяцев.

Шаг 1: Рефакторинг существующей интеграции

Прежде чем браться за создание интеграции с нуля, автор решил проверить Claude Code на уже знакомом коде — шестилетнем проекте ha-meural.

Он загрузил репозиторий в Claude Code, включил режим планирования и дал простой промпт: «Модернизируй эту интеграцию и приведи её в соответствие с актуальными практиками Home Assistant».

Изучив предложенный план, автор пришёл к очевидному выводу: он понимал предлагаемые изменения и причины, по которым они были бы улучшением, — но самостоятельно реализовать их не смог бы. Был реальный разрыв между уровнем его навыков программирования и тем, что требовалось интеграции.

Это важный момент: Claude Code не заменяет понимание — он заполняет разрыв между «понимаю архитектуру» и «умею реализовать».

После нескольких исчерпаний лимита токенов (стоило заранее перейти на нормальный план) новая, блестящая версия ha-meural была готова. Установив её в Home Assistant в ожидании катастрофы — она просто работала. Даже лучше: Claude тихо исправил несколько багов, которые давно раздражали, но были вне зоны досягаемости автора.

Итог первой итерации по версиям

Несколько итераций спустя Claude реализовал каждую функцию, которая годами висела в вишлисте.

Шаг 2: Интеграция с нуля — Tuneshine и локальный API

Настоящий тест начался, когда нужно было создать интеграцию без какого-либо существующего кода как основы.

Устройство Tuneshine — дисплей 64×64 пикселя, показывающий абстрактные образы воспроизводимой музыки — до этого момента полностью зависело от удалённого облачного сервера. Но в свежем Newsletter Tuneshine объявили о добавлении локального API.

Документация API была загружена в Claude с простым заданием: написать кастомную интеграцию для Home Assistant с нуля. Никакого кода-основы — только документация для разработчиков HA и минимальная API-спецификация Tuneshine.

Как выглядел воркфлоу

graph TD
    A[Получена API-документация Tuneshine] --> B[Передача в Claude Code с промптом]
    B --> C[Claude генерирует структуру интеграции]
    C --> D{Тест в Home Assistant}
    D -->|Ошибка JSON-формата| E[Передать IP устройства Клоду]
    E --> F[Claude анализирует реальные ответы API]
    F --> G[Исправление кода + сохранение эталонных данных]
    G --> H{Повторный тест}
    H -->|Успех| I[Рабочая интеграция]
    H -->|Новая проблема| F

Шаг 3: Управление Home Assistant через терминал

Помимо создания интеграций, Claude Code открывает ещё один мощный сценарий — прямое управление конфигурацией Home Assistant.

Один из разработчиков создал аддон, который интегрирует Claude Code прямо в Home Assistant — можно создавать автоматизации, отлаживать конфигурации и управлять умным домом на естественном языке через браузерный терминал.

Типичный сетап выглядит так: SSH-подключение к HA, запуск Claude Code из терминала, Cursor как редактор для просмотра файлов. Но большую часть времени — просто разговор с Claude в терминале. Yaml-конфиги, накопленные годами, теперь можно модифицировать в разговорном режиме.

CLAUDE.md — это markdown-файл в корне проекта, который Claude Code читает в начале каждой сессии. Его используют для задания стандартов кода, архитектурных решений, предпочтительных библиотек и чеклистов проверки.

# Пример CLAUDE.md для проекта Home Assistant
## Проект: Умный дом
- Используй async/await для всех IO-операций
- Все интеграции должны следовать паттерну config_flow
- Тестируй на реальном устройстве перед коммитом
- HA minimum version: 2024.1

Claude Code vs традиционная разработка: честное сравнение

Важно не впасть в крайности — ни в «AI заменит всех разработчиков», ни в «это просто автодополнение». Подход здесь не «теперь любой может создавать приложения». Скорее — «у меня есть базовое понимание, но недостаточно для превращения в рабочий код».

Внутренний опрос Anthropic среди 132 инженеров показал: около 27% задач, выполненных с помощью Claude Code, — это работа, которую вообще не стали бы делать без этого инструмента. Архитектура позволяет реализовывать качественно новые рабочие процессы, а не просто ускорять существующие.

Claude Code требует явного разрешения перед изменением файлов или запуском команд, работает в существующей среде разработчика и использует его инструменты. Решения о том, какой код в итоге попадёт в продакшн, остаются за человеком.

Практические уроки: что работает, а что нет

На основе реального кейса можно выделить несколько важных паттернов:

1. Режим планирования перед действием Прежде чем давать Claude Code carte blanche, включайте plan mode. Это позволяет убедиться, что агент правильно понял задачу — особенно при работе с большими и незнакомыми кодовыми базами.

2. Давайте реальный контекст Чем больше контекста — тем лучше результат. Документация API, примеры существующих интеграций, описание конкретного устройства — всё это существенно улучшает качество генерируемого кода.

3. Проверяйте спецификации API самостоятельно Как показал кейс с Tuneshine — даже официальная документация может содержать ошибки. Claude Code умеет адаптироваться к реальному поведению устройства, но вы должны дать ему возможность это сделать (передать IP, разрешить прямое подключение).

4. Управляйте токенами осознанно Claude также строит автоматическую память в процессе работы, сохраняя полезные данные — например, команды сборки и инсайты по отладке — между сессиями, без необходимости что-либо записывать вручную. Но при крупных рефакторингах — планируйте бюджет токенов заранее.

5. Итерируйте, а не ждите идеального результата с первого раза Когда тесты падают, Claude Code читает ошибки, исправляет код и запускает тесты снова до тех пор, пока всё не пройдёт. Он следит за CI-пайплайнами на GitHub и GitLab и автоматически коммитит исправления.

Заключение: новый класс разработчиков

История с интеграцией Tuneshine — это не просто кейс «AI написал код». Это демонстрация нового типа взаимодействия между человеком и инструментом.

Claude Code — это агентная система программирования, которая читает вашу кодовую базу, вносит изменения в файлы, запускает тесты и сдаёт готовый код. Для разработчиков без глубокого инженерного бэкграунда это точка входа в разработку программного обеспечения, которой раньше не существовало.

В Anthropic большинство кода теперь пишется с помощью Claude Code. Инженеры фокусируются на архитектуре, продуктовом мышлении и непрерывной оркестрации: управляют несколькими агентами параллельно, задают направление и принимают решения, определяющие, что именно строится.

Если у вашего устройства есть локальный API — у вас теперь есть всё необходимое, чтобы написать интеграцию. Не потому что AI сделает всё за вас. А потому что разрыв между «понимаю задачу» и «умею реализовать» стал преодолимым.