Claude Sonnet 5.5入門——AI実装の速度と品質をeffortで測る

はじめに

AIコーディングをチームに入れていると、新モデルのニュースで一番気になるのは「賢くなったか」だけではありません。

• 小さな修正を待たされずに返してくれるか
• レビューで余計な変更を増やさないか
• 高いモデルと安いモデルをどう使い分けるか
• tool useやthinkingまわりの移行差分で壊れないか

Anthropicは2026年9月28日にClaude Sonnet 5.5を発表しました。公式発表では、Sonnet 5より30%以上高速で、ほとんどの作業で最大30%低コスト、Claude APIのモデルIDは claude-sonnet-5-5 と案内されています。特に開発者に効くのは、日常的なバグ修正や明確に切られた実装タスクを、Opus 5.5より軽く回す候補が増えたことです。

本記事では、架空の業務SaaS「TaskHarbor」を題材に、Next.js App Router + Firestore + GitHub Actions + TypeScriptで、AI実装タスクをSonnet 5.5へ移すための評価台帳を作ります。この記事を読み終えると、モデル差し替えを勢いで進めず、速度・費用・品質を同じものさしで比較できるようになります。

参考にした一次情報は次の通りです。

• Claude Sonnet 5.5
• Migrating to Claude Sonnet 5.5
• Claude Sonnet 5.5 - Claude Platform Docs
• Models overview - Claude Platform Docs

Sonnet 5.5で見るべき変化

公式発表では、Sonnet 5.5はOpus 5.5の補完として位置づけられています。複雑で判断の重い仕事はOpus、範囲が明確な日常タスクやバグ修正、ドキュメント作成はSonnet 5.5、という分け方です。

TaskHarborでは、次のように役割を分けます。

もう1つ重要なのが effort です。Claude Platform Docsでは、Sonnet 5.5に low、medium、high、xhigh、max のeffort levelがあり、APIの既定は high、Claude appsの既定は medium と説明されています。日常タスクなら medium から試し、長い実装や失敗時だけ high に上げる運用が現実的です。

ハンズオン1: モデルとeffortを設定に集約する

まず、モデル名とeffortをコード中に散らばらせないようにします。TaskHarborでは、AI実装の候補モデルを限定し、環境変数で切り替えます。

// src/lib/ai/claudeCodingConfig.ts
export type ClaudeCodingModel = "claude-sonnet-5" | "claude-sonnet-5-5";
export type ClaudeEffort = "low" | "medium" | "high";

export function getClaudeCodingConfig(): {
  model: ClaudeCodingModel;
  effort: ClaudeEffort;
} {
  const model = process.env.CLAUDE_CODING_MODEL ?? "claude-sonnet-5";
  const effort = process.env.CLAUDE_CODING_EFFORT ?? "medium";

  if (model !== "claude-sonnet-5" && model !== "claude-sonnet-5-5") {
    throw new Error(`Unsupported Claude model: ${model}`);
  }

  if (effort !== "low" && effort !== "medium" && effort !== "high") {
    throw new Error(`Unsupported Claude effort: ${effort}`);
  }

  return { model, effort };
}

この記事では xhigh と max をあえて扱いません。移行ガイドでは、between_tools は low、medium、high で使え、xhigh や max では400エラーになると説明されています。最初の移行では、CIで扱いやすい範囲に絞る方が事故を減らせます。

ハンズオン2: Sonnet 5.5を呼び出す

次に、公式TypeScript SDKである @anthropic-ai/sdk を使います。npmで @anthropic-ai/sdk と firebase-admin の存在を確認済みです。

yarn add @anthropic-ai/sdk firebase-admin

Sonnet 5.5へ移すときに注意したいのは、thinkingの扱いです。移行ガイドでは、Sonnet 5.5で上位のthinkingを止めたい場合、Sonnet 5の thinking: { "type": "disabled" } ではなく、thinking: { "type": "between_tools" } を使うと案内されています。

// src/lib/ai/runImplementationPlan.ts
import Anthropic from "@anthropic-ai/sdk";
import { getClaudeCodingConfig } from "./claudeCodingConfig";

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

export async function runImplementationPlan(input: {
  issueKey: string;
  title: string;
  acceptanceCriteria: string[];
}) {
  const { model, effort } = getClaudeCodingConfig();
  const startedAt = Date.now();

  const message = await anthropic.messages.create({
    model,
    max_tokens: 1600,
    thinking:
      model === "claude-sonnet-5-5"
        ? { type: "between_tools" }
        : { type: "disabled" },
    output_config: { effort },
    messages: [
      {
        role: "user",
        content: [
          "あなたはNext.js App RouterとFirestoreに詳しい実装担当です。",
          "次のIssueについて、最初に触るファイル、テスト観点、リスクを短く整理してください。",
          `Issue: ${input.issueKey} ${input.title}`,
          `Acceptance criteria:\n${input.acceptanceCriteria.join("\n")}`,
        ].join("\n\n"),
      },
    ],
  });

  const text = message.content
    .filter((block) => block.type === "text")
    .map((block) => block.text)
    .join("\n");

  return {
    model,
    effort,
    text,
    stopReason: message.stop_reason,
    usage: message.usage,
    durationMs: Date.now() - startedAt,
  };
}

ポイントは、表示用テキストを type === "text" のblockから組み立てることです。Sonnet 5.5ではthinking blockが返る場合があるため、content[0].text を前提にした実装は移行時に壊れやすくなります。

ハンズオン3: Firestoreに評価台帳を保存する

モデル移行の成否は、1回の印象では判断しにくいです。20〜30件のIssueを3〜4件ずつ試し、Firestoreに結果を残します。

// src/app/actions/saveClaudeCodingEval.ts
"use server";

import { FieldValue } from "firebase-admin/firestore";
import { db } from "@/lib/firebaseAdmin";

export async function saveClaudeCodingEval(input: {
  issueKey: string;
  model: string;
  effort: "low" | "medium" | "high";
  durationMs: number;
  inputTokens?: number;
  outputTokens?: number;
  stopReason: string | null;
  humanScore: 1 | 2 | 3 | 4 | 5;
  needsRetry: boolean;
  notes: string;
}) {
  await db.collection("claudeCodingEvaluations").add({
    provider: "anthropic",
    taskKind: "implementation_plan",
    ...input,
    createdAt: FieldValue.serverTimestamp(),
  });
}

humanScore は、人間の開発者が「このまま着手できるか」を採点する値です。AIの自己評価だけにすると、実務の手戻りを拾いにくくなります。needsRetry も残しておくと、Sonnet 5.5の medium で足りるタスクと、high やOpusへ上げるべきタスクが分かれてきます。

ハンズオン4: GitHub Actionsで段階的に試す

GitHub Actionsでは、専用ラベルを付けたIssueやPRだけをSonnet 5.5評価に回します。いきなり全PRへ適用せず、小さなバッチで比較します。

name: Claude coding evaluation

on:
  pull_request:
    types: [opened, synchronize, labeled]

jobs:
  evaluate-sonnet-55:
    if: contains(github.event.pull_request.labels.*.name, 'ai-sonnet-55-eval')
    runs-on: ubuntu-latest
    env:
      CLAUDE_CODING_MODEL: claude-sonnet-5-5
      CLAUDE_CODING_EFFORT: medium
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: yarn
      - run: yarn install --frozen-lockfile
      - run: yarn build
      - run: yarn tsx scripts/evaluate-claude-coding.ts

このワークフローでは、ai-sonnet-55-eval ラベル付きPRだけを対象にします。TaskHarborでは、最初の週はUI文言修正やFirestore index追加のような小さめのIssueを10件、次の週にServer Actionsや権限チェックを含むIssueを10件、という順で広げます。

移行時の注意点

Sonnet 5.5は単なるモデルID差し替えではありません。移行ガイドで確認したい項目を、TaskHarbor向けに絞ると次の表になります。

特に、セキュリティ系のタスクは慎重に扱います。公式発表では、Sonnet 5.5はサイバー関連の安全策とフォールバックを備えており、高リスクな要求では挙動が変わる場合があります。通常のバグ修正やアプリの保守は対象外と説明されていますが、脆弱性調査を自動化しているチームは、拒否やfallbackをエラーとして潰さず、監査ログに残す設計にしておくべきです。

まとめ

Claude Sonnet 5.5は、日常的なAI実装タスクの既定モデルを見直す良いきっかけです。公式情報では、Sonnet 5より高速で、タスクあたりの費用も下がりやすく、コーディング評価でも大きく伸びています。一方で、thinking、effort、tool useの移行差分を無視すると、既存のAI機能が静かに壊れる可能性があります。

• Claude APIのモデルIDは claude-sonnet-5-5
• 小さな実装やバグ修正は medium から測る
• thinking.type.disabled 前提の実装は見直す
• Firestoreに速度、token、停止理由、人間の採点を保存する
• GitHub Actionsではラベル付きPRから段階的に広げる

新モデル移行は、速さのニュースに乗る作業ではなく、自分たちの開発テンポを合わせ直す作業です。Sonnet 5.5をメトロノームのように使い、タスクごとのちょうどよいeffortを見つけていきましょう。