Claude Code: что внутри — полный пошаговый гайд

Подробный разбор архитектуры Claude Code «под капотом» — как устроен агентный цикл, инструменты, права доступа, суб-агенты, память, MCP и продакшн-обвязка. Гайд построен по принципу «от простого к сложному»: сначала цикл в 15 строк, потом полноценный продакшн-агент. Материал собран из публично доступных источников и обсуждений сообщества и предназначен только для изучения и технического исследования.

[!NOTE] Этот репозиторий — учебный. Он объясняет паттерны современных кодинг-агентов на примере Claude Code. Внутренние детали реализации (кодовые имена, флаги, точная структура файлов) могут отличаться от версии к версии — важны не они, а принципы, которые переносятся на любой агент.

[!TIP] Популярные ресурсы по Машинному Обучению, ИИ и анализу данных.

🧠 Machine Learning — авторский Telegram-канал, который содержит всю базу для работы с ИИ-моделями. Дайджесты лучших проектов, разбор кода, инструкции по запуску LLM, подготовка к собесу и многое другое.

📚 Data Science — редкая литература, статьи, курсы и уникальные гайды для ML-специалистов любого уровня. Читайте, развивайтесь, практикуйте.

💼 Machine Interview — база с 1900 вопросами с собеседований по машинному обучению. Вы легко получите оффер, изучив популярные вопросы.

Telegram лучше — подписывайтесь.

Как читать этот гайд

Гайд рассчитан на три типа читателей — выберите свой маршрут, чтобы не читать лишнее.

Читать можно и по порядку — материал идёт «от простого к сложному»: сначала цикл в 15 строк (раздел 5), потом полноценная продакшн-обвязка (раздел 18). Если торопитесь — раздел 34 «Шпаргалка» держите открытым рядом как справочник.

Оглавление

Часть I. Основы

1. Кому и зачем это нужно
2. Что такое агент простыми словами
3. С чего начать: установка за 5 минут
4. Первая сессия: 10 команд, которые стоит знать

Часть II. Как это устроено внутри 5. Базовый агентный цикл (сердце всего) 6. Обзор архитектуры 7. Жизненный цикл одного запроса 8. Система инструментов (Tools) 9. Система прав доступа (Permissions) 10. Слэш-команды 11. Хуки и settings.json 12. MCP: подключаем внешние инструменты

Часть III. Продвинутое 13. Суб-агенты и мультиагентность 14. Управление контекстом (Compact) 15. Память и знания по требованию 16. Режим планирования (Plan Mode) 17. Сохранение и восстановление сессий 18. 12 механизмов продакшн-обвязки 19. Наблюдаемость и трейсинг агента 20. Стоимость и оптимизация токенов 21. Кэширование промптов (Prompt Caching) 22. Тестирование и оценка агентов (Evals) 23. Безопасность и защита от prompt injection 24. Отказоустойчивость: ретраи, таймауты, идемпотентность 25. Стриминг и параллелизм под нагрузкой

Часть IV. Практика 26. Практикум: собираем мини-агент сами 27. Рецепты: реальные сценарии использования 28. Практические примеры: разбор по шагам 29. Лучшие практики и антипаттерны 30. Решение проблем (Troubleshooting) 31. Глоссарий 32. Частые вопросы (FAQ) 33. Куда двигаться дальше 34. Шпаргалка (Quick Reference)

1. Кому и зачем это нужно

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

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

Мы идём от самого простого (цикл в 15 строк) к сложному (мультиагентные команды, изоляция в git worktree), объясняя каждый слой отдельно. Читать можно последовательно или прыгать по оглавлению.

2. Что такое агент простыми словами

Обычный чат с моделью — это «вопрос → ответ». Модель не может ничего сделать: она только генерирует текст. Агент отличается одним: у него есть инструменты (tools) и цикл.

Представьте помощника, которому вы дали не только возможность говорить, но и руки: он может читать файлы, запускать команды, искать в интернете. После каждого действия он смотрит на результат и решает, что делать дальше — пока задача не выполнена. Вот и всё. Агент = модель + инструменты + цикл, который крутится, пока есть работа.

ЧАТ:                          АГЕНТ:
вопрос -> ответ               вопрос -> [подумать -> действие -> результат]* -> ответ
(один шаг)                    (много шагов, пока задача не решена)

Всё остальное в этом гайде — про то, как сделать этот простой цикл надёжным, безопасным и масштабируемым.

Агент vs чат vs автодополнение — когда что

Три инструмента решают разные задачи. Путаница между ними — частая причина разочарования («агент слишком медленный», «автодополнение слишком глупое»).

Практическое правило: автодополнение — когда вы сами пишете код и знаете, что; чат — когда нужно понять или спросить; агент — когда задача требует нескольких шагов с обратной связью («почини тест», «отрефактори модуль», «разберись в баге»). Не гоняйте агента ради однострочника — это как вызывать эвакуатор, чтобы переставить машину на метр.

3. С чего начать: установка за 5 минут

Шаг 1. Проверьте окружение. Нужен Node.js версии 18 или выше:

node --version   # ожидается v18.x или выше

Если Node не установлен — скачайте с nodejs.org или поставьте через менеджер версий (nvm, fnm).

Шаг 2. Установите Claude Code глобально:

npm install -g @anthropic-ai/claude-code

Шаг 3. Перейдите в папку проекта и запустите:

cd your-project
claude

Шаг 4. Авторизуйтесь. При первом запуске откроется браузер для входа в аккаунт Anthropic. Токен сохранится локально, повторно логиниться не нужно.

Шаг 5. Задайте первый вопрос, например: «объясни структуру этого проекта». Готово — вы внутри агентного цикла.

[!TIP] Запустите claude именно в корне проекта — так агент сразу видит контекст (файлы, git, CLAUDE.md). Из пустой папки пользы будет меньше.

Быстрая проверка, что всё работает

4. Первая сессия: 10 команд, которые стоит знать

Внутри интерактивного режима (REPL) полезны слэш-команды. Вот минимальный набор новичка:

[!TIP] Начните любой новый проект с /init — Claude просканирует репозиторий и создаст CLAUDE.md с описанием стека, команд сборки и структуры. Это резко повышает качество последующих ответов.

5. Базовый агентный цикл (сердце всего)

В основе Claude Code лежит очень простая идея. Всё остальное — надстройка над ней.

ГЛАВНЫЙ ЦИКЛ
============

Пользователь --> messages[] --> Claude API --> ответ
                                        |
                              stop_reason == "tool_use"?
                                   /          \
                                 да            нет
                                  |             |
                          выполнить инструмент  вернуть текст
                          добавить tool_result
                          вернуться в цикл ------> messages[]

Разберём по шагам, что происходит:

1. Пользователь отправляет запрос — он попадает в массив messages[] (вся история диалога).
2. Массив уходит в Claude API вместе со списком доступных инструментов.
3. Модель отвечает. Ключевое поле ответа — stop_reason.
4. Если stop_reason == "tool_use" — модель захотела вызвать инструмент. Мы его выполняем, кладём результат обратно в messages[] как tool_result и возвращаемся к шагу 2.
5. Если нет — это финальный текстовый ответ, цикл завершён.

Вот и весь «магический» агент. Claude Code оборачивает этот цикл в продакшн-обвязку: права доступа, стриминг, параллелизм, сжатие контекста, суб-агенты, персистентность и MCP. Дальше по гайду мы разберём каждый слой этой обвязки.

[!IMPORTANT] Запомните главную мысль: цикл не меняется, сколько бы возможностей мы ни добавляли. Инструментов может быть 3 или 300 — структура остаётся той же. Именно это делает архитектуру расширяемой.

6. Обзор архитектуры

СЛОЙ ВХОДА
  cli --> main --> REPL (интерактивный режим)
              --> QueryEngine (headless / SDK)
       |
       v
ДВИЖОК ЗАПРОСОВ (QueryEngine)
  submitMessage(prompt) --> поток сообщений
       ├── собрать системный промпт (инструменты + CLAUDE.md)
       ├── обработать /команды
       ├── главный агентный цикл
       │     ├── параллельное выполнение инструментов
       │     ├── авто-сжатие контекста
       │     └── оркестрация инструментов
       └── стримить результат потребителю
       |
       ├──────────────┬──────────────┐
       v              v              v
  ИНСТРУМЕНТЫ     СЕРВИСЫ         СОСТОЯНИЕ
  40+ tools       API-клиент      права, история,
  Bash/Read/Edit  compact/mcp     агенты, режимы
  Glob/Grep       телеметрия
  WebFetch/Agent  плагины

Архитектуру удобно читать сверху вниз как «слоёный пирог»:

• Слой входа решает, в каком режиме мы работаем: интерактивный REPL (человек за терминалом) или headless/SDK (агент внутри скрипта или CI).
• Движок запросов (QueryEngine) — дирижёр. Он собирает системный промпт, обрабатывает команды, крутит главный цикл и стримит ответ.
• Три опорных слоя: инструменты (что агент умеет делать), сервисы (API, сжатие, MCP, телеметрия) и состояние (права, история файлов, активные агенты, режимы).

7. Жизненный цикл одного запроса

Что именно происходит между нажатием Enter и появлением ответа:

ВВОД ПОЛЬЗОВАТЕЛЯ (промпт / слэш-команда)
        |
        v
  разбор /команд, сборка UserMessage
        |
        v
  сборка системного промпта (инструменты -> секции, память CLAUDE.md)
        |
        v
  запись транскрипта на диск (JSONL)
        |
        v
  ┌── нормализация сообщений для API (сжатие при необходимости)
  │       |
  │       v
  │   Claude API (стриминг) — POST с инструментами и системным промптом
  │       |
  │       ├── текстовый блок --> отдать потребителю
  │       └── блок tool_use?
  │              |
  │              v
  │        проверка прав (хуки + правила + запрос у пользователя)
  │              ├── DENY --> tool_result(ошибка), продолжить цикл
  │              └── ALLOW --> выполнить инструмент --> добавить tool_result
  └────────── вернуться к вызову API
        |
        v  (stop_reason != "tool_use")
  финальное сообщение — текст, стоимость, id сессии

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

8. Система инструментов (Tools)

Каждый инструмент реализует единый интерфейс. Добавить инструмент = добавить один обработчик, при этом сам цикл не меняется.

ЖИЗНЕННЫЙ ЦИКЛ ИНСТРУМЕНТА
  validateInput()      — отсеять плохие аргументы заранее
  checkPermissions()   — проверка прав, специфичная для инструмента
  call()               — выполнить и вернуть результат

ВОЗМОЖНОСТИ
  isEnabled()          — проверка feature-флага
  isConcurrencySafe()  — можно ли запускать параллельно?
  isReadOnly()         — есть ли побочные эффекты?
  isDestructive()      — необратимые операции?

ОТРИСОВКА (React/Ink) — как показать ввод/вывод/прогресс в терминале
AI-СТОРОНА — prompt() и description() описывают инструмент для модели

Отдельно стоит подчеркнуть флаг isConcurrencySafe(). Инструменты только для чтения (например, поиск и чтение файлов) можно запускать параллельно — это резко ускоряет работу. А вот те, что меняют файлы или запускают команды, выполняются последовательно, чтобы не мешать друг другу.

Категории инструментов

[!TIP] Инструменты только для чтения (Glob, Grep, Read) безопасны и обычно выполняются без подтверждения. Осторожность нужна с Bash, Write и Edit — именно их стоит держать под контролем прав доступа (см. следующий раздел).

9. Система прав доступа (Permissions)

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

ЗАПРОС НА ВЫЗОВ ИНСТРУМЕНТА
        |
        v
  validateInput()  — отклонить некорректный ввод до любых проверок
        |
        v
  PreToolUse-хуки  — пользовательские команды из settings.json
                     могут: одобрить / отклонить / изменить ввод
        |
        v
  Правила прав     — alwaysAllow / alwaysDeny / alwaysAsk
        |
    нет совпадения?
        |
        v
  Интерактивный запрос — Allow Once / Allow Always / Deny
        |
        v
  checkPermissions() — логика инструмента (например, песочница путей)
        |
    ОДОБРЕНО --> call()

Режимы прав

Claude Code поддерживает несколько режимов, которые задают общее поведение:

• default — спрашивает разрешение на потенциально опасные действия. Безопасный выбор по умолчанию.
• plan — агент только планирует и читает, но ничего не меняет. Идеально для разведки в чужом коде.
• acceptEdits — автоматически принимает правки файлов, но всё ещё спрашивает про команды.
• bypassPermissions — без вопросов (опасно, только для изолированных окружений вроде контейнеров).

[!WARNING] Режим bypassPermissions даёт агенту полную свободу. Используйте его только в песочнице/контейнере, где нечего сломать. Никогда не запускайте его на рабочей машине с доступом к продакшену.

Правила в settings.json

Правила позволяют один раз описать, что разрешено без вопросов, а что запрещено всегда:

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Read(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(.env)"
    ]
  }
}

Так вы разрешаете тесты и чтение исходников, но навсегда запрещаете разрушительные команды и чтение секретов.

10. Слэш-команды

Слэш-команды (/command) — быстрый способ управлять сессией. Их около 80; вот категории и самые полезные:

Свои команды

Можно создавать собственные команды — это просто markdown-файлы в .claude/commands/. Например, файл .claude/commands/test.md:

Запусти все тесты, найди упавшие и предложи исправления.
Формат ответа: сначала список упавших тестов, потом по каждому — причина и фикс.

Теперь в сессии команда /test выполнит этот сценарий. Так вы кодифицируете повторяющиеся задачи команды.

11. Хуки и settings.json

Хуки — это ваши собственные shell-команды, которые Claude Code запускает в определённые моменты жизненного цикла. Они позволяют вставить свою логику, не трогая код агента.

Пример: автоматически прогонять форматтер после каждой правки файла. В settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATHS\"" }
        ]
      }
    ]
  }
}

Теперь любой файл, который агент изменил, автоматически проходит через Prettier — без единого напоминания.

Где лежат настройки

Настройки читаются с приоритетом (нижние переопределяют верхние):

~/.claude/settings.json           — глобальные, для всех проектов
<project>/.claude/settings.json   — настройки проекта (в git, для команды)
<project>/.claude/settings.local.json — локальные, только ваши (в .gitignore)

[!TIP] Общекомандные правила кладите в .claude/settings.json и коммитьте в репозиторий — так вся команда получает одинаковое поведение агента. Личные предпочтения — в settings.local.json.

12. MCP: подключаем внешние инструменты

MCP (Model Context Protocol) — открытый протокол, который позволяет подключать к агенту внешние источники данных и инструменты: базы данных, трекеры задач, API, файловые системы. Это способ расширять возможности агента, не меняя его самого.

MCP-АРХИТЕКТУРА
  MCPConnectionManager
    ├── Обнаружение серверов (из settings.json)
    │     ├── stdio  — запуск дочернего процесса
    │     ├── sse    — HTTP EventSource
    │     ├── http   — Streamable HTTP
    │     └── ws     — WebSocket
    │
    ├── Жизненный цикл клиента
    │     ├── connect -> initialize -> список инструментов
    │     ├── вызовы через обёртку MCPTool
    │     └── переподключение с backoff
    │
    └── Регистрация инструментов
          ├── именование: mcp__<сервер>__<инструмент>
          ├── схема подтягивается с сервера динамически
          └── права проходят через ту же систему Permissions

Пример подключения

Чтобы дать агенту доступ к файловой системе через официальный MCP-сервер, добавьте в конфиг:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

После перезапуска инструменты сервера появятся под именами вроде mcp__filesystem__read_file. Проверить статус подключений можно командой /mcp.

[!NOTE] Инструменты MCP проходят ту же проверку прав, что и встроенные. Внешний сервер не может обойти вашу систему разрешений — он просто добавляет новые инструменты в общий пул.

13. Суб-агенты и мультиагентность

Когда задача большая, её выгодно разбить и делегировать. Каждый суб-агент получает свежий контекст, поэтому главный диалог остаётся чистым, а подзадача решается изолированно.

ГЛАВНЫЙ АГЕНТ
     |
  ┌──┴────────────┬───────────────┐
  v               v               v
FORK-АГЕНТ    УДАЛЁННЫЙ       IN-PROCESS
дочерний      АГЕНТ           напарник
процесс       через мост      тот же процесс
свежий msgs[] изолирован      общее состояние

РЕЖИМЫ ЗАПУСКА:
  default   — в процессе, общий диалог
  fork      — дочерний процесс, свежий messages[], общий файловый кэш
  worktree  — изолированный git worktree + fork
  remote    — мост к удалённому Claude Code / контейнеру

СВЯЗЬ:
  SendMessageTool   — сообщения между агентами
  TaskCreate/Update — общая доска задач
  TeamCreate/Delete — управление жизненным циклом команды

Зачем это нужно? Представьте задачу «отрефактори модуль авторизации и обнови тесты». Главный агент может поручить одному суб-агенту исследование кода, другому — написание тестов, а сам собрать результаты. Каждый работает в своём контексте и не «загрязняет» общий диалог лишними деталями.

Свои суб-агенты

Можно описать специализированного агента в .claude/agents/. Например, reviewer.md:

---
name: reviewer
description: Строгий ревьюер кода. Ищет баги, проблемы безопасности и стиля.
tools: Read, Grep, Glob
---

Ты — опытный ревьюер. Проверяй код на баги, уязвимости и нарушения стиля.
Не предлагай правки без обоснования. Будь конкретным и краток.

Обратите внимание: этому агенту выданы только read-only инструменты — он может анализировать, но не менять код. Это безопасный паттерн для ревью.

14. Управление контекстом (Compact)

Контекстное окно не бесконечно. Когда токены заканчиваются — старые сообщения сжимаются, чтобы освободить место, но не потерять суть.

БЮДЖЕТ КОНТЕКСТНОГО ОКНА
┌─────────────────────────────────────────────┐
│ Системный промпт (инструменты, права, CLAUDE.md) │
├─────────────────────────────────────────────┤
│ История диалога                              │
│   [сжатое резюме старых сообщений]           │
│   --- граница сжатия ---                     │
│   [свежие сообщения — полная детализация]    │
├─────────────────────────────────────────────┤
│ Текущий ход (запрос + ответ)                 │
└─────────────────────────────────────────────┘

ТРИ СТРАТЕГИИ СЖАТИЯ:
  autoCompact      — при превышении порога токенов
                     суммаризирует старые сообщения отдельным вызовом API
  snipCompact      — удаляет «мёртвые» сообщения и устаревшие маркеры
  contextCollapse  — реструктурирует контекст для эффективности

ПОТОК СЖАТИЯ:
  messages[] --> взять сообщения после границы сжатия
        |
        v
  старые сообщения --> Claude API (суммаризация) --> сжатое резюме
        |
        v
  [резюме] + [граница сжатия] + [свежие сообщения]

Сжатие происходит автоматически, но вы можете запустить его вручную командой /compact — например, перед сменой темы, чтобы «подчистить» контекст и сэкономить токены.

[!TIP] Если ответы стали «плыть» и агент забывает начало сессии — это сигнал, что контекст переполнен. Сделайте /compact, а для совсем новой задачи — /clear.

15. Память и знания по требованию

Claude Code не грузит все знания в системный промпт (это дорого и раздувает контекст). Вместо этого он подгружает их лениво, когда нужно.

• CLAUDE.md — файлы памяти, читаются по мере необходимости для каждой директории. Кладите сюда правила проекта, стиль кода, команды сборки, важные заметки.
• SkillTool — навыки инжектятся через tool_result, а не в системный промпт, экономя контекст.
• Директория с навыками/заметками — хранилище знаний, доступное агенту по требованию.

Иерархия CLAUDE.md

Файлы памяти складываются по уровням, от общего к частному:

~/.claude/CLAUDE.md              — личные правила для всех проектов
<project>/CLAUDE.md              — правила проекта (в git, для команды)
<project>/<subdir>/CLAUDE.md     — правила для конкретной подпапки

Хороший CLAUDE.md

# Проект: My App

## Стек
- Backend: Node.js + Fastify
- Frontend: React + Vite
- БД: PostgreSQL

## Команды
- \`npm run dev\` — запуск в разработке
- \`npm test\` — тесты (обязательно после изменений)
- \`npm run lint\` — проверка стиля

## Правила
- Используй TypeScript строго, без \`any\`.
- Все новые эндпоинты покрывай тестами.
- Не трогай файлы в \`legacy/\` без явной просьбы.

[!TIP] Держите CLAUDE.md коротким и конкретным. Это не документация проекта, а «шпаргалка для агента»: команды, соглашения, запреты. Длинные файлы съедают контекст и снижают качество.

16. Режим планирования (Plan Mode)

Режим планирования — это когда агент сначала думает и составляет план, и только потом действует. В этом режиме он читает код и рассуждает, но ничего не меняет, пока вы не одобрите план.

ОБЫЧНЫЙ РЕЖИМ:   запрос -> сразу правки -> результат
PLAN MODE:       запрос -> исследование -> ПЛАН -> [ваше одобрение] -> правки

Как включить: команда /plan или запуск с флагом. Плюсы:

• Безопасность — агент ничего не сломает, пока вы не согласитесь.
• Прозрачность — вы видите намерения до действий.
• Качество — «агент без плана дрейфует»; явный план заметно повышает долю успешно решённых задач.

[!TIP] Для незнакомого или критичного кода всегда начинайте с plan mode. Прочитайте план, поправьте, если агент понял задачу не так, и только потом разрешайте выполнение.

17. Сохранение и восстановление сессий

Каждая сессия пишется на диск в виде журнала — это позволяет восстановить работу после перезапуска или сбоя.

ХРАНИЛИЩЕ СЕССИЙ
  ~/.claude/projects/<hash>/sessions/
    └── <session-id>.jsonl   — журнал только на дозапись
         ├── {"type":"user",...}
         ├── {"type":"assistant",...}
         └── {"type":"system","subtype":"compact_boundary",...}

ВОССТАНОВЛЕНИЕ:
  --continue        — последняя сессия в текущей папке
  --resume <id>     — конкретная сессия
  --fork-session    — новый id, копия истории

Стратегия записи продумана под надёжность: пользовательские сообщения пишутся синхронно (чтобы точно не потерять при сбое), а ответы ассистента — «выстрелил и забыл», с сохранением порядка. Формат JSONL (по объекту на строку) удобно читать и парсить.

Практика: прервали работу — вернитесь командой claude --continue. Нужна конкретная старая сессия — claude --resume <id> или интерактивно через /resume.

18. 12 механизмов продакшн-обвязки

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

Главная идея этой таблицы: сложность агента — не в цикле, а в обвязке вокруг него. Цикл остаётся тем же с самого первого раздела. Всё, что делает агент «продакшн-грейд» — это 11 слоёв поверх одной простой петли.

19. Наблюдаемость и трейсинг агента

Агент без наблюдаемости — чёрный ящик: непонятно, почему он принял решение, где потратил токены и на каком шаге сломался. Продакшн-агент логирует каждый виток цикла структурированно.

ЧТО ТРЕЙСИТЬ НА КАЖДОМ ВИТКЕ ЦИКЛА
─────────────────────────────────
запрос к API      → модель, размер контекста (токены in), latency
ответ модели      → stop_reason, токены out, стоимость витка
вызов инструмента → имя, аргументы (без секретов!), длительность, успех/ошибка
проверка прав     → решение (allow/deny), какое правило сработало
сжатие контекста  → до/после (токены), какая стратегия

СПАН-ИЕРАРХИЯ (OpenTelemetry-совместимо)
session
 └── turn (один ход пользователя)
      └── api_call (виток цикла)
           ├── tool_use: bash
           └── tool_use: read_file

Три уровня наблюдаемости, которые стоит завести сразу: логи (структурный JSONL по событиям), метрики (токены/стоимость/latency/доля ошибок инструментов) и трейсы (сквозной путь одного запроса через все витки и инструменты).

[!TIP] Логируйте session_id и turn_id в каждой записи. Тогда любой инцидент («агент удалил не тот файл») восстанавливается по журналу за секунды: видно точный инструмент, аргументы и правило прав, которое его пропустило.

20. Стоимость и оптимизация токенов

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

КУДА УХОДЯТ ТОКЕНЫ (типичная сессия)
────────────────────────────────────
системный промпт + описания инструментов  ~ фикс. оверхед КАЖДОГО витка
история диалога                            растёт линейно с шагами
вывод инструментов (bash, файлы)           часто ГЛАВНЫЙ пожиратель
ответы модели                              обычно малы

ПРАВИЛО: input-токены >> output-токены. Оптимизируйте ВВОД.

[!TIP] Команда /cost показывает разбивку по сессии. Если стоимость растёт быстрее, чем сложность задачи — почти всегда виноват раздутый вывод инструмента, попавший в историю. Фильтруйте вывод до того, как он вернётся в messages[].

21. Кэширование промптов (Prompt Caching)

Системный промпт Claude Code огромен: описания 40+ инструментов, права, CLAUDE.md. Отправлять его заново на каждом витке — расточительно. Кэширование промптов позволяет один раз «прогреть» стабильный префикс и переиспользовать его.

БЕЗ КЭША:  [СИСТЕМА+ИНСТРУМЕНТЫ][история][ход]  ← платим за всё каждый виток
С КЭШЕМ:   [====кэш-хит====][история][ход]      ← платим лишь за новое

ГРАНИЦЫ КЭША (cache breakpoints), от стабильного к изменчивому:
1. системный промпт + определения инструментов   (меняется редко)  ← кэш
2. CLAUDE.md / контекст проекта                    (стабильно)      ← кэш
3. ранняя история диалога                          (растёт)         ← кэш
4. свежие сообщения                                (каждый ход)     — без кэша

Ключевой принцип: кэш работает по префиксу. Всё стабильное держите в начале, всё изменчивое — в конце. Одно изменение в начале инвалидирует весь кэш ниже.

[!IMPORTANT] Порядок важнее всего. Если вставлять «текущую дату» или случайный id в самое начало системного промпта — кэш не сработает никогда. Динамику держите ближе к концу контекста.

22. Тестирование и оценка агентов (Evals)

Обычные юнит-тесты проверяют детерминированный код. Агент недетерминирован: та же задача может решиться разными путями. Поэтому его оценивают не по «точному выводу», а по достижению цели на наборе сценариев (eval-набор).

ПИРАМИДА ТЕСТИРОВАНИЯ АГЕНТА
───────────────────────────
        ┌───────────────┐
        │  End-to-End    │  «почини баг X в репо» → тест зелёный?
        │   сценарии     │  (мало, дорого, самые ценные)
        ├───────────────┤
        │  Инструменты   │  каждый tool: валидный ввод → ожидаемый эффект
        │  (детермин.)   │  (много, дёшево, быстро)
        ├───────────────┤
        │ Проверки прав  │  deny-правило реально блокирует rm -rf?
        └───────────────┘

Как оценивать вероятностный результат: задайте проверяемый критерий успеха (тесты проходят, файл содержит нужное, команда вернула 0), гоняйте каждый сценарий несколько раз и смотрите долю успеха (pass@k), а сложные случаи отдавайте на LLM-as-judge с чёткой рубрикой.

[!WARNING] Не оценивайте агента «на глаз» после ручной проверки пары задач. Меняете системный промпт или модель — прогоняйте весь eval-набор. Улучшение на одном примере часто ломает пять других.

23. Безопасность и защита от prompt injection

Как только агент читает внешние данные (веб-страницы, файлы, вывод команд, тикеты), появляется главная угроза — prompt injection: во внешнем тексте спрятаны инструкции, которые агент может принять за команды пользователя.

МОДЕЛЬ УГРОЗ КОДИНГ-АГЕНТА
──────────────────────────
1. Prompt injection   вредный текст в файле/вебе → «выполни rm -rf», «слей .env»
2. Эксфильтрация      секреты в контекст → отправка наружу через bash/веб
3. Опасные команды    деструктив (rm, drop table, git push --force)
4. Выход за периметр   доступ к путям вне проекта, к продакшену

ГРАНИЦА ДОВЕРИЯ
[ инструкции пользователя ] = доверенные
[ вывод инструментов/файлов/веба ] = ДАННЫЕ, не инструкции

Практическая защита выстраивается слоями: права и sandbox (deny на rm -rf, чтение .env, запись вне проекта), изоляция секретов от контекста агента, человек в цикле на необратимых действиях и трактовка любого внешнего текста как данных, а не команд.

[!WARNING] Никогда не давайте агенту одновременно и доступ к секретам, и возможность отправлять данные наружу без подтверждения. Это классический канал эксфильтрации: инъекция в прочитанном файле → чтение .env → curl на чужой сервер.

24. Отказоустойчивость: ретраи, таймауты, идемпотентность

Реальный мир ненадёжен: API отвечает 429/500, сеть отваливается, команда зависает. Продакшн-агент не должен падать от первой же ошибки — он восстанавливается.

ЭКСПОНЕНЦИАЛЬНЫЙ BACKOFF С JITTER
─────────────────────────────────
попытка 1 → ошибка 429 → ждём ~1s
попытка 2 → ошибка 429 → ждём ~2s   (+ случайный jitter)
попытка 3 → ошибка 500 → ждём ~4s
попытка 4 → успех ✓
                    (после N попыток — аккуратно сдаёмся)

ЧТО РЕТРАИТЬ, А ЧТО НЕТ
429 / 500 / 503 / таймаут  → ретрай (временное)
400 / 401 / 403            → НЕ ретраить (ошибка запроса/прав)

Базовые приёмы устойчивости: ретрай с backoff только на транзиентные ошибки, таймауты на каждый вызов инструмента (зависший bash не должен вешать сессию), идемпотентность повторяемых действий и graceful degradation — при отказе инструмента вернуть tool_result с ошибкой, чтобы агент попробовал другой путь, а не рухнул.

[!TIP] Отказ инструмента — не конец цикла, а сигнал модели. Возвращайте понятную ошибку в tool_result («команда превысила таймаут 30с») — агент часто сам сообразит обходной путь.

25. Стриминг и параллелизм под нагрузкой

Отзывчивость агента держится на двух вещах: стриминге (пользователь видит ответ по мере генерации, а не через 30 секунд тишины) и параллельном выполнении безопасных инструментов.

ПАРАЛЛЕЛЬНОЕ ВЫПОЛНЕНИЕ ИНСТРУМЕНТОВ
────────────────────────────────────
модель вернула 3 вызова за один виток:
  read_file(a)  ┐
  read_file(b)  ├─ isConcurrencySafe? → да → запускаем ВМЕСТЕ
  grep(x)       ┘
                     vs
  write_file(c) → меняет состояние → строго ПОСЛЕДОВАТЕЛЬНО

ПОТОК СТРИМИНГА
API (SSE) → дельты текста → сразу в терминал
          → блок tool_use собирается целиком → затем выполняется

Правило безопасности параллелизма — тот самый флаг isConcurrencySafe() из раздела про инструменты: read-only операции (чтение, поиск) летят пачкой и резко ускоряют разведку по кодовой базе, а всё, что меняет файлы или состояние, сериализуется, чтобы не создавать гонок.

[!TIP] Самый дешёвый прирост скорости — распараллелить чтение и поиск. Когда агент исследует незнакомый проект, десяток Read/Grep параллельно превращают минуты ожидания в секунды.

26. Практикум: собираем мини-агент сами

Чтобы прочувствовать цикл, соберём его в ~20 строках на псевдо-Python. Это ядро, которое масштабируется до всего Claude Code.

messages = [{"role": "user", "content": prompt}]

while True:
    response = claude_api(messages, tools=TOOLS)
    messages.append(response.message)

    if response.stop_reason != "tool_use":
        print(response.text)   # финальный ответ
        break

    for call in response.tool_calls:
        if not check_permission(call):             # ворота прав
            result = {"error": "denied"}
        else:
            result = TOOLS[call.name](https://github.com/justxor/Claudecourse/blob/HEAD/call.input)  # выполнить инструмент
        messages.append({"role": "tool", "content": result})
    # цикл повторяется — модель видит результаты и решает, что дальше

Добавляем инструменты (2 штуки достаточно для старта)

import subprocess

def tool_read_file(args):
    with open(args["path"]) as f:
        return {"content": f.read()}

def tool_bash(args):
    out = subprocess.run(args["cmd"], shell=True, capture_output=True, text=True)
    return {"stdout": out.stdout, "stderr": out.stderr, "code": out.returncode}

TOOLS = {"read_file": tool_read_file, "bash": tool_bash}

Уже с этими двумя инструментами (чтение файла + запуск команды) агент может исследовать проект, запускать тесты и чинить ошибки. Именно так устроен любой кодинг-агент в своей основе.

Что добавить дальше, слой за слоем

1. Проверку прав перед вызовом (мы уже заложили функцию проверки).
2. Планирование — todo-лист, который агент ведёт сам.
3. Сжатие истории при переполнении контекста.
4. Запись в JSONL для восстановления после сбоя.
5. Суб-агентов для крупных подзадач с чистым контекстом.

Пройдя эти пять шагов, вы повторите путь от учебного скрипта до архитектуры уровня Claude Code.

От псевдокода к рабочему агенту (реальный API)

Теперь соберём тот же цикл, но уже с настоящим SDK Anthropic и корректными схемами инструментов. Это полностью рабочий скелет — добавьте свой API-ключ и запускайте.

import subprocess, json
from anthropic import Anthropic

client = Anthropic()  # ключ берётся из ANTHROPIC_API_KEY

# 1) Описываем инструменты для модели (JSON Schema)
TOOL_SCHEMAS = [
    {
        "name": "read_file",
        "description": "Прочитать текстовый файл по пути и вернуть содержимое.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
    {
        "name": "bash",
        "description": "Выполнить shell-команду и вернуть stdout/stderr/код возврата.",
        "input_schema": {
            "type": "object",
            "properties": {"cmd": {"type": "string"}},
            "required": ["cmd"],
        },
    },
]

# 2) Реализация инструментов
def read_file(path):
    with open(path, encoding="utf-8") as f:
        return f.read()[:10_000]  # обрезаем, чтобы не раздуть контекст

def bash(cmd):
    r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=30)
    tail = lambda s: s[-2000:]   # отдаём только хвост длинного вывода
    return json.dumps({"stdout": tail(r.stdout), "stderr": tail(r.stderr), "code": r.returncode})

IMPL = {"read_file": lambda a: read_file(a["path"]),
        "bash":      lambda a: bash(a["cmd"])}

# 3) Ворота прав: опасное — блокируем, остальное — спрашиваем
DENY = ("rm -rf", "git push --force", ":(){", "mkfs", "dd if=")
def check_permission(name, args):
    if name == "bash":
        cmd = args.get("cmd", "")
        if any(bad in cmd for bad in DENY):
            return False
        return input(f"Выполнить `{cmd}`? [y/N] ").strip().lower() == "y"
    return True  # чтение безопасно

# 4) Главный агентный цикл
def run(prompt):
    messages = [{"role": "user", "content": prompt}]
    while True:
        resp = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=2048,
            tools=TOOL_SCHEMAS,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})

        if resp.stop_reason != "tool_use":
            print(next(b.text for b in resp.content if b.type == "text"))
            return

        results = []
        for block in resp.content:
            if block.type != "tool_use":
                continue
            if not check_permission(block.name, block.input):
                out, err = "Отказано пользователем", True
            else:
                try:
                    out, err = IMPL[block.name](https://github.com/justxor/Claudecourse/blob/HEAD/block.input), False
                except Exception as e:
                    out, err = f"Ошибка инструмента: {e}", True
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(out),
                "is_error": err,
            })
        messages.append({"role": "user", "content": results})

if __name__ == "__main__":
    run("Найди все файлы .py в src/, посчитай строки и покажи самый большой")

[!IMPORTANT] Обратите внимание на четыре продакшн-детали, которых не было в псевдокоде: таймаут на bash, обрезку вывода (tail) для экономии токенов, флаг is_error в tool_result (агент понимает, что инструмент упал, и пробует иначе) и блок-лист опасных команд, который срабатывает раньше запроса к пользователю.

Как выглядит один прогон (трассировка)

Запрос: «Найди все файлы .py в src/, посчитай строки и покажи самый большой». Вот что происходит виток за витком:

ВИТОК 1
  -> API: messages=[user], tools=[read_file, bash]
  <- stop_reason=tool_use  ->  bash("find src -name '*.py'")
  [права] команда безопасна, пользователь: y
  -> tool_result: "src/app.py\nsrc/db.py\nsrc/utils.py"

ВИТОК 2
  <- stop_reason=tool_use  ->  bash("wc -l src/app.py src/db.py src/utils.py")
  [права] y
  -> tool_result: "120 src/app.py\n64 src/db.py\n38 src/utils.py"

ВИТОК 3
  <- stop_reason=end_turn (инструменты больше не нужны)
  <- текст: "Найдено 3 файла. Самый большой — src/app.py (120 строк)."

Три витка, два вызова инструментов, один текстовый ответ. Модель сама решила: сначала найти файлы, потом посчитать строки, потом сделать вывод. Мы не программировали эту последовательность — она следствие цикла.

27. Рецепты: реальные сценарии использования

Рецепт 1. Разобраться в незнакомом проекте

/init                          # сгенерировать CLAUDE.md
"Опиши архитектуру проекта и точки входа"
"Где обрабатываются HTTP-запросы?"

Рецепт 2. Починить упавший тест

"Запусти тесты, найди упавший, объясни причину и предложи фикс"
# просмотрите план, одобрите правку

Рецепт 3. Безопасный рефакторинг

/plan                          # включить режим планирования
"Отрефактори модуль auth: раздели на слои, сохрани поведение"
# читаете план -> одобряете -> агент правит -> прогоняет тесты

Рецепт 4. Ревью перед коммитом

/review
"Проверь мои незакоммиченные изменения на баги и стиль"

Рецепт 5. Автоматизация в CI (headless)

claude -p "Обнови CHANGELOG по коммитам с последнего тега" --output-format json

Рецепт 6. Разобраться в незнакомом баге по стектрейсу

"Вот стектрейс из прода (вставляю ниже). Найди причину в коде,
 объясни цепочку вызовов и предложи минимальный фикс. Не меняй ничего,
 пока я не подтвержу."
# агент: Grep по имени исключения -> Read виновных файлов -> гипотеза -> фикс

Ключевое здесь — фраза «не меняй ничего, пока не подтвержу». Она удерживает агента в режиме анализа, и вы получаете разбор до правок.

Рецепт 7. Массовое переименование по кодовой базе

/plan
"Переименуй функцию `getUser` в `fetchUser` во всём проекте:
 обнови объявление, все вызовы и тесты. Не трогай строки в комментариях
 и логах, если это не идентификатор."
# план -> одобрение -> Grep находит все вхождения -> Edit по каждому -> прогон тестов

[!TIP] Для рискованных массовых правок всегда связка «/plan + частый коммит». Сделайте git commit до запуска — если результат не понравится, git reset --hard откатит всё одной командой.

Рецепт 8. Написать тесты на существующий модуль

"Покрой тестами модуль `src/pricing.py`. Сначала прочитай его,
 перечисли граничные случаи (нули, отрицательные, пустые списки),
 потом напиши тесты на pytest и запусти их."

Агент сначала проговаривает граничные случаи (вы можете поправить список), и только потом пишет код — так тесты получаются осмысленными, а не формальными.

Рецепт 9. Дежурный по логам (headless в cron)

# Каждое утро в 9:00 — сводка ошибок за сутки
claude -p "Прочитай logs/app.log, сгруппируй ошибки за последние 24ч \
  по типу, выдели топ-3 по частоте и оцени серьёзность. Формат: markdown." \
  --output-format json | ./post-to-slack.sh

Рецепт 10. Миграция зависимости с проверкой

/plan
"Обнови библиотеку X с версии 1.x до 2.x. Прочитай CHANGELOG об ломающих
 изменениях, найди затронутые места в коде, обнови их и прогони тесты.
 Если тесты падают — чини, пока не станут зелёными."
# агент работает циклом: правка -> тест -> анализ падения -> правка ...

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

28. Практические примеры: разбор по шагам

Пять сквозных примеров, где мы не просто даём команду, а собираем настоящий артефакт: свою слэш-команду, хук, суб-агента, MCP-интеграцию и полную сессию отладки. Каждый пример можно повторить у себя.

Пример 1. Своя слэш-команда для code review

Задача: чтобы вместо длинного промпта достаточно было набрать /review-pr. Создаём файл .claude/commands/review-pr.md:

Проверь изменения в текущей ветке относительно main.

Шаги:
1. Выполни `git diff main...HEAD` и прочитай изменения.
2. Для каждого файла оцени: баги, утечки ресурсов, edge-cases, стиль.
3. Проверь, покрыты ли новые ветки кода тестами.

Формат ответа:
- **Блокеры** (чинить обязательно) — список с файлом и строкой.
- **Замечания** (желательно) — список.
- **Хорошо** — что сделано правильно.


_…[view the full README on GitHub](https://github.com/justxor/Claudecourse)._