# Adaptive Thinking 設定ガイド

**Adaptive Thinking（自適応思考）** は Claude 4.6/4.7/4.8 シリーズの新世代推論モードです：モデル自身がいつ推論に投入するか、どれだけの tokens を推論に使うかを決定し、開発者が固定予算を事前に設定する必要はありません。`effort` パラメータと組み合わせて思考の深さを粗粒度で制御できます。本ガイドは、これに関する API の使い方、モデルサポートマトリクス、効果とコストのトレードオフをまとめたものです。

> **5 系について**：日常のデフォルト推奨は引き続き `claude-sonnet-5` / `claude-opus-5` です（4.x は販売中）。下記のパラメータ行列は Claude 4.6 / 4.7 / 4.8 で**実測**したものです。5 系の `thinking` / `effort` が表と完全に一致するかは本ラウンドでは未検証です。4.x 専用の結論（例：Opus 4.8 での `budget_tokens` 禁止、`xhigh` / `max`）を 5 系にそのまま当てはめないでください。5 系の選定は [モデル選択](/docs/usage/model-selection) を参照。

## 旧 Extended Thinking との主な違い

| 観点 | 旧 Extended Thinking（4.5 以前）| Adaptive Thinking（4.6 / 4.7 / 4.8）|
|------|--------------------------------|------------------------------|
| トリガーパラメータ | `thinking={"type": "enabled", "budget_tokens": N}` | `thinking={"type": "adaptive"}` |
| 予算制御 | 固定 token 上限（`budget_tokens` は `max_tokens` 未満必須）| モデル自動調整、`effort` で粗調整 |
| ツール呼び出しをまたぐ | デフォルトでインターリーブしない（`interleaved-thinking-2025-05-14` beta ヘッダ必要）| 自動インターリーブ（beta ヘッダ不要）|
| Opus 4.8 互換性 | ❌ **400 error**（`budget_tokens` は削除済み）| ✅ 唯一サポートされるモード |
| Sonnet 4.6 互換性 | ⚠️ deprecated（動作はするが非推奨）| ✅ 推奨 |

**簡潔なルール**：4.6 / 4.7 / 4.8 シリーズのモデルはすべて `adaptive` を使用、4.5 以前のみ `budget_tokens` を使用します。

## サポートモデルマトリクス

| モデル | adaptive thinking | budget_tokens | effort パラメータ |
|------|------------------|---------------|-------------|
| `claude-opus-4-8` | ✅ 唯一の有効化方法 | ❌ 400 error | ✅ low / medium / high / xhigh / max |
| `claude-sonnet-4-6` | ✅ 推奨 | ⚠️ 使用可だが deprecated | ✅ low / medium / high |
| `claude-opus-4-7` | ✅ 推奨 | ⚠️ 使用可だが deprecated | ✅ low / medium / high / max |
| `claude-haiku-4-5` | ✅ サポート | ❌ 非サポート | ❌ effort パラメータは error |
| `claude-sonnet-4-5` 以前 | ❌ 非サポート | ✅ こちらを使用 | ❌ |

> QCode.cc 経由でアクセスする際、上記すべてのモデルが利用可能です（実証済み）。

## effort パラメータ：思考の深さの粗調整ノブ

`effort` は adaptive thinking の総合的な強度（思考 tokens、ツール呼び出し回数、回答の詳細度を含む）を制御します。

| effort | 適用シナリオ | 大まかな相対コスト |
|--------|---------|-------------|
| `low` | 単純な質問応答、サブ agent、レイテンシに敏感 | 1× |
| `medium` | 一般的なコーディング、ドキュメント検索（多くの日常タスク）| 1.5-2× |
| `high` | 複雑な推論、複数ファイルにまたがるリファクタリング（**デフォルト**）| 2-3× |
| `xhigh` | 長時間 agent ワークフロー（Opus 4.8 専用、Claude Code デフォルト）| 3-4× |
| `max` | 最高品質優先、コストは二の次（Opus 4.8 / 4.7 のみ）| 5× |

**経験則**：`high` はほとんどの対話的コーディングタスクのスイートスポット；`xhigh` は長い agent ループ（複数ステップのコードレビュー、深掘り調査など）で最もコストパフォーマンスが良い；`max` は正確性がコストよりはるかに重要な場合のみ有効化（本番コード生成、重要なアーキテクチャ決定など）。

## API 呼び出し例

### Python（anthropic SDK）

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.qcode.cc/api",
    api_key="cr_xxxxxxxx",
)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "user service モジュールの認証ロジックをリファクタリングして..."}],
)

for block in response.content:
    if block.type == "thinking":
        print(f"[思考] {block.thinking}")
    elif block.type == "text":
        print(f"[回答] {block.text}")
```

### TypeScript（@anthropic-ai/sdk）

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.qcode.cc/api",
  apiKey: "cr_xxxxxxxx",
});

const response = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "xhigh" },
  messages: [{ role: "user", content: "user service をリファクタリング..." }],
});
```

### Claude Code CLI

CLI では effort をショートカットキー `Tab` で切り替えます。現在の effort はステータスバーに表示されます。Opus 4.8 はデフォルトで `xhigh` ですが、手動で `medium` まで下げて tokens を節約できます。

## 思考内容のレンダリング

Opus 4.8 はデフォルトで**思考テキストを表示しません**（`thinking.display: "omitted"`）、内部推論のみです。UI で思考過程を表示したい場合：

```python
thinking={"type": "adaptive", "display": "summarized"}
```

`display: "summarized"` はモデルに思考サマリ（可視の thinking blocks）を出力させます；`omitted` は思考 tokens をカウントするのみでテキストは出力しません。Sonnet 4.6 / Haiku 4.5 はデフォルトで `summarized` です。

## Task Budgets（Opus 4.8 Beta）

agent ループを実行し、ターン全体（思考 + ツール + 最終出力を含む）に対してグローバルな上限を設けたい場合は `task_budget` を使用します：

```python
response = client.beta.messages.create(
    betas=["task-budgets-2026-03-13"],
    model="claude-opus-4-8",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[...],
)
```

モデルは残り予算のカウントダウンを見ながら、超過しないように自己調整します。`total` の最小値は 20,000 です。

## コスト観測の推奨事項

adaptive thinking を有効化すると入力 / 出力 token が増加するため、監視が必要です：

```python
print(response.usage)
# 注目：input_tokens、output_tokens、cache_read_input_tokens
# Adaptive thinking は thinking tokens を個別に課金しません——output_tokens に含まれます
```

QCode.cc ユーザーの場合、リクエストは [probe.qcode.cc](https://probe.qcode.cc) にレポートされます——そこで各リクエストの input / output / 思考の比率を確認できます。

## よくある質問

### budget_tokens から adaptive thinking への移行はどう換算しますか？

線形の換算関係はありません。`budget_tokens=8000` は特定の effort レベルと等価ではありません。`effort: "medium"` から始めてテストし、回答品質と token 使用量に応じて調整することを推奨します。ハードリミットが必須の場合は `task_budget` を使用できます（上記参照）。

### Opus 4.8 でリクエストが 400 エラーになり budget_tokens が許可されないと表示される

`thinking={"type": "enabled", "budget_tokens": N}` をすべて `thinking={"type": "adaptive"}` に変更してください。`budget_tokens` フィールドは Opus 4.8 で完全に削除されています（任意の値で 400）。

### Sonnet 4.6 で budget_tokens を使い続けるべきですか？

推奨しません。新しいコードはすべて adaptive thinking を使用してください。`budget_tokens` は 4.6 でも動作しますが deprecated パスであり、将来のいずれかのバージョンで削除されます。

### Claude Code CLI で effort をどう変更しますか？

CLI ステータスバーに表示される effort は `Tab` で切り替えます。永続化されたデフォルト値は `~/.claude/settings.json` 内の `"effort"` フィールドにあります。

## 次のステップ

- [モデル選択ガイド](/docs/usage/model-selection) — 各モデルの料金、能力比較
- [ベストプラクティス](/docs/usage/best-practices) — 大規模コンテキスト、agent ワークフローの prompt テクニック
- [接続点と API 形式](/docs/getting-started/endpoints-and-api-paths) — QCode.cc 接続ドメイン全表
- [Claude Code 完全チュートリアル](/docs/getting-started/claude-code-tutorial) — CLI の全機能の使い方