Lv1 API基礎

前提: L0修了 or 免除 ／ CCAドメイン: ④ ／ 力量マップ: D. プロンプト・構造化出力 の基礎

主教材: Building with the Claude API 全文日本語ガイド（動画字幕ベース・2026-07-10改訂版。1.1 の「読む」に体験できる疑似ターミナルを埋め込み） 横断必修: 安全性・セキュリティ（safety-security.md）— 本レベルは「APIキーの秘匿」が該当

ゴール: Anthropic API を素の状態で正しく扱えること。モデルをタスクで選び、Messages API でマルチターン会話を実装し（会話状態はクライアント管理という本質を理解した上で）、system prompt / temperature / streaming / 構造化出力を使い分けられる状態。

進め方と環境準備

1. 読む → やる → 自己チェック の順。L1 は序盤なので演習は手順付き。
2. 環境: Python + Jupyter notebook（%pip install anthropic python-dotenv）。API key は notebook と同じディレクトリの .env に ANTHROPIC_API_KEY="..." として保存。
3. 安全（必須）: key をハードコードしない。.env は .gitignore に入れる。クライアントから直接 API を叩かない——key はサーバー側のみ（Lesson: Accessing the API の最初の原則）。
4. コストが不安なら各演習の低コスト版（Haiku・短プロンプト・小さい max_tokens・少ない試行）から。
5. 演習の提出物は共通4点: ① 実装 ② テストデータ（入力と期待） ③ 実行結果（出力・usage・観察） ④ 設計判断メモ（採用案・却下案・トレードオフ）。

1.1 モデル選定とAPIアクセス

学ぶこと

• 3ファミリーはコア能力を共有し最適化が違う: Opus=最高の知性・複雑なagentic codingに強い・thinking対応（公式名は「thinking」パラメータによる extended thinking / adaptive thinking であり、「reasoning」はAnthropicの機能名ではない）・コスト/レイテンシ高、Sonnet=速度と知性のベストバランス、Haiku=最速・最安（thinking 対応の可否は下の鮮度注意を参照）。なお Opus よりさらに上位に位置づけられる Claude Fable 5 / Mythos 5 という別ラインも存在するが、本カリキュラムでは基本の3ファミリーを扱う。
• 選定は「自分のユースケースで何が最重要か」から。実務は1アプリ内で複数モデルの使い分けが普通。
• リクエストの5ステップ（クライアント→自分のサーバー→API→応答→表示）と、クライアント直叩き禁止（key秘匿）。公式SDKは Python/TypeScript/C#/Go/Java/PHP/Ruby の7言語（「JavaScript」という別立てのSDKは存在せず、TypeScript SDKがNode.js/JS双方をカバーする）。
• 生成の内部処理は tokenization→embedding→contextualization→generation という4段階でざっくり理解しておくとよい（※これは教育目的の簡略化で、Anthropic公式が採用している用語ではない）。レスポンスには message のほか usage と stop_reason が含まれる。stop_reason には公式に end_turn / max_tokens / stop_sequence / tool_use / pause_turn / refusal の6種類が定義されている（自然終了・トークン上限・停止シーケンス到達などが代表例）。

鮮度注意: 教材内のモデル名（Claude 3.7 Sonnet）は古くなる。名前は公式ドキュメントで都度確認し、「使い分けの原理」を持ち帰る。またコース収録時点の説明では「Haiku=reasoning 非対応」とされたが、Haiku 4.5 は extended thinking（thinking: {type: "enabled", budget_tokens: N} 方式）に対応している（adaptive thinking / effort パラメータは非対応。2026-07-11 に公式 API リファレンスで確認）。逆に現行モデル（Opus 4.6+ / Sonnet 4.6+）では adaptive thinking（{type: "adaptive"}）が標準で、budget_tokens 方式は Opus 4.7 以降・Sonnet 5・Fable 5 では 400 エラーになる（モデル別の分岐表は L3B 3B.3 の注記参照）。モデル別の thinking 対応は世代で変わるため、公式 docs / Models API で確認すること。

読む

▍

本文は content というブロックの配列に入る（content[0].text で取り出す。装飾は自動で外れたりしない——欲しい形式は system prompt で指定する）。stop_reason は「なぜ止まったか」（end_turn=自然終了・max_tokens=打ち切り）、usage は課金対象のトークン数。全文ガイドの Lesson: Welcome to the course ／ Overview of Claude models ／ Accessing the API

やる — 演習1.1「初リクエストとモデル比較」

1. ベースライン: .env → クライアント作成 → create() で一問一答。message.content[0].text・usage・stop_reason を記録。
2. 実装: 同一プロンプトを Haiku と Sonnet に投げる比較スクリプト（モデル名は変数化）。
3. 敵対テスト: max_tokens=15 で応答が切れる様子と stop_reason の変化を観察。存在しないモデル名でエラーを読む。
4. 測定: モデル別のレイテンシと usage を表に。
5. 言語化: 「このタスクにどちらを使うか。なぜ Opus でないか」を3行で。

低コスト版: 1文プロンプト・max_tokens=100・各モデル1回。

自己チェック

1.2 リクエストの基本 — Messages API とマルチターン

学ぶこと

• create() の必須引数は model / max_tokens / messages。max_tokens は安全機構。テキストは message.content[0].text。
• messages は user（人間が書いたテキスト）と assistant（モデルが生成したテキスト）のリスト。
• API はステートレス: 会話状態を次のリクエストへ自動継承しない（サーバー側に「会話セッション」は存在しない）。文脈維持には ① 履歴リストを自前で維持し ② 毎回リスト全体を送る。※これは会話状態の管理の話であり、サービス側のデータ保持ポリシー（不正利用監視・契約上の保持など）とは別問題——「一切保存されない」と読み替えないこと。
• 定番3ヘルパー add_user_message / add_assistant_message / chat（コース全体の基本パターン）。

まず次の図で、リクエストに何を積み、レスポンスのどのフィールドを読むのかの全体像を掴む。

続いて次の図で、「サーバーが会話を記憶してくれる」という誤ったメンタルモデルを捨て、「毎回 messages に全履歴を積んで送る」という正しいモデルに置き換える。

✏️ 再現チェック: モジュールを読み終えたら、この図を見ずに白紙へ描き直す（矢印のラベルまで）。描けなかった部分が復習ポイント。

読む

全文ガイドの Lesson: Making a request ／ Multi-Turn conversations ／ Chat exercise

やる — 演習1.2「ステートレスの証明とループチャット」

1. ベースライン: 履歴なしで「量子コンピューティングを一文で定義」→別リクエストで「もう一文書いて」を送り、2問目が無関係になることを記録（ステートレスの実証）。
2. 実装: 3ヘルパー＋input() と while True のループチャット（Chat exercise 相当）。
3. 敵対テスト: 空入力・長入力・「さっき何て言った？」を投入。わざと add_assistant_message を1回スキップし文脈が壊れる様子を観察。
4. 測定: 各ターンの usage.input_tokens を記録し、ターンが進むほど入力トークンが増える（全履歴再送のコスト構造）ことを示す。
5. 言語化: 「会話状態をクライアント側で持つ設計の利点と負担」を3〜5行。

低コスト版: 3ターン・max_tokens=200・input_tokens は3点記録のみ。

自己チェック

1.3 system prompt と temperature

学ぶこと

• system prompt は応答のトーン・スタイルを制御。文字列を system keyword 引数で渡す（messages とは別）。1行目で役割を割り当てるのが定石（例: 忍耐強い数学の家庭教師→直接答えず導く）。
• 実装注意: system=None は渡せない。無いときは params dict に system キー自体を含めない（条件分岐＋**params）。
• temperature（0〜1、デフォルト1.0）は次トークン選択の確率分布を操作: 0=揺らぎを最小化（ほぼ常に最高確率のトークンを選ぶ）、高いほど低確率トークンが選ばれやすい。低=データ抽出など正確性重視、高=ブレスト・文章・ジョークなど創造性重視。
• 但し書き: 高 temperature ≠ 必ず違う出力（異なる出力になる確率が上がるだけ）。逆に temperature=0 ≠ 同一出力の保証。
  現行API

  ⚠️ 現行API注記（2026-07-11確認）: 公式ドキュメントは「temperature=0 でも完全に決定的にはならない」（同一入力でも結果が僅かに変わりうる）と明記している。厳密な再現性・形式保証が必要なら structured outputs（1.5 注記）・code grader での検証（L2）・再試行で担保する。さらに現行の最上位モデル（Opus 4.7/4.8・Sonnet 5・Fable 5）では temperature（および top_p・top_k）をデフォルト値以外に設定すると400エラーになる（デフォルト値のまま使う分には問題ない）。これらのモデルで creativity を制御したい場合は temperature ではなく system prompt の指示文で誘導する。

読む

全文ガイドの Lesson: System prompts ／ System prompts exercise ／ Temperature

やる — 演習1.3「役割の設計と温度の実験」

1. ベースライン: system prompt なしで「5x + 3 = 2 を解いて」→完全な解答が即返ることを記録。
2. 実装: chat(messages, system=None, temperature=1.0) に拡張（None 分岐を自分で書く）。家庭教師 system prompt と簡潔コード用 system prompt（"You are a Python engineer who writes very concise code." 相当）の2本で挙動差を記録。
3. 敵対テスト: 家庭教師モードのまま user message で「答えだけ教えて」と押し切り、system prompt がどこまで持つか観察（突破された記録にも価値がある）。
4. 測定: 「一文の映画のアイデア」を temperature 0.0 / 1.0 で各5回実行し、重複・類似を表に（上のモデル分岐注記に従い対応モデルへ切り替えるか system prompt 誘導に読み替えて実施）。
5. 言語化: 自分の実プロジェクトの機能2つについて temperature を宣言し理由を書く。

低コスト版: 各3回・max_tokens=100・敵対テストは1往復。

自己チェック

1.4 streaming

学ぶこと

• 問題: 応答完了まで10〜30秒かかることもある。スピナーは体験が悪く、ユーザーは即座に何か見え始めることを期待する。
• stream=True でイベントのストリームが返る: message_start → content_block_start → content_block_delta（複数回）→ content_block_stop → message_delta → message_stop。テキストを運ぶのは content_block_delta（1イベント＝1語とは限らない）。
• 実務は SDK の client.messages.stream()（with ＋ stream.text_stream）でテキストだけ簡単に取れる。
• 完了後 stream.get_final_message() で全チャンクを1つの完全なメッセージに（DB 保存・履歴用）。

次の図で、イベントが届く順序と「テキストを運ぶのは content_block_delta だけ」であることを掴む。

読む

全文ガイドの Lesson: Response streaming

やる — 演習1.4「イベントを読んでから隠す」

1. ベースライン: stream=True で生イベントを全部 print し、種類と順序を確認（1回でよい）。
2. 実装: client.messages.stream() ＋ text_stream に書き換え、print(text, end="") でチャンク表示。get_final_message() の結果を 1.2 の履歴に append できることを確認。
3. 敵対テスト: max_tokens を絞って途中で切れるケースを観察。ループチャットに組み込んだ際、履歴追加を忘れると次ターンが壊れることを確認。
4. 測定: 同一プロンプトで「非 streaming の完了時間」と「最初のチャンク到達時間」を比較。
5. 言語化: 「streaming を入れるかスピナーで済ませるか」の判断基準を測定値を根拠に3行。

低コスト版: 各パターン1回の計測でよい。

自己チェック

1.5 構造化データ生成 — prefilling と stop sequences

学ぶこと

• Claude は放っておくとヘッダー・フッター・解説を付けたがる。生データだけ欲しい場面（JSON・コード・リスト）ではこれが邪魔（例: ```json フェンス付きで機械処理できない）。
• 解法は assistant message prefilling ＋ stop_sequences: ```json をプリフィル→Claude は「もう書き始めた」と想定し続きの生データだけ書く。閉じデリミタ ``` を stop_sequences に指定→閉じようとした瞬間に停止。「これで始めて、それで終わって、間だけちょうだい」。取り出したら json.loads(text.strip())。
• prefill は開始文字だけでなく応答内容の誘導にも使える（例: "Here are all three commands in a single block without any comments:" ＋改行をプリフィル）。JSON 限定でなくあらゆる構造化コンテンツに応用可。

次の図で、使うモデルの世代で手法が分岐すること——現行モデルでは structured outputs が標準解で、教材の prefill＋stop_sequences は旧世代モデルでのみ動く——を掴む。

読む

全文ガイドの Lesson: Structured data ／ Structured data exercise

やる — 演習1.5「生JSONだけを取り出す」（足場少なめ）

1. ベースライン: 「非常に短い EventBridge ルールを JSON で」を素のまま実行し、フェンスや解説が付くことを記録。
2. 実装: prefill（```json）＋ stop_sequences=["```"] で生 JSON を取得し json.loads まで通す。続いて AWS CLI コマンド3つの演習を、プロンプト本文は変えず prefill の文言設計だけで「コメント無し・1ブロック」に安定させる。
3. 敵対テスト: あいまいな指示（「いい感じの設定を JSON で」）等でパースが落ちるケースを最低1つ見つけ、失敗時の扱い（エラー or 1回だけ再試行）を実装。
4. 測定: 同一リクエストを10回実行し json.loads 成功率を記録（prefill 改善前後で比較）。
5. 言語化: 「prefill+stop_sequences」と「プロンプトで『JSONだけ返して』」の違い・使い分けを実験結果を根拠に5行以内。

低コスト版: 各5回・max_tokens=300・敵対テスト2ケース。

自己チェック

以下の Q1〜Q3 は教材の手法（旧世代モデル＋prefill+stop 構成）を前提とする。現行モデルでは 1.5 の現行API注記のとおり structured outputs が標準解。

キャップストーン増分 — ドキュメント調査アシスタント 第1形態（v0.1）「構造化出力つきチャットCLI」

累積キャップストーン（L1〜L6）の第1形態。このレベルの要素だけで作る。置き場所は任意（例: learn/claude/capstone/）。以後のレベルで積み増すため使い捨てにしない。

要件

1. チャットCLI: input() ループ。履歴はクライアント側リストで管理し毎ターン全履歴を送る（1.2）。
2. system prompt: 「ドキュメント調査アシスタント」の役割・スタイル（例: 日本語・簡潔・不明なことは不明と言う）を定義（1.3）。
3. streaming: 応答は text_stream でチャンク表示し、get_final_message() で履歴に追加（1.4）。
4. 構造化出力コマンド: :note で会話の調査メモを JSON（例: {"topic": ..., "key_points": [...], "open_questions": [...]}）出力。手法は使うモデルで分岐（1.5 の現行API注記）: 旧世代モデルなら prefill＋stop_sequences、現行モデルなら structured outputs（output_config.format）。いずれも json.loads で検証し、失敗時は1回だけ再試行、それでも失敗ならエラー表示して会話は継続（1.5）。どちらを選んだかと理由を設計判断メモに書く。
5. 設定の使い分け: 通常応答と :note（抽出寄り＝低 temperature）で temperature を変える（1.3）。低 temperature の設定は使うモデルで分岐（1.3 のモデル分岐注記）: 現行モデル（claude-sonnet-5 等）では非デフォルト temperature が400エラーになるため、temperature 対応の旧世代モデルへ切り替えるか、system prompt の指示文（例:「抽出は一字一句正確に、推測や言い換えをしない」）で揺らぎを抑える方式に読み替える。
6. 安全: key は .env から。ハードコード・コミット禁止。.gitignore を成果物に含める。

提出物（4点）

低コスト版: シナリオ3本・:note 検証5回・max_tokens=500。ロジック検証は、記録済み応答テキストを返すフェイク chat 関数に差し替えてオフラインで行ってよい。

修了ゲート（L1）

共通ルール（DESIGN.md）: 知識20% / 実技60% / 説明20%、総合80%以上で合格。安全性の必須問題は配点と独立に全問正解。 採点は自動テスト＋ルーブリック＋Claude 一次レビュー＋本人による反証。再受験時は Claude に類題を作らせ同じ問題を使い回さない。

知識確認（5問・シナリオベース）

安全必須問題（全問正解が必要・配点と独立）

実技 — キャップストーン増分のルーブリック（5観点 × 0〜3点）

説明課題（20%）

どちらか1つを選び、初学者向けに書面または口頭（3分）で説明。正確さと「何が保証で何が確率か」の区別を評価:

1. temperature は内部で何を操作しているか＋低くすべき/高くしてよいタスクの実例（「高 temperature＝毎回違う出力」「temperature=0＝完全に決定的」という2つの誤解の訂正を含める）。
2. prefill＋stop_sequences で生 JSON だけが返る仕組みを、Claude の視点（「もう書き始めたと想定する」）から説明。あわせて「現行モデルでは prefill は 400 エラーで、標準解は structured outputs」というモデル分岐と使い分けに触れる。

遅延チェック

修了1〜2週間後に10〜20分: ヘルパー3関数を白紙から書けるか／K2・安全1 相当の類題／:note 成功率の再測定。不合格モジュールは復習キューへ（修了取消はしない）。

部分合格方式: ゲート本体は不合格項目のみ補習して再受験すればよい（合格済み項目は保持。共通運用は README.md 参照）。

力量マップ・CCA接続

• 力量マップ対応: D. プロンプト・構造化出力 — 修了で「構造化出力 / スキーマ強制」「モデル選定」を段階2（ガイド付き成果物）に更新可。証拠リンク（キャップストーン提出物4点）を必ず添える。「プロンプト設計」の本格上げは L2、「extended thinking」は L3B。
• CCA副線（ドメイン④）: cca-prep.md のドメイン④（プロンプト・構造化出力）のドリルを解く。L1 時点では prefill・system/user の役割分担が解けるはず。「厳密な JSON はスキーマ強制（structured outputs / strict tool use）が最も堅い」は L3A 学習後に完全理解できる——今は 1.5 の現行API注記のとおり「prefill より堅く、現行モデルの標準解でもある structured outputs がある」とだけ覚えておく。本格再診断は README の CCA 接続表どおり L2 修了後。
• 次へ: L2（プロンプト設計と評価）。L5（Claude Code）はここから並行開始も可。

最終確認日: 2026-07-11（教材: 全文ガイド 2026-07-10 改訂版に基づく。モデル名・SDK 仕様など製品依存の記述は公式ドキュメントで随時確認）