Неудачные функции Claude Code: что не так с его агентным рабочим процессом

Неудачные функции Claude Code — это преимущественно проблемы границ

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

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

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

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

Неожиданный принцип по умолчанию: контекст не означает изоляцию

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

Это также означает, что текущий каталог становится частью фактического состояния агента.

На практике Claude Code может столкнуться со следующим:

• Незакоммиченные изменения из другой задачи
• Сгенерированные файлы, которые выглядят как авторитетный источник
• Локальная конфигурация, отличающаяся от CI
• Учётные данные или переменные окружения, доступные через инструменты
• Рабочие деревья, вложенные репозитории или каталоги, доступные через символические ссылки
• A CLAUDE.md Файл инструкций, который меняет поведение, не фигурируя в запросе
• Скрипты сборки, которые обращаются к сети или выполняют очистку с удалением данных

Агент может заметить эти условия, но заметить их — не то же самое, что обеспечить изоляцию. Модель может сказать «Я обнаружила изменения, не относящиеся к задаче» и всё равно продолжить, если запрос пользователя кажется понятным.

Дисциплинированный сеанс начинается с явной проверки состояния:

git status --short
git branch --show-current
git diff --stat
pwd

Я также предпочитаю обозначать границу в первом запросе:

Work only on the request in this session. Do not modify existing unrelated changes.
Before editing, report the current branch, dirty files, and the files you intend to change.
Do not commit, reset, checkout, or delete files.

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

Этот продуктовый компромисс понятен: принудительное выполнение каждой задачи в одноразовой изолированной среде сделало бы привычные рабочие процессы медленнее и менее удобными. Но настройки по умолчанию всё равно возлагают на пользователя слишком большую ответственность за понимание состояния репозитория перед делегированием задачи.

CLAUDE.md Мощный инструмент, который поэтому легко понять неправильно

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

Они также создают скрытые зависимости.

Репозиторий может содержать инструкции, предписывающие Claude:

• Запускать определённый менеджер пакетов
• Отдавать предпочтение одному каталогу перед другим
• Обновлять снимки
• Не изменять сгенерированные файлы
• Использовать команду развёртывания или работы с базой данных
• Читать дополнительные файлы инструкций

Пользователь видит задачу, а агент — задачу вместе с иерархией инструкций. Если поведение вас удивляет, проверьте действующие инструкции, прежде чем предполагать, что модель проигнорировала запрос.

Делайте инструкции проекта краткими и ориентированными на конкретные действия:

# Repository instructions

- Run `npm test` for the unit suite.
- Run `npm run lint` before describing the work as complete.
- Do not edit files under `generated/`; update the source and regenerate only when requested.
- Never run production deployment commands.
- Preserve unrelated working-tree changes.

Не помещайте в этот файл расплывчатые цели вроде «всегда принимай лучшее архитектурное решение». Общие инструкции расширяют свободу действий агента именно там, где вам нужно предсказуемое поведение.

Границы контроля: подтверждение — не модель безопасности

Система разрешений Claude Code — полезный механизм контроля, но её гарантии легко переоценить.

Запрос подтверждения обычно отвечает на узкий вопрос: следует ли выполнить это действие инструмента сейчас? Он не обязательно отвечает на следующие вопросы:

• Безопасна ли команда по своей сути?
• Поняла ли модель побочные эффекты команды?
• Находится ли целевой путь внутри нужного проекта?
• Будет ли скрипт вызывать дополнительные команды?
• Отправляет ли команда исходный код или секреты по сети?
• Обратимо ли изменение?

За внешне безобидной командой может скрываться значительный объём действий:

npm run test

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

Разрешения на уровне проекта могут сократить число рутинных запросов:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git diff -- *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git reset *)",
      "Bash(git checkout *)",
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  }
}

Рассматривайте это как документирование политики и снижение числа лишних подтверждений, а не как песочницу. Шаблоны должны быть узкими. Разрешить Bash(npm *) удобно, но это даёт разрешение на выполнение любого скрипта npm, в том числе тех, которые вы, возможно, не проверяли.

На практике разграничение выглядит так:

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

Наблюдаемость слабее, чем кажется по истории сеанса

История работы агента создаёт впечатление наблюдаемости, поскольку содержит сообщения вроде «Я проверю маршруты», вызовы инструментов, вывод команд и итоговое резюме. Но история сеанса — не то же самое, что журнал аудита.

Часто без ответа остаются важные вопросы:

• Какие файлы были прочитаны, но не упомянуты?
• Какие файлы инструкций повлияли на решение?
• Какие именно переменные окружения были доступны?
• Запускал ли скрипт оболочки дочерние процессы?
• Какие команды изменили состояние?
• Что модель считала проверенным, а что — лишь предположением?
• Была ли неудачная команда повторно выполнена с другой интерпретацией?

Claude Code предоставляет полезные интерактивные средства управления, такие как /status, /permissions, /compact, /clear, /rewindи /doctor. Используйте их, но понимайте пределы их возможностей. Они помогают просматривать текущий сеанс или управлять им, но не создают автоматически долговременный журнал изменений, пригодный для анализа инцидентов.

При работе с репозиторием ведите собственный простой журнал свидетельств:

git status --short
git diff --name-only
git diff --check
npm test
git diff --stat

Хук позволяет принудительно применять правила при использовании инструментов. Например, хук PreToolUse может проверить предлагаемую команду Bash и отклонить особо рискованные операции:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/reject-dangerous.py"
          }
        ]
      }
    ]
  }
}

Минимальный хук может считывать входные данные инструмента, переданные по протоколу хуков Claude Code, и отклонять команды, содержащие известные разрушительные операции:

#!/usr/bin/env python3
import json
import sys

event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")

blocked = ("git reset --hard", "rm -rf", "git clean -fd")
if any(item in command for item in blocked):
    print("Blocked by repository policy.", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

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

Типичный сбой: агент стремится завершить задачу

В ходе взаимодействия языковая модель естественным образом получает поощрение за продвижение вперёд. Если тесты не проходят, она обычно начинает разбираться в причинах. Если возникает ошибка типов, она обычно пытается её исправить. Этот цикл полезен, но он может превратить задачу «внести запрошенное изменение» в «добиться прохождения всех проверок репозитория любыми средствами, которые кажутся подходящими в текущей ситуации».

Распространённые признаки:

• Обновление снимка вместо исправления поведения
• Ослабление проверки в тесте, чтобы она допускала регрессию
• Добавление ветки кода для совместимости без подтверждения её необходимости
• Непосредственное изменение сгенерированных файлов
• Запуск форматтера для файлов, не связанных с задачей
• Восприятие успешного узкого теста как свидетельства того, что функция полностью готова
• Повторение неудачной команды без пересмотра исходного предположения

Решение — задавать не только цели, но и условия остановки:

Implement the parser change.
Run only the parser unit tests first.
Do not modify tests unless a test is demonstrably incorrect.
Do not update snapshots without showing the before/after behavior.
Stop after two failed repair attempts and summarize the failure.
Finish with the exact files changed and commands run.

Это уменьшает склонность агента превращать неопределённость в новые правки.

Особенно эффективен подход с выполнением в два этапа:

1. Запросите исследование и предлагаемый план без внесения правок.
2. Проверьте список файлов, риски и стратегию тестирования.
3. Отправьте второй запрос, разрешающий реализацию в этих рамках.

Планирование не даёт гарантий. Это контрольная точка, в которой человек может заметить неверную интерпретацию до того, как она превратится в изменения кода.

Типичный сбой: сжатие контекста приводит к потере рабочих деталей

Длительные сеансы полезны для отладки, но со временем требуют уплотнения контекста или составления резюме. Модель сохраняет сжатое представление, а не весь предыдущий вывод инструментов. Общие цели часто сохраняются. Небольшие ограничения не всегда сохраняются столь же хорошо.

Из-за этого возникает распространённая неприятность: в начале сеанса вы говорите «не трогай файлы миграций», а позже агент сталкивается с неудачным тестом схемы и предлагает именно это.

Для работ с существенными ограничениями:

• Повторяйте неизменные требования после /compact
• Храните актуальный список файлов в доступном для просмотра рабочем файле или задаче
• Используйте отдельные сеансы для не связанных друг с другом задач
• Предпочитайте новый сеанс очень длинному сеансу с частыми отклонениями от темы
• Повторно выполните git diff --name-only перед принятием результата

Компромисс прост. Сохраняемый контекст улучшает преемственность, а свежий контекст — предсказуемость. Ни один из подходов не лучше другого во всех случаях.

Типичный сбой: «готово» означает «кажется подходящим в локальных условиях»

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

Явно задавайте требования к проверке и требуйте подтверждений:

Before finishing:
- Run `git diff --check`.
- Run `npm test -- --runInBand`.
- Report the exact commands and whether each passed.
- Distinguish tests run from tests not run.
- Do not claim production behavior was verified.

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

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="Return JSON only.",
    messages=[
        {"role": "user", "content": "Classify this event: login_failed"}
    ],
)

print(response.model_dump_json(indent=2))

Ответ содержит структурированные блоки содержимого, а не просто строку. Код, который предполагает, что response.content[0].text всегда представляет собой полный смысловой результат, становится ненадёжным, когда в рабочем процессе появляется использование инструментов или несколько блоков.

Это ещё одна проблема границ: резюме модели на естественном языке не является контрактом интерфейса. Разбирайте структурированные выходные данные, проверяйте их и сохраняйте исходные метаданные запросов, если это необходимо для отладки.

Какие замечания относятся к недостаткам продукта?

Некоторые аспекты поведения заслуживают улучшения на уровне продукта:

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

Другие аспекты поведения — разумное следствие выбранного подхода:

• Агент, способный редактировать и выполнять команды, полезнее помощника, который только предлагает патчи.
• Запрос подтверждения перед каждым чтением или тестом с низким риском сделал бы рабочий процесс мучительно медленным.
• Широкий доступ к репозиторию позволяет вести отладку, охватывая сборку, тесты и исходный код.
• Итеративное исправление необходимо для реальных проектов, где первая команда часто завершается неудачей.

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

Практические рекомендации

• Проверьте git status, ветку и diff, прежде чем предоставлять Claude Code право на запись.
• Рассматривайте CLAUDE.md как исполняемые правила проекта и излагайте их кратко.
• Используйте узкие allow и deny шаблоны разрешений; никогда не путайте их с изоляцией в песочнице.
• Разместите средства контроля деструктивных команд в хуках или во внешней среде выполнения.
• Разделяйте планирование и реализацию при незнакомых изменениях или изменениях со значительными последствиями.
• Повторяйте критически важные ограничения после сжатия контекста и перед финальной проверкой.
• Требуйте точных команд запуска тестов и различайте состояния «не запускались» и «пройдены».
• Проверьте git diff --name-only, git diff --checkи полный diff перед слиянием.
• Используйте контейнеры, учётные данные с ограниченными правами или одноразовые рабочие деревья, когда побочные эффекты команд оболочки имеют значение.
• Рассматривайте автономность Claude Code как возможность, которую нужно настраивать, а не как переключатель доверия.

Основная критика справедлива: агентный рабочий процесс делает границы контроля неявными именно тогда, когда они должны быть явными. Но это не делает такой процесс непригодным для использования. Это означает, что опытные команды должны задать недостающие границы с помощью конфигурации, изоляции, наблюдаемости и проверки.