AI開発・プログラミング入門｜コード生成からアプリ構築まで

会社のPCやVPN越しでClaude Codeが「Can't reach the API server — check your internet or DNS (ENOTFOUND)」「Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)」「SSL certificate verification failed」「fetch failed」で繋がらない——これらはリクエストがAnthropicのサーバ(api.anthropic.com)まで届いていないネットワーク系エラーで、認証(401/403)・サーバ過負荷(529/500)・レート制限(429)とは別物だ。v2.1.227より前は、同じエラーが「Unable to connect to API (ECONNREFUSED)」のようにコードを付けるだけで表示されていた。本記事では、現行の文言ごとの意味(No internet route・Couldn't connect through your proxy・Connection droppedを含む)、初回セットアップで終了する「Unable to connect to Anthropic services」(プロキシ変数の確認、利用できない国・地域の可能性)、途中のプロキシやゲートウェイが応答を加工したときの「Streaming response ended before any complete data was received」、企業ネットワークで詰まる3層(プロキシ未設定・TLS検査による証明書差し替え・ファイアウォールのドメイン遮断)とDNS/VPN/Docker、プロキシ設定(HTTPS_PROXY/HTTP_PROXY/NO_PROXY、SOCKS非対応、NTLM/KerberosはLLMゲートウェイ)、TLSと社内CA証明書(v2.1.273以降の証明書エラーの文言、/loginと起動時の「SSL certificate error」、NODE_EXTRA_CA_CERTS、mTLS)、絶対にやってはいけないNODE_TLS_REJECT_UNAUTHORIZED=0、ファイアウォールの許可ドメイン、切り分けワークフロー、認証・サーバ・レートとの区別までを、公式のエラーリファレンスの原文に基づいて整理する。

Claude Codeで突然「API Error: 529 {"type":"overloaded_error","message":"Overloaded"}」や「500 Internal server error」が出て止まった——これらはサーバー側の一時的な事象で、あなたのリクエストや設定のミスでも使用量の枠切れでもない。本記事では、529 Overloaded（Anthropic側のAPIが一時的に過負荷＝全ユーザー共通の混雑）と500（サーバー内部の予期しないエラー、関連で504 timeout_error。502/503は上流インフラ由来が多い）の意味、いずれもあなたの使用量の枠を消費しないこと、Claude Codeが表示前に最大10回・指数バックオフで自動リトライしている仕組み（Retrying in Ns・attempt x/y、CLAUDE_CODE_MAX_RETRIES既定10・API_TIMEOUT_MS既定10分）、ユーザー側の対処（少し待って再試行・/modelでモデル切替＝容量はモデル別なのでOpusが混んでもSonnetなら通ることが多い・status.claude.com確認・500継続ならrequest_idを添えて/feedback）、紛らわしいエラーとの区別（529/500=サーバー側で枠不消費／429=あなたのレート制限でretry-after付き・枠消費／usage limit=プラン枠／400=リクエストの不備）、開発者向け（SDKの型付き例外と自動リトライ・指数バックオフ＋ジッター・429ではretry-afterに従う・--fallback-model・Priority Tier/Batch）、一時的スパイクか継続インシデントかの見分けまでを、公式情報に基づいて整理する。

Claude Codeで作業中に突然「You've hit your session limit · resets 3:45pm」と出て手が止まる——これはエラーやバグではなく、サブスクの使用量制限の仕様だ。公式エラーリファレンスには session（5時間ローリング枠）・weekly（週次枠）・Opus・Sonnet（系統ごとの枠）の4通りが載っており、session と weekly は全モデル共通なので、モデルを替えても戻らない。本記事では、4つの表示の意味と旧表示「Claude usage limit reached. Your limit will reset at …」からの変遷、枠を最も食う4要因（モデル選択・コンテキストの大きさ・長時間連続セッション・サブエージェント/MCP）、上限到達時の5つの打ち手（Opus/Sonnet枠なら/modelで系統外へ・/compactで次の枠を長持ちさせる・リセットを待つ＝v2.1.234以降は自動再開・API従量へ切替・/usage-creditsで使用量クレジットやプラン昇格）、残量の見方（/usage・ステータスライン・設定→使用量）、似ているが別物の表示（Server is temporarily limiting requests・spend limit）、サブスク制限とAPI制限の違いまでを、公式ドキュメントをもとに整理する。具体的な枠の数値は時期で改定されるため断定は避ける。

Claude Codeの「Prompt is too long」は、履歴・ファイル・ツール結果などを含む入力の合計がコンテキスト上限を超えたときのエラー。長い履歴を圧縮する場合、最初の入力を減らす場合、認証など圧縮の根本エラーを直す場合を分けて説明する。MCPの定義は既定で遅延読み込みされ、1Mの利用条件はモデル・接続先・プランによって異なる。APIを直接使う場合のトークン計数と停止理由も整理。

Claude CodeでMCPサーバーが繋がらないときは、ステータス、接続方式、Issueの詳細を合わせて確認します。failedはstdioの起動失敗だけでなく、HTTPの通信失敗や固定認証ヘッダの拒否でも表示されます。この記事ではConnection closedの意味、環境変数と未定義変数の扱い、プロジェクト設定と承認、Windowsのnpx起動、デバッグログ、再接続後の操作確認までを説明します。ツールが0個でも異常とは限らず、単体起動だけではMCP接続の成功を保証しない点も整理します。

Claude Codeで長時間作業していると、突然「court」や生の<invoke name="Bash">タグが画面に漏れ、ツール呼び出しが実行されない——そんな現象に遭遇したことはないだろうか。これはあなたの環境やコマンドのミスではなく、Claude（特にOpus 4.8/4.7系）がツール呼び出しの制御タグを生成する瞬間に、まれにそのタグが壊れて出力されるモデル側の既知の不具合だ。Anthropic公式リポジトリにも多数のIssue（#64108, #64150, #64690, #65705, #66153, #67295, #68354）が立っている。本記事では、エージェントがツール呼び出しもテキストとして「生成」している仕組み、ハーネスがfail-closedで弾くため誤コマンドは走らない安全性、原因の2層構造（①制御トークンの生成破損＋②壊れたブロックが履歴に残ることでモデルが真似て連鎖する自己汚染）、誘発条件（長時間・複数日セッション、重いコンテキスト、/compact後、複数ツール同時、3+MCP、長いツール引数）、よくある3つの誤解（暴走ではない／courtに意味はないが目印／再試行で直るは軽症時のみ）、ユーザー向け対処（2回外したら新セッション/clearへ逃げる・/compactは不確実）、開発者向け対処（stop_reason確認・invoke混入検出リトライ・壊れた履歴を残さない・引数短縮）、似たエラー（thinking署名400・max_tokens切断・Bedrock第三者連携）との見分け方、2026年10月4日時点で公式修正が未提供である対応状況までを、公式ドキュメントと実Issueに基づいて完全解説する。

巨大なAIモデルを丸ごと学習し直すのは高すぎる、でも自分用に少しだけ調整したい、その願いを叶えるのがLoRA（Low-Rank Adaptation／低ランク適応）。元のモデルはそのまま凍結し、ごく小さな追加部品（アダプタ）だけを学習することで学習するパラメータを元のモデルの1%未満に減らす。LoRAはファインチューニングを劇的に安く速くする技術であり、Stable Diffusionなどの画像生成でキャラや画風を足す小さなファイルとしても大人気。本記事は仕組みをパッチ（あて布）のたとえで解説する。LoRAはパラメータ効率の良いファインチューニング（PEFT）の代表格で、核心は巨大な元の重みを一切変えず凍結し各層に小さな追加行列を差し込みそこだけ学習する（W = W₀ + BA、W₀は凍結、BAが小さな追加分）。AIの調整は実はそんなに大きく変える必要がない＝低ランクで足りるという仮説が土台で、原論文の実験が裏づけた（数学やプログラミングでは全体の学習に劣るとの報告もある）。メリットは学習パラメータが元の1%未満（原論文の GPT-3 175B で約1万分の1）・省メモリ高速安い（同じく学習時のGPUメモリ 1.2TB → 350GB）・推論はアダプタを統合すればレイテンシ増なし・元の力を忘れにくい。最大の強みはアダプタの付け替えで、土台共通のまま用途ごとに小さなLoRAを差し替え瞬時に切り替えられる。多くの人が最初に触れるのは画像生成で、Stable Diffusionでは特定キャラ・画風・被写体を覚えた小さなLoRAが無数に共有される（画風を足す、キャラを覚えさせる、軽く共有しやすい）。QLoRAは量子化と組み合わせ土台を4ビットに圧縮したままLoRAを学習し、16ビットで全部を学習すると780GB超が要る65Bのモデルを48GBのGPU 1枚で、33Bを24GBの家庭用GPUで微調整でき、論文の比較では16ビットの方式と同等の成績（33B・65Bで全体学習と並ぶかは未確認と論文自身が書く）。フルファインチューニング（全パラメータ学習）との違いは学習する重み・コスト・成果物・向く場面で、多くの実務ではまずLoRAで十分。土台はそのまま味付けは小さく、が要点。数値は原論文などの実験条件でのもので傾向の参考。

70B（700億パラメータ）の巨大モデルを手元のPC1台でも動かせる（家庭用GPUに収まらない分はCPUとメインメモリに任せる構成で）、それを可能にするのが量子化（quantization）。モデルの重みの数値精度を下げてサイズと必要メモリを劇的に小さくする技術で、モデル蒸留が別の小さいモデルに知識を移すのに対し量子化は同じモデルを軽くする。本記事は仕組みを写真の圧縮のたとえで解説する。量子化は重み（パラメータ）をFP16/FP32の小数からINT8（8ビット）やINT4（4ビット）の整数に置き換え、1重みあたりの容量を減らす（FP32=4バイト、INT8=1バイト、INT4=0.5バイト）。RAW写真をJPEGに圧縮するように少しの精度を犠牲に大きな軽さを得て、驚くのは失うものがこれほど少ないこと。どれだけ軽くなるかは、4ビット化でFP16比約1/4、70Bモデルは140GB→約35GB、8Bモデルは4ビットで約4.5〜5GBとミドルクラスGPU（VRAM 8GB）に収まりローカル実行できる＝LLMの民主化。精度はINT8でほぼ無損失、INT4でも一般的なQ&Aや常識タスクなら劣化4%未満との報告だが、数学・コード生成・難しい推論では低下が目立ちやすく用途に合うビット数を選ぶのが肝心（パープレキシティの微増として現れる）。主な手法はGPTQ（精度を保つ4ビット圧縮の先駆け）、AWQ（重要な約1%の重みを保護、GPTQとの優劣は評価で逆転）、GGUF（llama.cpp/Ollama形式でQ2_K〜Q8_0、CPU+GPU併用可、ローカル向け）、QLoRA（4ビット土台にLoRAで家庭用GPUでも微調整）。蒸留（別の小モデルに移す）・ファインチューニング（特定用途に追加学習）とは狙いが違い、組み合わせて使うのが普通（蒸留した小モデルをさらに量子化、量子化土台にFT等）。始め方はローカルならGGUF（Ollama）を1コマンド、VRAMに合わせてQ4/Q8を選び、コード生成や厳密計算ならINT4を避けINT8以上に。たいてい量子化済みモデルが配布されダウンロードして使うだけ。賢さはそのまま重さだけ落とす最も実用的な一手。数値は各種公表資料の引用で傾向の参考。

巨大で高性能なAIは賢いが重くて高い、その悩みを解くのがモデル蒸留（Knowledge Distillation）。大きな先生（teacher）モデルの知識を小さな生徒（student）モデルに移し、はるかに小さく速いまま先生に近い性能を保ついいとこ取りを狙う技術。本記事は仕組みを先生と生徒のたとえで解説する。カギはソフトラベルで、普通の学習が正解は猫とだけ教える（ハードラベル）のに対し蒸留は先生が出す90%猫8%犬2%キツネといった確率分布ごと生徒に渡し、その迷いの度合いに正解だけでは伝わらない豊かな情報が含まれる。さらに温度（Temperature）で確率をやわらかくし似たもの同士の微妙な関係まで見せる（実例：OpenAIは2024年、大モデルの出力で小モデルを鍛える蒸留機能をAPIに追加）。メリットは速くて安い・大幅に小型でも先生に近い性能（TinyBERTは約7.5分の1で96.8%以上）・エッジで動く・用途特化に強い。方式は先生の重みや内部表現にフルアクセスできるホワイトボックスと、出力（API応答）しか見えないブラックボックスの2つで、後者で他社APIを先生にすると規約違反になりうる。混同しやすい技術との違いは、蒸留＝別の小モデルに知識を移す、量子化＝同じモデルの重みの精度を下げて圧縮、ファインチューニング＝既存モデルを特定タスク向けに追加学習、で排他でなく組み合わせ可能。法的・規約の現実が2026年の大論点で、蒸留技術自体は正当だがOpenAI・Anthropic・xAI等の利用規約には自社出力を競合モデル開発に使うことを禁じる反蒸留条項があり、制限APIの出力を先生に競合を蒸留するのは技術的に可能でも規約違反になりうる。OpenAI対DeepSeekの係争（OpenAIはアクセス制限を回避し出力を蒸留した疑いと主張、一方DeepSeek規約は自社出力の蒸留利用を認めるとされる）やClaude Fable 5/Mythos 5で蒸留と判定されたリクエストを下位のOpusモデルに切り替える設計など緊張は継続。実務は使う先生モデルの規約を必ず確認し、自社・許諾OSSを先生にする、競合開発に当たらないか用途を慎重に判断するのが心得。賢さは大モデル運用は小モデルの両立を可能にするが先生に誰を選ぶかで技術的にも法的にも結果が変わる。数値・事例は各種公表資料・報道の引用で傾向の参考。

マルチエージェントの作り方で「増やす前に全ハンドオフを計測せよ」と書いた、その計測を本番で支える技術がAIオブザーバビリティ（可観測性）。LLMやエージェントが本番で実際に何をしているか（どのモデルをどんなプロンプトで呼び・どのツールや検索を使い・何を返し・何秒いくらかかったか）を記録し問題の原因まで遡れるようにする。普通のアプリ監視との決定的な違いは、AIは200 OK・50msで返しながら堂々と嘘（ハルシネーション）をつくことがある点で、AIの障害の多くはインフラ障害でなく品質障害（ハルシネーション・検索失敗・安全でない回答・タスク未完了・ツール誤用・プロンプト変更後の劣化）。オブザーバビリティは3本柱＝トレース（1リクエストの実行経路をスパンの木で記録・AI観測の主役）・メトリクス（レイテンシ/コスト/トークン/エラー率を数値集計）・ログ（個別イベントの詳細）で語られ、業界標準のOpenTelemetry GenAI規約がプロンプト・応答・トークン・ツール呼び出しをベンダー非依存スキーマで扱う。最も混同しやすい評価（Evals）との違いは、オブザーバビリティが何が起きたかを見る（計測は簡単だが答えの正しさは分からない）のに対し評価は答えの質が良いかを測る（明示的なEvalsが必要）こと。コストとレイテンシは簡単に測れるが答えの質は評価がないと分からないため2026年の主要ツールはトレース表示＋出力スコアリング＋劣化アラートを一体提供する。見るべきメトリクスは運用系（コスト・レイテンシ・トークン・エラー率）と品質系（ハルシネーション・根拠性groundedness＝RAGで最重要・安全性・タスク完了度）に分かれハルシネーション検知にはLLM-as-a-judge/意味的類似度/根拠性スコアを使う。主要ツールはLangSmith（LangChain系）・Langfuse（OSSセルフホスト）・Arize Phoenix（RAGデバッグ）・MLflow（ライフサイクル）・AgentOps（エージェント）・OpenTelemetry（標準規格）。始め方はトレース取得→運用メトリクス可視化→評価接続の順で本番前から入れること。とくにマルチエージェントでは失敗が多段の因果連鎖に隠れるためセッション全体のトレースが必須。観測＋評価の両輪で初めて本番品質。数値・特徴は各種公表資料の引用で傾向の参考。

マルチエージェントとは？で概念を押さえた次の実践編。まず単一エージェントで作り、限界にぶつかってから最小構成で増やすのが原則だ（Google Research の検証では、順を追う課題でマルチ構成がすべて単一より39〜70%悪化し、Anthropic はマルチエージェントがチャットの約15倍のトークンを使うと報告）。基本形はスーパーバイザー型（司令塔型）で、Claude Agent SDK ではサブエージェント、OpenAI Agents SDK では Agents as tools がこれに当たる。課題分解→ワーカー定義→司令塔設計→受け渡し→計測の5ステップに加え、両 SDK の公式ドキュメントに沿った最小コード（司令塔1体＋調査役・確認役）、役ごとの道具の絞り方、maxTurns・max_turns・費用の3重の上限、ハンドオフとの使い分け、良い分割と悪い分割、Anthropic が実際に経験した失敗例（単純な質問に50体、重複調査）と対策をまとめた。

AIエージェントが当たり前になり、次の課題はエージェント同士をどう連携させるかに移った。MCPがエージェントを道具につなぐ標準なら、A2A（Agent2Agent）はエージェントを別のエージェントにつなぐ標準。異なるベンダー・フレームワークで作られたAI同士が共通の作法で会話し協力できるようにする。Googleが2025年4月に公開し同年6月にLinux Foundationへ寄贈、2026年にv1.0へ到達。本記事は、正体（会社間の業務提携のたとえ）、なぜ必要か（計画→ホテル予約→決済のように専門エージェントがリレーで協力する時代）、MCPとの違い（MCPは縦＝エージェント↔ツール、A2Aは横＝エージェント↔エージェント、両方を重ねる2層構成が標準）、仕組み（Agent Card＝/.well-known/agent-card.jsonに置く能力の名刺で発見→Task＝依頼で進行中（working）・要入力（input-required）・完了（completed）などの状態→Artifact＝結果。HTTP・SSE・JSON-RPC 2.0の上に作られ、各エージェントは内部を隠したまま安全に協力）、現状と実装（2026年4月時点で150超の組織が支持・GitHubスター22,000超・5言語SDK＝Python/JavaScript/Java/Go/.NET、Microsoft・Salesforce・SAP・ServiceNow等が参加）までを初心者向けに解説。道具につなぐ＝MCP、仲間につなぐ＝A2Aが覚え方。