公式 Exam Guide 演習 — 実装ガイド

import Anthropic from '@anthropic-ai/sdk'
 
const client = new Anthropic()
 
// 1. ツール定義（境界を明示した description が肝）
const tools = [
  {
    name: 'get_customer',
    description:
      '顧客 ID またはメールでアカウントを検索・確認。返金や情報変更の前に必ず呼ぶ。注文照会には lookup_order を使うこと',
    input_schema: {
      type: 'object',
      properties: {
        identifier: { type: 'string', description: '顧客 ID またはメールアドレス' }
      },
      required: ['identifier']
    }
  },
  {
    name: 'lookup_order',
    description:
      '注文 ID で注文を照会。get_customer で本人確認したあとに使う。process_refund の前提条件',
    input_schema: {
      type: 'object',
      properties: {
        order_id: { type: 'string' }
      },
      required: ['order_id']
    }
  },
  {
    name: 'process_refund',
    description:
      '返金処理。$500 を超える額は PostToolUse フックで自動的にエスカレーション扱いになる（プロンプト側で制御しない）',
    input_schema: {
      type: 'object',
      properties: {
        customer_id: { type: 'string' },
        order_id: { type: 'string' },
        amount: { type: 'number' }
      },
      required: ['customer_id', 'order_id', 'amount']
    }
  },
  {
    name: 'escalate_to_human',
    description:
      '人間オペレーターへ引き継ぐ。customer_id・root_cause・recommended_action を必ず含めること',
    input_schema: {
      type: 'object',
      properties: {
        customer_id: { type: 'string' },
        root_cause: { type: 'string' },
        recommended_action: { type: 'string' }
      },
      required: ['customer_id', 'root_cause', 'recommended_action']
    }
  }
]
 
// 2. 構造化エラー型 — LLM が「リトライしていいか」を機械的に判断できる形にする
type ErrorCategory = 'transient' | 'validation' | 'permission' | 'business'
 
type ToolErrorResult = {
  isError: true
  errorCategory: ErrorCategory
  isRetryable: boolean
  message: string
  retryAfterMs?: number
}
 
const RETRY_POLICY: Record<ErrorCategory, boolean> = {
  transient: true,
  validation: false,
  permission: false,
  business: false
}
 
function makeError(category: ErrorCategory, message: string): ToolErrorResult {
  return {
    isError: true,
    errorCategory: category,
    isRetryable: RETRY_POLICY[category],
    message
  }
}
 
// 3. PostToolUse フック — ビジネスルールを「決定論的に」強制
type ToolInput = Record<string, unknown>
 
function postToolUseHook(toolName: string, input: ToolInput, result: unknown) {
  if (toolName === 'process_refund' && typeof input.amount === 'number' && input.amount > 500) {
    return {
      blocked: true,
      redirect: 'escalate_to_human',
      reason: '$500 超の返金は人間承認が必要',
      input_for_redirect: {
        customer_id: input.customer_id,
        root_cause: 'refund_amount_over_threshold',
        recommended_action: `Approve $${input.amount} refund for customer ${input.customer_id}`
      }
    }
  }
  return result
}
 
// 4. ツール実行ディスパッチャ — 各ツールのエラーカテゴリを返す例
async function dispatchTool(name: string, input: ToolInput): Promise<unknown> {
  switch (name) {
    case 'get_customer': {
      // 検索結果なし = valid empty result（成功として返す）
      // タイムアウト = transient access failure（エラーとして返す）
      try {
        return await fakeDb.findCustomer(input.identifier as string)
      } catch (e: unknown) {
        if (e instanceof TimeoutError) return makeError('transient', String(e))
        throw e
      }
    }
    case 'process_refund': {
      const amount = input.amount as number
      if (amount <= 0) return makeError('validation', 'amount must be positive')
      return await fakeDb.refund(input as { customer_id: string; order_id: string; amount: number })
    }
    // ... 他のツールも同様
    default:
      return makeError('validation', `unknown tool: ${name}`)
  }
}
 
// 5. エージェンティックループ — stop_reason 駆動・並列 tool_use 対応
async function runAgent(userMessage: string) {
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: userMessage }]
 
  while (true) {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-6',
      max_tokens: 4096,
      tools,
      messages
    })
 
    messages.push({ role: 'assistant', content: response.content })
 
    // ❌ Anti-pattern: テキストに「完了」が入っているかで判定
    // ✅ stop_reason で判定
    if (response.stop_reason === 'end_turn') return response
 
    if (response.stop_reason === 'tool_use') {
      // 1 レスポンス内の全 tool_use を「並列に」処理
      const toolUses = response.content.filter(
        (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use'
      )
 
      const toolResults = await Promise.all(
        toolUses.map(async tu => {
          const raw = await dispatchTool(tu.name, tu.input as ToolInput)
          const hooked = postToolUseHook(tu.name, tu.input as ToolInput, raw)
          return {
            type: 'tool_result' as const,
            tool_use_id: tu.id,
            content: JSON.stringify(hooked)
          }
        })
      )
 
      // tool_result は user ロールに含めて返す（ここを assistant にすると正しく動作しない）
      messages.push({ role: 'user', content: toolResults })
      continue
    }
 
    return response
  }
}

<!-- .claude/CLAUDE.md（チーム共有・git 管理下） -->
# チーム標準
 
## コーディング規約
 
- TypeScript: strict mode 必須、`any` 型禁止、関数の戻り値型は明示
- React: Server Components 優先、'use client' は必要時のみ
- テスト: 新規モジュールは追加時にテストを書く（カバレッジ ratchet）
 
## Pull Request の流れ
 
1. `feat/...` ブランチで実装
2. `npm run typecheck && npm run test && npm run build` がパスすること
3. PR は draft で起票し、CI 緑になったら ready 化
4. squash merge
 
外部参照:
 
@./docs/architecture.md
@./docs/migration-rules.md

<!-- .claude/rules/api.md（API 専用ルール、API ファイル編集時にだけロード） -->
---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.tsx"
---
API ハンドラの規約：
 
- 入力 schema は zod で定義し、`parse` ではなく `safeParse` を使う
- すべてのエンドポイントに rate limit middleware を通す
- ログには PII（メール・電話番号）を含めない

<!-- .claude/rules/typescript.md -->
---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---
- import は `import type` で型のみインポートする箇所と値インポートを区別する
- exhaustive switch は `assertNever` ヘルパでガードする

<!-- .claude/skills/release-note/SKILL.md -->
---
name: release-note
description: 直近のリリースタグから現在までのコミットを集約し、CHANGELOG エントリを下書きする。`/release-note <tag>` で実行
context: fork
allowed-tools:
  - Bash
  - Read
argument-hint: "[from-tag]"
disable-model-invocation: true
model: sonnet
---
 
# Release note generator
 
`git log <from-tag>..HEAD --oneline` を解析し、Conventional Commits の prefix ごとに分類した changelog エントリをドラフトする。
副作用なし、実際の CHANGELOG.md への書き込みは人間レビュー後。

// .mcp.json — stdio + Streamable HTTP の混在例
// stdio（ローカル subprocess）と Streamable HTTP（hosted MCP）は同じ .mcp.json で混在 OK
{
  "mcpServers": {
    // stdio: ローカル subprocess を npx で起動
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    // Streamable HTTP: hosted MCP（2025-11-25 spec の remote 公式形式）
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${ATLASSIAN_TOKEN}"
      }
    }
  }
}

<!-- CLAUDE.local.md（個人 override・gitignore 対象） -->
# 個人設定
 
ローカル開発で使うパス・ポート：
 
- DB: `postgres://localhost:5433/myapp_dev`
- 個人検証用ブランチは `wip/yokoto/...` プレフィックス

// .claude/settings.json — 実際のツール制限はここで
{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ],
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run typecheck)"
    ]
  }
}

import Anthropic from '@anthropic-ai/sdk'
 
const client = new Anthropic()
 
// 1. nullable と enum + "other" を活用したスキーマ
const extractInvoice = {
  name: 'extract_invoice',
  description: '請求書ドキュメントから構造化データを抽出する',
  input_schema: {
    type: 'object',
    properties: {
      invoice_number: { type: 'string' },                // required
      total_amount: { type: 'number' },                  // required
      currency: { type: 'string', enum: ['USD', 'JPY', 'EUR', 'other'] },
      currency_other: { type: ['string', 'null'] },       // currency=other の詳細
      due_date: { type: ['string', 'null'], description: 'ISO 8601 (YYYY-MM-DD) または不明なら null' },
      tax_rate: { type: ['number', 'null'] },
      line_items: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            description: { type: 'string' },
            amount: { type: 'number' },
            confidence: { type: 'number', description: '0..1、低い場合は人間レビューへ' }
          },
          required: ['description', 'amount', 'confidence']
        }
      }
    },
    required: ['invoice_number', 'total_amount', 'currency', 'line_items']
  }
} as const
 
// 2. バリデータ — 構文ではなく意味エラーを検出する
type ValidationIssue = { path: string; reason: string }
 
function validateInvoice(data: any): ValidationIssue[] {
  const issues: ValidationIssue[] = []
  const sumOfLines = data.line_items.reduce(
    (s: number, li: any) => s + li.amount,
    0
  )
  if (Math.abs(sumOfLines - data.total_amount) > 0.01) {
    issues.push({
      path: '$',
      reason: `total_amount (${data.total_amount}) does not match sum of line_items (${sumOfLines})`
    })
  }
  if (data.currency === 'other' && !data.currency_other) {
    issues.push({ path: '$.currency_other', reason: 'must be set when currency=other' })
  }
  return issues
}
 
// 3. Few-shot プロンプトで「情報不在 → null」を強化
const SYSTEM_PROMPT = `あなたは請求書データを抽出するアシスタントです。
 
ルール:
- ドキュメントに記載がないフィールドは null を返す（推測しない）
- enum で網羅できない値は "other" を選び、currency_other に詳細を書く
- 各 line_item に confidence (0..1) を付ける。文字が掠れている・OCR ノイズが多い箇所は低めに
 
例 1（明確な請求書）:
入力: "Invoice #INV-001  Total: $100  Tax: 10%  Items: Widget x1 $90, Tax $10"
出力: {
  invoice_number: "INV-001",
  total_amount: 100,
  currency: "USD",
  currency_other: null,
  due_date: null,             // 期日の記載なし → null
  tax_rate: 0.10,
  line_items: [
    { description: "Widget x1", amount: 90, confidence: 0.95 },
    { description: "Tax", amount: 10, confidence: 0.95 }
  ]
}
 
例 2（OCR ノイズあり）:
入力: "Inv#A-22  T0tal: $48.20  Wdg3t: $43.20"  (一部判読不能)
出力: {
  invoice_number: "A-22",
  total_amount: 48.20,
  currency: "USD",
  currency_other: null,
  due_date: null,
  tax_rate: null,             // 不明 → null
  line_items: [
    { description: "Widget", amount: 43.20, confidence: 0.6 },  // OCR ノイズで low confidence
    { description: "(不明)", amount: 5.00, confidence: 0.3 }
  ]
}`
 
// 4. retry-with-error-feedback ループ
async function extractWithRetry(documentText: string, maxAttempts = 2) {
  let lastResult: any = null
  let lastIssues: ValidationIssue[] = []
 
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const messages: Anthropic.MessageParam[] = [
      { role: 'user', content: `# Document\n\n${documentText}` }
    ]
    if (lastResult && lastIssues.length > 0) {
      // 失敗した抽出と具体的なエラーを context に含めて再送
      messages.push({ role: 'assistant', content: JSON.stringify(lastResult) })
      messages.push({
        role: 'user',
        content: `バリデーションが失敗しました。以下の問題を修正してください。
 
${lastIssues.map(i => `- ${i.path}: ${i.reason}`).join('\n')}
 
修正版を返してください。`
      })
    }
 
    const response = await client.messages.create({
      model: 'claude-sonnet-4-6',
      max_tokens: 4096,
      system: SYSTEM_PROMPT,
      tools: [extractInvoice],
      tool_choice: { type: 'tool', name: 'extract_invoice' },  // 強制
      messages
    })
 
    const block = response.content.find(b => b.type === 'tool_use')
    if (!block || block.type !== 'tool_use') throw new Error('expected tool_use')
 
    const issues = validateInvoice(block.input)
    if (issues.length === 0) return { ok: true as const, data: block.input }
 
    lastResult = block.input
    lastIssues = issues
  }
 
  // ❌ Anti-pattern: ここで「情報不在」だった場合に無限リトライループ
  // ✅ 上限到達 → 人間レビューへ
  return { ok: false as const, partial: lastResult, issues: lastIssues }
}
 
// 5. Batch API 投入（100 件・SLA 不要なケースのみ）
async function submitBatch(documents: { id: string; text: string }[]) {
  return await client.messages.batches.create({
    requests: documents.map(d => ({
      custom_id: d.id,             // 紐付けに必須
      params: {
        model: 'claude-sonnet-4-6',
        max_tokens: 4096,
        system: SYSTEM_PROMPT,
        tools: [extractInvoice],
        tool_choice: { type: 'tool', name: 'extract_invoice' },
        messages: [{ role: 'user', content: `# Document\n\n${d.text}` }]
      }
    }))
  })
}

// 1. コーディネーターから並列 Task 発行
// 1 つの assistant レスポンスの content に複数 tool_use を含めれば並列
const coordinatorResponse = await client.messages.create({
  model: 'claude-opus-4-7',
  max_tokens: 8192,
  tools: [TaskTool],   // allowedTools: ["Task"] 相当
  messages: [
    { role: 'user', content: 'Q4 売上トレンドと競合動向を比較した投資レポートを作成' }
  ]
})
 
// 期待される content:
// [
//   { type: 'tool_use', name: 'Task', input: { description: 'Search Agent: ...', prompt: <full ctx> } },
//   { type: 'tool_use', name: 'Task', input: { description: 'Analysis Agent: ...', prompt: <full ctx> } }
// ]
 
// 2. コンテキスト渡し — 元要求 + 前段結果 + 制約 + 出力スキーマを明示
function buildAnalysisPrompt(originalRequest: string, searchResults: unknown) {
  return `## 元のユーザー要求
"${originalRequest}"
 
## 前段（Search Agent）の出力
${JSON.stringify(searchResults, null, 2)}
 
## あなたのタスク
上記の検索結果を分析し、以下の JSON 形式で返してください：
 
{
  "trends": [
    { "metric": string, "direction": "up" | "down" | "flat", "evidence": string, "source_url": string, "published_date": string }
  ],
  "competitors": [
    { "name": string, "signal": string, "source_url": string, "published_date": string, "excerpt": string }
  ]
}
 
## 制約
- 公開日 2024 年以降のソースのみ使用
- 各 claim に source_url と published_date を必ず含める
- 不確実な場合は trends/competitors から除外し、out_of_scope セクションに移すこと`
}
 
// 3. 部分的成功 + カバレッジギャップ注釈
type SubagentSuccess = { ok: true; data: unknown }
type SubagentFailure = {
  ok: false
  errorCategory: 'transient' | 'validation' | 'permission' | 'business'
  attemptedQuery: string
  partialResults: unknown | null
  alternatives: string[]
}
type SubagentResult = SubagentSuccess | SubagentFailure
 
async function runSubagentsInParallel(
  tasks: Array<{ name: string; prompt: string; query: string }>
): Promise<SubagentResult[]> {
  const results = await Promise.allSettled(
    tasks.map(t => callSubagent(t.name, t.prompt))
  )
 
  return results.map((r, i) => {
    if (r.status === 'fulfilled') return { ok: true, data: r.value }
    return {
      ok: false,
      errorCategory: 'transient',
      attemptedQuery: tasks[i].query,
      partialResults: null,
      alternatives: [
        'retry with narrower date range',
        'fall back to cached results',
        'skip and annotate as coverage_gap'
      ]
    }
  })
}
 
// 4. 合成エージェントの入力構築 — 失敗を「カバレッジギャップ」として明示
function buildSynthesisInput(
  results: SubagentResult[],
  originalRequest: string
) {
  const successful = results.filter((r): r is SubagentSuccess => r.ok)
  const failed = results.filter((r): r is SubagentFailure => !r.ok)
 
  return {
    original_request: originalRequest,
    partial_results: successful.map(s => s.data),
    coverage_gaps: failed.map(f => ({
      attempted_query: f.attemptedQuery,
      error_category: f.errorCategory,
      suggested_alternatives: f.alternatives
    })),
    is_complete: failed.length === 0
  }
 
  // ❌ Anti-pattern: if (failed.length > 0) throw new Error('全体失敗')
  // → 部分結果を捨ててしまう。コーディネーターは部分結果 + ギャップ注釈を必ず合成へ流す
}
 
// 5. 競合する情報源の扱い — 一方を選ばず両方を帰属付きで残す
type Claim = {
  metric: string
  value: number
  source_url: string
  published_date: string
}
 
type SynthesizedClaim = {
  metric: string
  values: Array<Claim>
  conflict_detected: boolean
  resolution_note: string | null
}
 
function reconcileClaims(claims: Claim[]): SynthesizedClaim[] {
  const byMetric = new Map<string, Claim[]>()
  for (const c of claims) {
    if (!byMetric.has(c.metric)) byMetric.set(c.metric, [])
    byMetric.get(c.metric)!.push(c)
  }
 
  return [...byMetric.entries()].map(([metric, vs]) => {
    const values = vs.map(v => v.value)
    const allEqual = values.every(v => v === values[0])
    return {
      metric,
      values: vs,                         // 両方の出所を保持
      conflict_detected: !allEqual,
      resolution_note: allEqual
        ? null
        : `Sources disagree on ${metric}. Reporting both with attribution; reader should choose primary source.`
    }
  })
 
  // ❌ Anti-pattern: const winner = vs[0]  // 任意選択 → 出所情報の消失
}