Claude Code на Windows: пять подводных камней, которые ломают автоматизацию
Habr AI · оригинал
Материал подготовлен автоматизированной редакционной системой. Факты можно сверить по указанному первоисточнику.
Разработчик описывает типичные проблемы при работе с агентом Claude Code в нативной среде Windows без WSL. Статья разбирает конфликты версий PowerShell, особенности поиска процессов и нюансы работы с дисковой подсистемой.
Материал актуален для инженеров, использующих ИИ-агентов в корпоративных средах Windows, где стандартные скрипты под Linux/macOS часто дают сбои из-за различий в системных утилитах и кодировках.
Большинство документации по Claude Code ориентировано на экосистему macOS и Linux. Однако для задач, требующих глубокой интеграции с браузерной автоматизацией и живыми профилями Chrome, многие разработчики предпочитают работать в нативном окружении Windows без использования WSL. По наблюдениям автора, сам агент функционирует стабильно, но критические сбои возникают на стыке взаимодействия с системными компонентами: PowerShell 5.1, кодировками файлов и механизмами управления процессами. Чтобы избежать повторных ошибок, автор зафиксировал пять ключевых правил в памяти агента.
Первая серьезная проблема связана с устаревшей версией PowerShell 5.1, которая поставляется с Windows. ИИ-модели обучены на современном bash и pwsh, поэтому они регулярно используют операторы && и ||, которые в версии 5.1 отсутствуют. Это приводит к ошибкам парсинга. Кроме того, перенаправление stderr через 2>&1 для внешних программ вроде git или npm приводит к тому, что переменная $? становится ложной даже при успешном выполнении. Автор рекомендует использовать конструкцию A; if ($?) { B } и проверять код выхода через $LASTEXITCODE.
Вторая засада касается кодировок. Команда Set-Content по умолчанию использует системную ANSI-кодировку, что приводит к искажению кириллических символов в конфигурационных файлах. Использование Out-File с UTF-8 может создавать BOM, ломающий парсеры JSON. Решение — запретить агенту писать файлы через шелл и использовать встроенные инструменты записи или явно указывать кодировку utf8.
Третья проблема возникает при управлении процессами. Python из Microsoft Store отображается в системе не как python.exe, а как python3.10.exe. Если агент ищет процесс по имени, он может ошибочно полагать, что скрипт остановлен, хотя он продолжает работать. Это приводило к конфликтам при использовании одного профиля Chrome несколькими экземплярами. Теперь поиск осуществляется по полной командной строке процесса.
Четвертый нюанс касается переменных окружения. Агент работает в изолированной среде, где PATH может отличаться от пользовательского терминала. Если команда вроде go не находится, необходимо указывать полный путь к исполняемому файлу. Также отмечено странное поведение классификатора безопасности: go test по полному пути проходит, а go vet блокируется.
Пятая проблема связана с сетевыми хостами. В Next.js 16 dev-режим блокирует HMR-вебсокет при обращении через 127.0.0.1, требуя использования localhost. Игнорирование этого правила приводит к зависанию интерфейса на скелетоне, хотя API работает корректно.
Наконец, автор описывает проблему производительности при работе с профилями Chrome на HDD. Высокая нагрузка на диск (disk time 168%) вызывала таймауты при открытии отладочного порта. Перенос профилей на SSD и их немедленное удаление после использования решили проблему. Важно также помнить, что файлы профиля блокируются Windows, пока активен процесс chrome.exe, и нельзя убивать процессы по шаблону имени, если работают параллельные сессии агента.
Все эти правила собраны в единый блок для файла CLAUDE.md, который можно использовать как готовый шаблон. Это позволяет агенту сразу учитывать специфику Windows-окружения и избегать типовых ошибок, экономя время разработчика на отладку системных конфликтов.