Claude Code ガイド

Appearance

原文（日本語訳） ​

Claude Sonnet 5のセッションでは、ハーネスのリマインダー配信に会話途中の system ロールを使用しなくなりました。

原文（英語） ​

Claude Sonnet 5 sessions no longer use the mid-conversation system role for harness reminders

概要 ​

Claude Codeは会話の途中で、ツール実行結果や環境の変化などをモデルに伝える「ハーネスリマインダー」（<system-reminder> タグなど）を差し込んでいます。従来はこれをAnthropic APIの「mid-conversation system message」（会話途中に role: "system" のメッセージを挿入する機能）として送信していましたが、この機能は現時点でClaude Opus 4.8限定のサポートです。今回のアップデートで、Claude Sonnet 5をハーネスのモデルとして使うセッションでは、同じリマインダーを通常の user ターンの中に埋め込む方式に変更されました。

基本的な使い方 ​

これはClaude Code内部の実装詳細であり、ユーザーが設定を変更する項目ではありません。ただし、Claude Agent SDKや独自のAPI連携でエージェントハーネスを実装している場合は、モデルによってリマインダーの配信ロールが異なる点を理解しておく必要があります。

  • Claude Opus 4.8 をハーネスのモデルに使う場合: リマインダーは会話途中に role: "system" のメッセージとして挿入される
  • Claude Sonnet 5 をハーネスのモデルに使う場合: 同じリマインダーが role: "user" メッセージ内に埋め込まれる（会話途中の system ロールは使われない）

これはAnthropic APIの「mid-conversation system messages」機能自体が、現時点でClaude Opus 4.8限定でサポートされていることに対応した変更です。

実践例 ​

独自のエージェントハーネスを実装している場合 ​

Claude Agent SDKやAnthropic APIを直接呼び出して自前のエージェントを構築している場合、モデルに応じてリマインダーの送信方法を切り替える必要があります。

python
import anthropic

client = anthropic.Anthropic()

def add_harness_reminder(messages, model, reminder_text):
    if model.startswith("claude-opus-4"):
        # Opus 4.8: 会話途中のsystemロールとして追加
        # cache_controlで区切ったプレフィックスを維持したまま挿入できる
        messages.append({"role": "system", "content": reminder_text})
    else:
        # Sonnet 5など: userターン内にリマインダーを埋め込む
        messages.append({
            "role": "user",
            "content": f"<system-reminder>{reminder_text}</system-reminder>",
        })
    return messages

セッションログ・トランスクリプト解析ツールを作っている場合 ​

Claude Codeのセッションログ（JSONL）やオブザーバビリティツールで、メッセージの role フィールドを見てハーネスリマインダーを判別しているツールは、Sonnet 5のセッションでは system ロールではなく user ロールの中身を見る必要があります。

python
def is_harness_reminder(message):
    # 従来: role == "system" だけを見ていた
    # 変更後: Sonnet 5では user メッセージ内のタグも確認する
    if message["role"] == "system":
        return True
    if message["role"] == "user":
        content = message.get("content", "")
        text = content if isinstance(content, str) else str(content)
        return "<system-reminder>" in text
    return False

Opus 4.8への切り替えとプロンプトキャッシュへの影響 ​

mid-conversation system messages は、会話の先頭にある system フィールドやキャッシュ済みのプレフィックスを変更せずに、途中から新しい指示を追加できる機能です。Opus 4.8をハーネスに使っている場合はこの仕組みでキャッシュ効率を保てますが、Sonnet 5では同等のAPI機能が使えないため、リマインダーは通常の user ターンとして追加されます。長いエージェントセッションでキャッシュヒット率を厳密に検証したい場合は、モデルごとにこの違いがあることを踏まえて計測してください。

bash
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are a coding assistant.",
    "messages": [
      {"role": "user", "content": "Run the test suite."},
      {"role": "assistant", "content": "Running tests now."},
      {"role": "system", "content": "Reminder: 3 files changed on disk since the last turn."}
    ]
  }'

注意点 ​

  • これはClaude Code内部の実装詳細の変更であり、ユーザー側で設定を変更する必要はありません
  • Anthropic APIの「mid-conversation system messages」機能は現時点でClaude Opus 4.8限定であり、Claude API・Claude Platform on AWS・Microsoft Foundryでのみ利用可能です（Amazon BedrockやGoogle Cloud/Vertexでは非対応）
  • 独自にAnthropic APIを直接呼び出してハーネスやエージェントを構築している場合、使用するモデルによってリマインダー等の「システム的な指示」をどのロールで送るべきかが変わる点に注意してください
  • セッションのJSONLログやトランスクリプトを解析するツール・可観測性基盤を持っている場合は、Sonnet 5のセッションで system ロールの有無だけを見て判定しているとリマインダーを見落とす可能性があります

関連情報 ​