Руководство по миграции на Claude Opus 4.7 — breaking changes и как их обойти

1. Для кого это руководство

Как мы описали в обзоре релиза Claude Opus 4.7, 4.7 — это прямой наследник 4.6. Но на уровне API сразу несколько breaking changes, и если просто сменить имя модели, код местами будет валиться с 400 Bad Request.

Статья адресована:

• разработчикам, которые вызывают claude-opus-4-6 через Anthropic API / SDK
• командам, использующим Claude через Bedrock / Vertex AI
• тем, кто «застрял» на Opus 4.5 или 4.1 и хочет сразу прыгнуть на 4.7
• тем, кто в проде использует extended thinking (thinking: enabled) или temperature

Мы опираемся на официальное руководство Anthropic, но фокусируемся на вещах, где чаще всего спотыкаются разработчики. Официальное руководство — в migration guide на platform.claude.com.

2. В трёх строках — быстрое резюме

TL;DR для тех, у кого нет времени.

1. Смените ID модели с claude-opus-4-6 на claude-opus-4-7 (и обновите версию SDK)
2. Три крупных breaking changes: extended thinking enabled удалён (переход на adaptive + effort), удалены temperature/top_p/top_k, новый токенизатор (тот же текст — до x1.35 токенов)
3. Что получаете взамен: выше качество на коде, контекст 1M по базовой цене, новый уровень усилий xhigh

Дальше — детали.

3. Смена имени модели

Первое действие простое — поменять идентификатор модели.

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

Если храните имя модели в переменной окружения или конфиге, сохраняйте эту привычку — в следующий переход будет одно место для правки.

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

Но одной сменой имени модели чаще всего не обойтись — в этом и состоит сложность перехода. Разберём breaking changes по одному.

4. Breaking #1: extended thinking удалён, переход на adaptive

В Opus 4.6 extended thinking включался как thinking: {type: "enabled", budget_tokens: N}. В 4.7 этот формат даёт ошибку 400.

Вместо него используется «адаптивное мышление (adaptive thinking)», где модель сама подбирает объём рассуждения. Более того, в 4.7 мышление по умолчанию выключено: если не передавать поле thinking, модель работает без него. Для глубоких рассуждений включайте вручную.

Before (4.6) / After (4.7)

# Before: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Before: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// After: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

На что обратить внимание

• budget_tokens руками задавать больше не нужно
• Вместо этого — output_config.effort: «насколько серьёзно подумать»
• Если не передавать thinking, модель отвечает без мышления (поведение отличается от 4.6)

5. Breaking #2: параметры сэмплирования удалены

Любые значения temperature, top_p, top_k, отличные от дефолтных, дают ошибку 400. Это последовательное проведение линии Anthropic: «поведение задаётся промптом».

# Before
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# After
client.messages.create(
    model="claude-opus-4-7",
    # temperature / top_p / top_k полностью удалены
    messages=[...],
)

Если вы раньше выставляли temperature=0.2 ради «максимально стабильного вывода», теперь в промпте прямо пишите «отвечай одинаково на один и тот же вопрос» или используйте structured outputs с JSON-схемой.

Если temperature=1.2 задавалось для «креативности», используйте инструкции по тону в самом промпте — «используй метафоры и неожиданные формулировки».

6. Breaking #3: содержимое мышления скрыто по умолчанию

В 4.6 при включённом мышлении «summarized» шёл в стриме по умолчанию — многие приложения показывали это в UI как «думает...».

В 4.7 формат тихо изменился: блоки мышления в ответе есть, но поле thinking приходит пустым. Чтобы получить содержимое — нужен явный opt-in.

Симптомы

Индикатор «думаю...» крутится вечно, между нажатием и началом ответа — неестественно большая пауза. Пользователи пишут: «всё зависло?» — это оно.

Решение

# Если хотите показывать summary мышления, как в 4.6
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # явно указать
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

Если мышление нужно только в бэкенде, а в UI оно не отображается, display можно не задавать — всё будет работать.

7. Breaking #4: новый токенизатор (около x1.35)

Opus 4.7 использует новый токенизатор. Он участвует в росте качества, но тот же текст теперь занимает в 1,0–1,35 раза больше токенов, чем в 4.6.

К чему это приводит:

• процессы, у которых max_tokens был выставлен впритык, обрываются на середине
• сбивается клиентская оценка длины через аналоги tiktoken
• результаты /v1/messages/count_tokens отличаются между 4.7 и 4.6
• тот же промпт стоит чуть дороже и работает чуть дольше

Что делать

# Before: под 4.6 выделили 16k токенов на вывод
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# After: берём запас около 1.35x
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1.35 ≈ 21600 → округлили вверх
    messages=[...],
)

Отдельно плюс: в 4.7 контекст 1M теперь доступен по базовой цене API (без премии за длинный контекст). Токенов становится больше, зато стратегия «закинуть в контекст всё подряд» стала практичнее.

8. Breaking #5: prefill удалён

Breaking, унаследованный ещё из 4.6. Assistant prefill — когда в конец messages клали сообщение {role: "assistant", content: "```json"}, чтобы «заставить ответ начаться с JSON», — возвращает ошибку 400.

# Before: заставляем выдавать JSON префиллом
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "Верни данные пользователя в JSON"},
        {"role": "assistant", "content": "```json\n{"},  # префилл
    ],
)

# After: используем structured outputs
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "Верни данные пользователя в JSON"},
    ],
)

Чем заменить prefill:

1. Structured outputs (output_config.format) — фиксируем формат через JSON-схему
2. System-промпт — прямо написать «возвращай только JSON, без markdown и вводных фраз»
3. Tool use — принимать результат как вызов функции с аргументами-JSON

9. Как выбирать уровень усилий (новый xhigh)

В output_config.effort доступно пять значений. В 4.7 добавлен новый — xhigh.

Если в 4.6 вы руками задавали budget_tokens, теперь достаточно выбрать effort. Эмпирика:

• кодинг-агенты (формат Claude Code) — начинайте с xhigh
• Q&A-чаты и RAG-ответы — high обычно оптимален
• разметка, извлечение JSON, классификация — medium или low
• max — только «один вопрос, не жалко денег, надо додумать до конца»

10. Что делать с изменениями поведения

API может быть совместим, но реакция на промпт в 4.7 отличается от 4.6. Если не учесть, пользователи будут жаловаться: «стало как-то сухо».

10.1 Длина ответа адаптируется под задачу

4.7 сам подбирает длину под сложность. «Всегда пиши в три абзаца» — больше не работает само. Снимите прежние ограничения на длину и посмотрите, как ведёт себя модель без них.

10.2 Инструкции читаются буквально

Особенно на низком effort. «Кратко» — значит действительно кратко; «перечисли три» — четвёртый пункт не появится. Удобно, но «дочитывать между строк», как делал 4.6, модель уже не будет.

10.3 Тон стал прямее

Validation phrases («Отличный вопрос!»), декоративные эмодзи, приветствия в начале — стало меньше. Если нужен дружелюбный тон, прямо задавайте его в system-промпте.

10.4 Progress-update встроен в трекинг агентов

Если вы руками «доставляли» агенту промежуточные «сейчас делаю X», знайте: 4.7 делает это сам — дубликат в scaffolding можно убрать.

10.5 Меньше саб-агентов и tool calls

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

10.6 Realtime-safeguards по кибербезопасности

В законных задачах offensive security (red team, PoC уязвимостей) модель может отказаться в зависимости от контекста. Если security — ваш прод-кейс, подайте заявку в Cyber Verification Program.

10.7 Поддержка HD-картинок

Картинки до 2576px теперь обрабатываются без потери разрешения. Но одна такая картинка — около ×3 токенов. В нагрузках с большим количеством картинок либо (a) перераспределяйте max_tokens, либо (b) сжимайте изображения перед отправкой.

11. Рекомендованные изменения (не обязательные)

Здесь — что «можно не делать, но лучше сделать».

1. Пересмотреть max_tokens: новый токенизатор раздувает и выход, начните с ×1.2–1.35 от прежних значений
2. Аудит клиентской оценки токенов: если у вас свой биллинг и подсчёт длины — переходите на count_tokens API или уточняйте коэффициенты
3. Подключить task_budgets (beta): для агентов — с header'ом task-budgets-2026-03-13, минимум 20k. Это «advisory-лимит», а не жёсткий
4. Поставить max_tokens от 64k: при xhigh/max нужно не меньше 64k на мышление + вывод
5. Даунсемплить картинки: если HD не нужен — уменьшайте до отправки, экономьте токены

11.1 Минимальный пример task_budgets (Python SDK)

task_budgets — бета, поэтому вызывается через client.beta.messages.create, и нужно явно передать betas. С GA-функциями вызов отличается.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

Ключевое в спецификации:

• Минимум — 20 000 токенов, меньше не принимается
• max_tokens — жёсткий лимит на запрос (модели не сообщается), task_budget — advisory-лимит на весь цикл агента (модель ведёт обратный отсчёт)
• Если нужно жёстко ограничить расходы — max_tokens; баланс качества и эффективности — task_budget
• В open-ended работах, где важнее качество, чем скорость, task_budget лучше не задавать (иначе появляется тенденция слишком рано закругляться)

12. Миграция с Opus 4.5 / 4.1 и раньше

Если прыгаете на 4.7 сразу с 4.5 или 4.1, в дополнение к перечисленному сделайте следующее.

• Удалить параметры сэмплирования: пользователи Claude 3.x привыкли к temperature — нужно полностью убрать
• Почистить beta-заголовки: effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14 и подобные уже вошли в основную часть API — удалить
• Перейти на другой endpoint: вызовы через client.beta.messages.create замените на client.messages.create
• Перенести output_format в output_config.format: имя ключа поменялось
• Парсинг аргументов инструментов: с 4.6 поведение JSON-эскейпа местами изменилось — используйте полноценные парсеры JSON.parse / json.loads, а не ручную обработку строк

По самим возможностям 4.7 смотрите материнскую статью — Релиз Claude Opus 4.7: новые функции, бенчмарки, цены.

13. Чек-лист миграции (все пункты)

Готовая чек-версия для распечатки и передачи команде.

13.1 Обязательно (без этого — 400 или сломанное поведение)

• ☐ Сменить ID модели: claude-opus-4-6 → claude-opus-4-7
• ☐ Убрать temperature / top_p / top_k
• ☐ Заменить thinking: {type: "enabled", budget_tokens: N} на {type: "adaptive"} + output_config.effort
• ☐ Удалить assistant prefill и перейти на structured outputs / system-промпт
• ☐ Если мысли показываются в UI — явно задать thinking.display: "summarized"

13.2 Настройка (оптимизация стоимости и качества)

• ☐ Замерить стоимость и задержки на новом токенизаторе
• ☐ Поднять max_tokens примерно в ×1.35
• ☐ Перетестировать клиентскую логику оценки токенов
• ☐ При отправке картинок учесть рост токенов на HD
• ☐ При использовании xhigh/max поставить max_tokens ≥ 64k
• ☐ Для агентов рассмотреть внедрение task_budgets (beta)

13.3 Промпты и операционка

• ☐ Проверить на реальных промптах адаптацию длины, буквальное чтение и тон
• ☐ Удалить старые ограничения по длине и замерить baseline заново
• ☐ Если security-задачи отказываются — подать заявку в Cyber Verification Program
• ☐ Упростить agent-scaffolding (ручные «сейчас делаю X» и подобные)
• ☐ При миграции с 4.5 и ниже — убрать beta-заголовки и перейти на client.messages.create

14. Инструменты автомиграции

Если используете Claude Code, для механических правок есть скилл Claude API от Anthropic. В Claude Code достаточно вызвать его так:

/claude-api migrate

Мигрируй весь проект с Claude Opus 4.6 на 4.7:
- смени ID модели
- удали temperature / top_p / top_k
- замени thinking: enabled на adaptive + effort: high
- если остался prefill — замени на structured outputs

Скилл сам пройдёт по репозиторию, найдёт файлы, импортирующие SDK anthropic, и предложит правки. Но тонкая настройка промптов и повторные замеры бенчмарков автоматом не делаются — финишную шлифовку ведите по чек-листу.

FAQ

Статья основана на официальном руководстве по миграции Claude Opus 4.7 (данные на апрель 2026). Спецификации API могут меняться — перед выкаткой в прод сверяйтесь с официальной документацией.