AI初心者ガイド｜ゼロから始めるAI入門

Claude Codeをインストールしたのにターミナルで「zsh: command not found: claude」「bash: claude: command not found」「is not recognized as an internal or external command(Windows)」が出る——これは多くの場合インストール先のフォルダがPATHに入っていないだけで、インストール自体は成功している。本記事では、シェルがPATH上のフォルダを順に探す仕組み、インストール方法と置き場所(ネイティブインストーラ推奨=~/.local/bin・Windowsは%USERPROFILE%\.local\bin/npmはNode18+で同じネイティブバイナリ/Homebrew/WinGet、VS Code拡張だけではclaudeはPATHに入らない)、主な原因と対処(PATHに~/.local/binを追加して端末再起動、npm権限エラーEACCESはsudoせずネイティブへ、Nodeが古い、複数インストールの衝突はwhich -a/where.exeで確認しネイティブ1本に、optional依存スキップでネイティブバイナリ不明)、Windows特有の罠(irmをCMDで等のシェル取り違え・端末再起動・古いClaude DesktopのWindowsApps Claude.exe衝突・Git BashのCLAUDE_CODE_GIT_BASH_PATH)、自動更新と更新系(claude update/claude install/claude doctorで成否確認/DISABLE_AUTOUPDATER・DISABLE_UPDATES)、切り分けワークフロー(claude doctor→which -a→PATH追加→余計な版を削除→ネイティブ入れ直し)までを、公式情報に基づいて整理する。

会社のPCやVPN越しでClaude Codeが「Unable to connect to API」「Unable to connect to API (ECONNREFUSED)」「SSL certificate verification failed」「fetch failed」で繋がらない——これらはリクエストがAnthropicのサーバ(api.anthropic.com)まで届いていないネットワーク系エラーで、認証(401/403)・サーバ過負荷(529/500)・レート制限(429)とは別物だ。本記事では、企業ネットワークで詰まる3層(プロキシ未設定・TLS検査による証明書差し替え・ファイアウォールのドメイン遮断)とDNS/VPN/Docker、プロキシ設定(HTTPS_PROXY/HTTP_PROXY/NO_PROXY、認証付きプロキシ、SOCKS非対応、NTLM/KerberosはLLMゲートウェイ＋ANTHROPIC_BASE_URL、MCPサーバは各envに明示)、TLSと社内CA証明書(近年は同梱CA＋OSトラストストアの両方を信頼しOSストアにあれば設定不要、無ければNODE_EXTRA_CA_CERTSにPEMを指定、mTLSはCLAUDE_CODE_CLIENT_CERT/KEY、インストール時はcurl --cacert)、絶対にやってはいけないNODE_TLS_REJECT_UNAUTHORIZED=0(全通信が中間者攻撃に晒される)、ファイアウォールの許可ドメイン(api.anthropic.com/claude.ai/platform.claude.com/downloads.claude.ai/raw.githubusercontent.com、statsig/sentryは任意)、切り分けワークフロー(curl -I https://api.anthropic.comで到達確認→/doctorとプロキシ確認→証明書/プロキシ設定→直接接続で確定→DNS/VPN/Docker)、認証・サーバ・レートとの区別までを、公式情報に基づいて整理する。

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の型付き例外と自動リトライ・指数バックオフ＋ジッター・retry-afterは429のみ・--fallback-model・Priority Tier/Batch）、一時的スパイクか継続インシデントかの見分けまでを、公式情報に基づいて整理する。

Claude Codeで作業中に突然「Claude usage limit reached. Your limit will reset at 3pm」と出て手が止まる——これはエラーやバグではなく、サブスク（Pro/Max）の使用量制限の仕様だ。本記事では、制限の二層構造（最初のプロンプトから約5時間で回復する5時間ローリング枠＋7日ごとにリセットする週次枠＋MaxにはOpus専用の週次枠）、Claude CodeとClaudeアプリが同じプランの枠を共有すること、消費を最も食う4要因（モデル選択=Opusが桁違い・コンテキストの大きさ・長時間連続セッション・サブエージェント/MCP）、上限到達時に今すぐ動かす5つの選択肢（/modelでSonnetに下げる・/compactで文脈を削る・5時間枠ならリセットを待つ・API従量課金へ切替・使用量クレジット購入やプラン昇格）、残量の見方（/usage・/status・設定→使用量で週次リセット日を確認）、サブスク制限とAPI制限（429・retry-after・Tier）の違いまでを、公式情報をもとに整理する。なお具体的な枠の数値は時期で改定されるため断定を避け、最新の公式表示で確認することを推奨する。

Claude CodeやAPIで突然出る「Prompt is too long」（API では「prompt is too long: 233153 tokens > 200000 maximum」）——これは使用量制限ではなく、送ろうとした入力（会話履歴＋添付/読み込んだファイル＋ツール定義など）がモデルのコンテキスト窓を超えたという意味だ。本記事では、コンテキスト窓を埋める要因（増え続ける会話履歴・読み込んだファイル・ツール結果という動的要因と、MCPツール定義・CLAUDE.md・システムプロンプトという固定要因）、Claude Codeが既定でauto-compact（自動要約）して回避していること、窓のサイズ（標準200Kと1M、1Mは2026年時点で標準価格だがサブスクではクレジットが必要な場合・新トークナイザで約30〜35%多く消費する注意）、今すぐ直す手順（/compactで要約・/clearで作り直し・巨大な読み込みは別の窓を持つサブエージェントに逃がす・/contextで内訳確認し不要MCP無効化やCLAUDE.md圧縮・本当に大きい時だけ1Mモデル）、紛らわしい3つ（Prompt is too long=入力超過／max_tokens=出力切断／usage limit=プラン枠／1M credits=権限）の見分け方までを、公式情報に基づいて整理する。

Claude CodeでMCP（Model Context Protocol）サーバーを設定したのに、/mcpを開くとfailedやneeds authentication、pending approvalで止まっている——MCP接続は意外と詰まりやすい。本記事ではまず/mcp（やclaude mcp list）のステータスで原因を3系統に分類する方法（✓ connected/✗ failed=ローカル起動失敗/△ needs authentication=リモート認証/⏸ pending approval=プロジェクト承認待ち、connectedなのにツール0の状態）、failed・設定系の主因と対処（相対パス→絶対パス、サーバ用APIキーはサーバごとのenvに書く・settings.jsonのenvは伝わらない、MCP_TIMEOUTでの起動タイムアウト、.mcp.jsonはリポジトリ直下・未定義の${VAR}で解析失敗、stdoutにログを書くとプロトコルが壊れる）、Windowsで最頻出のnpx問題（spawn npx ENOENT→commandをcmdにして/c npxでラップ、またはWSL）、リモートのOAuth認証（401/403→/mcpから認証、Microsoft 365/Gmail等はclaude.aiのコネクタ側で接続）、切り分けワークフロー（/mcpでステータス→claude --debug mcpでstderr→サーバ単体起動→MCP Inspector→Desktopは完全再起動）、再発防止チェックリストまでを、公式情報に基づいて整理する。

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年6月時点で公式修正が未提供である対応状況までを、公式ドキュメントと実Issueに基づいて完全解説する。

ある日突然ChatGPTやClaudeのアカウントが使えなくなる、2026年こうしたアカウント停止（BAN）・警告の報告が増えている。怖いのは悪意がなくても規約をうっかり破ってBANされるケースがあること。本記事はOpenAI（ChatGPT・Codex）とAnthropic（Claude・Claude Code）でアカウントを失わないために知るべきことを公開規約・報道をもとに整理する（検知をすり抜ける裏ワザではなく規約を正しく守って使い続けるための実践ガイド）。両社共通のBANトリガーは5つ＝①禁止コンテンツ・脱獄（違法有害生成や安全フィルターのプロンプト突破、重大違反は一発永久停止も）②無断の自動化・スクレイピング（ボットやスパム・フィッシング）③アカウント・APIキーの共有/転売④不審なアクセスパターン（短期間の頻繁なIP/国変更・VPN多用・端末切替で異常ログイン判定）⑤決済の不一致・不正（登録地と決済地のズレ・不審な支払い）。2026年最大の落とし穴は、Claude個人向けプラン（Free/Pro/Max）のOAuthトークンを公式アプリ以外の第三者ツール・サービス（Agent SDK含むハーネス）で使うことがConsumer利用規約違反とされ大規模BAN波の主因になったこと。正しくはアプリ・エージェントはAPI（従量課金）、個人プランは公式アプリでの対話用と割り切る。OpenAIで特に注意は安全フィルター/アクセス制限の回避・自動化スクレイピング・APIキー流用・違法有害用途。Anthropicで特に注意はOAuthトークンの第三者利用・非公式クライアント・反蒸留/競合モデル条項・脱獄。BAN回避チェックリスト7点（規約を読む／用途にあうプラン／個人トークンを第三者ツールに入れない／脱獄禁止コンテンツに手を出さない／共有転売しない／登録地一致の決済と安定アクセス／警告が来たら即見直す）。警告は直す機会で多くは是正で継続でき、軽微偶発の違反は異議申し立て可能だが重大違反は永久停止で復旧困難。正しいプランを正しい用途で正直に、が要点。各社の最新公式規約を必ず確認すること。

巨大なAIモデルを丸ごと学習し直すのは高すぎる、でも自分用に少しだけ調整したい、その願いを叶えるのがLoRA（Low-Rank Adaptation／低ランク適応）。元のモデルはそのまま凍結し、ごく小さな追加部品（アダプタ）だけを学習することで学習するパラメータを約90%減らす。LoRAはファインチューニングを劇的に安く速くする技術であり、Stable Diffusionなどの画像生成でキャラや画風を足す小さなファイルとしても大人気。本記事は仕組みをパッチ（あて布）のたとえで解説する。LoRAはパラメータ効率の良いファインチューニング（PEFT）の代表格で、核心は巨大な元の重みを一切変えず凍結し各層に小さな追加行列を差し込みそこだけ学習する（W = W₀ + BA、W₀は凍結、BAが小さな追加分）。AIの調整は実はそんなに大きく変える必要がない＝低ランクで足りるという発見が土台。メリットは学習パラメータ約90%減（GPT-3規模で従来比1万分の1との報告）・省メモリ高速安い（GPU記憶約3分の1）・推論はアダプタを統合すればレイテンシ増なし・過学習しにくい。最大の強みはアダプタの付け替えで、土台共通のまま用途ごとに数MBのLoRAを差し替え瞬時に切り替えられる。多くの人が最初に触れるのは画像生成で、Stable Diffusionでは特定キャラ・画風・被写体を覚えた小さなLoRAが無数に共有される（画風を足す、キャラを覚えさせる、軽く共有しやすい）。QLoRAは量子化と組み合わせ土台を4ビットに圧縮したままLoRAを学習し、標準LoRAよりさらにメモリ約4分の1、家庭用GPU（場合によりCPU）でも巨大モデルを微調整でき精度低下もごくわずか。フルファインチューニング（全パラメータ学習）との違いは学習する重み・コスト・成果物・向く場面で、多くの実務ではまずLoRAで十分。土台はそのまま味付けは小さく、が要点。数値は各種公表資料の引用で傾向の参考。

70B（700億パラメータ）の巨大モデルが手元のゲーミングPC1台で動く、それを可能にするのが量子化（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より1〜2%高精度＋高速）、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）モデルに移し、10分の1のサイズ・速度で先生の性能の95%以上を保ついいとこ取りを狙う技術。本記事は仕組みを先生と生徒のたとえで解説する。カギはソフトラベルで、普通の学習が正解は猫とだけ教える（ハードラベル）のに対し蒸留は先生が出す90%猫8%犬2%キツネといった確率分布ごと生徒に渡し、その迷いの度合いに正解だけでは伝わらない豊かな情報が含まれる。さらに温度（Temperature）で確率をやわらかくし似たもの同士の微妙な関係まで見せる（実例：GPT-4o miniがGPT-4oから蒸留）。メリットは速くて安い・約10倍コンパクトで性能95%以上維持・エッジで動く・用途特化に強い。方式は先生の重みや内部表現にフルアクセスできるホワイトボックスと、出力（API応答）しか見えないブラックボックスの2つで、後者で他社APIを先生にすると規約違反になりうる。混同しやすい技術との違いは、蒸留＝別の小モデルに知識を移す、量子化＝同じモデルの重みの精度を下げて圧縮、ファインチューニング＝既存モデルを特定タスク向けに追加学習、で排他でなく組み合わせ可能。法的・規約の現実が2026年の大論点で、蒸留技術自体は正当だがOpenAI・Anthropic・Mistral・xAI等の利用規約には自社出力を競合モデル開発に使うことを禁じる反蒸留条項があり、制限APIの出力を先生に競合を蒸留するのは技術的に可能でも規約違反になりうる。OpenAI対DeepSeekの係争（OpenAIはアクセス制限を回避し出力を蒸留した疑いと主張、一方DeepSeek規約は自社出力の蒸留利用を認めるとされる）やClaude Fable 5/Mythos 5で蒸留判定の作業が制限される設計など緊張は継続。実務は使う先生モデルの規約を必ず確認し、自社・許諾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（標準規格）。始め方はトレース取得→運用メトリクス可視化→評価接続の順で本番前から入れること。とくにマルチエージェントでは失敗が多段の因果連鎖に隠れるためセッション全体のトレースが必須。観測＋評価の両輪で初めて本番品質。数値・特徴は各種公表資料の引用で傾向の参考。