В этой статье мы погрузимся во внутреннее устройство Claude Code - Coding агента от Anthropic. Мы проанализируем его с точки зрения архитектуры, рассмотрим доступные инструменты и разберем системные промпты, которые определяют его поведение.

Я заменил его стандартную модель claude на GPT-4.1, что позволило мне детально проанализировать логи, архитектуру и системные промпты, определяющие его поведение.

Начнем с основ. В Claude Code используется архитектура ReAct - агнета (Reasoning and Acting), которая позволяет агенту взаимодействовать с окружением через набор специализированных инструментов для выполнения задач.

Доступные Tools - Claude Code

Агент имеет доступ к следующим инструментам:

Инструменты для работы с файлами и кодом

Инструменты для поиска и навигации

Инструменты для управления задачами и выполнения команд

⚠️Полное описание всех инструментов с параметрами я выложил на GitHub — так же ссылка доступна в моем Telegram-канале.

Системный промпт

Если общий объем описания только инструментов составляет около 10,000 токенов, то системный промпт добавляет еще - 2,700 токенов, который подробно описывает задачи, возможности и ограничения агента, с постоянными напоминаниями о недопустимости создания вредоносного кода.

Ключевые особенности промпта

Few-Shot подход: Активное использование примеров для объяснения правильного поведения. Даже для демонстрации краткости ответов приводятся конкретные примеры.

Неполное описание инструментов: Интересно, что системный промт упоминает только самые критичные инструменты и не предоставляет их исчерпывающий список. Это говорит о том, что Claude, подобно OpenAI, отходит от практики перечисления всех инструментов и их параметров всамом системном промте.

Роль TodoWrite: Центральное место в архитектуре отводится инструменту TodoWrite. Инструкции не просто упоминают его, а настаивают на его "ОЧЕНЬ частом" и "критически важном" использовании, превращая его в фундаментальный механизм для решения сложных задач.

Первое сообщение пользователя и динамический контекст

Подход к обработке первого сообщения пользователя весьма интересен. Помимо основного запроса, в модель передаются системные напоминания:

<system-reminder>
Отвечая на вопросы пользователя, вы можете использовать следующий контекст:
# важные-напоминания-об-инструкциях
Делайте то, о чем вас попросили; ни больше, ни меньше.
НИКОГДА не создавайте файлы, если они не являются абсолютно необходимыми...
ВСЕГДА предпочитайте редактирование существующего файла созданию нового...
</system-reminder>

**Привет, можешь посмотреть в моем терминале какие есть папки?**

<system-reminder>
Это напоминание о том, что ваш список дел в настоящее время пуст...
пожалуйста, используйте инструмент TodoWrite, чтобы создать его...
</system-reminder>

Этот механизм выполняет две функции:

1. Напоминание о правилах: Агенту еще раз напоминают о ключевых правилах работы (не создавать лишние файлы, предпочитать редактирование).

2. Динамический контекст: Система информирует агента, что список TodoWrite пуст, и подталкивает к его использованию при необходимости.

Последующие сообщения пользователя отправляются без дополнительного системного контекста, правда если вы запускаете Calude Code команды, результат этих команд так же попадет в историю сообщений в специальных тегах:

Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to. 
<command-name>/cost</command-name> 
<command-message>cost</command-message> 
<command-args></command-args> 
<local-command-stdout>[2mTotal cost: $0.0000 (costs may be inaccurate due to usage of unknown models)[22m [2mTotal duration (API): 2.5s[22m [2mTotal duration (wall): 21.3s[22m [2mTotal code changes: 0 lines added, 0 lines removed[22m [2mUsage by model:[22m [2mgpt-4.1-nano-2025-04-14: 2 input, 2 output, 0 cache read, 0 cache write[22m</local-command-stdout> Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to. 
<command-name>/status</command-name> 
<command-message>status</command-message> 
<command-args></command-args> 
<local-command-stdout>(no content)</local-command-stdout> 
Посмотри какие есть контейнеры

TodoWrite: управление задачами

Давайте рассмотрим более подробно инструмент TodoWrite.

Он используется для планирования и разбиения сложных задач на управляемые шаги и информирования пользователя о прогрессе.

Основные принципы работы TodoWrite:

• Частое использование: Инструмент используется для любых нетривиальных задач, требующих более двух шагов (но если попросить использовать инструмент в сообщении, то он вызовет его, даже если вы решаете задачу 2+2).

• Управление статусами:

  • pending: Задача ожидает выполнения.

  • in_progress: Задача в процессе выполнения (только одна в данный момент).

  • completed: Задача успешно завершена.

• Строгие правила: Задача отмечается как выполненная ТОЛЬКО после ее полного и безошибочного завершения.

Пример JSON который формируется TodoWrite:

[
  {
    "content": "Создать папку project_ai",
    "status": "pending",
    "priority": "high",
    "id": "1"
  },
  {
    "content": "Создать файл main.py внутри папки project_ai и написать в него простую программу",
    "status": "pending",
    "priority": "high",
    "id": "2"
  },
  {
    "content": "Проверить, создался ли файл и папка успешно",
    "status": "pending",
    "priority": "high",
    "id": "3"
  }
]

Пример последовательности работы

Давайте посмотрим, как TodoWrite используется на практике на примере задачи: "Создай файл README иmain.py".

1. Запрос пользователя: "Создай файл README и main.py с простой программой".

2. Планирование: Ассистент вызывает TodoWrite и создает две задачи со статусом pending.

3. Начало работы: Ассистент снова вызывает TodoWrite, чтобы изменить статус первой задачи на in_progress.

4. Создание файла: Ассистент использует инструмент Write для создания файла README.md.

5. Завершение первой задачи: После успешного создания файла ассистент вызывает TodoWrite, меняя статус первой задачи на completed, а второй — на in_progress.

6. Работа над второй задачей: Процесс повторяется для файла main.py.

7. Завершение всех задач: Ассистент отмечает последнюю задачу как completed.

8. Итоговый ответ: "Созданы файлы README.md и main.py..."

Особенности реализации TodoWrite

Я заметил, что при каждом обновлении статуса конкретной задачи LLM вынуждена передавать весь список todos. Гораздо эффективнее было бы передавать только id задачи и новый статус. При работе со списком из 12 шагов модель каждый раз передавала полный список, даже для обновления всего двух статусов.

Текущий подход, когда модель постоянно пересылает весь план, создает лазейку. LLM может "сгаллюцинировать" и незаметно подстроить первоначальный план под тот, который она фактически выполнила, а не тот, который был задуман изначально, просто передав нужные действия.

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

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

БОНУС слитый в сеть ClaudeCode 4-х месячной давности - https://github.com/ripgrim/anon-kode/tree/main

Пишите в комментариях, какие еще аспекты внутренней работы Claude Code вам интересны, попробуем разобрать!

И не забывайте заглядывать в мой Telegram канал.