Claudeの長時間タスクをtests.jsonとprogress.txtで管理する
複数のコンテキストウィンドウをまたぐClaudeの長時間タスクを、tests.jsonとprogress.txtで状態管理する具体的な手順とプロンプト例をまとめます。
カテゴリ
Agent SDKの記事一覧
Agent SDKは、Claudeを使って自律的に動くエージェントを構築するためのAnthropic公式SDKです。
はじめての方へ:Agent SDKクイックスタート211件の記事 · 最終更新 2026/09/23
全記事一覧
Claude Sonnet 5は指示を文字通り解釈し、範囲を広げない
Claude Sonnet 5は指示を一般化せず文字通り実行します。effortとの関係、範囲を明示する書き方とコードレビューでの影響をまとめます。
Claudeに破壊的操作を確認させるプロンプト設計
公式プロンプトエンジニアリングガイドの「reversibility」原則に基づき、破壊的操作の前にClaudeへ確認を求めさせるプロンプトの書き方と、権限システムとの役割の違いを示します。
Agent Skillsの効果をSkillsBenchが実測 — 最適は3モジュール以下
Agent Skillsは本当にタスク成功率を上げるのか。87タスクの検証結果、モジュール数と複雑さの影響、逆効果になった13タスクの共通パターンを一次データで確認します。
claude-agent-sdkのwheelが公開されず、pip installに失敗する原因と対処法
claude-agent-sdkのPyPI公開が一部失敗しwheelが欠けると、pip installはプラットフォームエラーで止まります。2026年3月の実際の障害と、9月にも起きた再発、切り分け手順をまとめました。
Claude Agent SDKで(no content)テキストが出る原因と対処法
Claude Agent SDKのstreaming inputモードでthinkingブロックの前に(no content)という空テキストが混入する不具合の原因・修正バージョン・防御的な実装をまとめます。
大きいメッセージでJSONDecodeErrorが発生し停止する原因と対処
Python版Claude Agent SDKで大きな応答時にCLIJSONDecodeErrorが起きる原因と、現行SDKでのmax_buffer_size対処をまとめます。
MCP_TOOL_TIMEOUTを設定しても5分で切れるAgent SDKのMCPツール呼び出し
Agent SDK TypeScriptでMCP_TOOL_TIMEOUTを伸ばしてもMCPツール呼び出しが5分で失敗する既知報告と、原因が一致する公式修正、確認しておきたい設定をまとめます。
Fable 5.1のxhigh/maxでmax_tokensに達し出力が切れる問題と対処
Claude Fable 5.1をxhigh・maxのeffortで使うと、モデルが思考内で下書きしてから本文を書き直すためmax_tokensに達し出力が切れることがあります。原因と対処法をまとめます。
Claude Fable 5.1のサブエージェント並行作業でリードを待たせない設計
起動ツールの即時リターン・結果の後続メッセージ投入・待機専用ツールの3点で、Claude Fable 5.1のリードエージェントはサブエージェント実行中も動かし続けられます。
Claude Fable 5.1の保持指示でcompactionの要約を書く方法
Claude Fable 5.1はクライアント側でcompactionを自前実装すると、制約や決定事項を要約から落としやすくなります。公式が示す保持指示の全文と、単純圧縮を選ぶ理由をまとめました。
「SDK execution error」でclaude-code-actionが落ちる原因と対処法
claude-code-actionがAPI呼び出し前に「SDK execution error」でexit code 1停止する原因と、確認された対処法をまとめます。
Browser Use Toolの座標指定 — refと座標クリックの使い分け
Browser use toolのTargetはCoordinateTargetとRefTargetの2方式です。使い分けの基準と参照が無効になる条件を公式仕様から解説します。
Browser use toolのセキュリティ対策6原則 — プロンプトインジェクション対応
Browser use toolはページの内容がそのままClaudeへの入力になります。プロンプトインジェクション対策として公式が挙げる6つの防御策を、実装観点でまとめます。
Browser use toolを有効化 — javascript_exec/file_uploadの設定とリスク
Browser use toolのjavascript_exec・file_upload・read_console・read_networkは既定で無効です。configsでの有効化手順と、有効化前に満たすべき実装条件をまとめます。
browser use toolのbrowser_stateでタブ管理を実装する
Browser use toolのnew_tab・list_tabs・switch_tab・close_tabとbrowser_stateブロックの入出力仕様、ダウンロード報告の実装手順をまとめます。
Browser Useツールの実装 — navigateとread_pageの使い方
Browser Useツール(browser_toolset_20260801)のnavigate/read_pageをMessages APIから直接呼ぶ実装の要点。アクセシビリティツリーとref参照、エラー処理までを解説します。
only prompt commands are supported in streaming modeエラーの原因
Agent SDKで非同期サブエージェントを動かすと起きていたエラーの原因と、修正済みバージョンをまとめます。
Agent SDK Skillsが検出されないときの切り分け手順
設定を確認したはずのAgent SDKでSkillsが検出されないとき、バージョン・settingSources・cwd・許可リストの4点を順に切り分ける手順です。
Claude Agent SDKがLinuxでmusl版バイナリを優先するバグの原因と対処
TypeScript Agent SDKがLinuxでネイティブバイナリを自動選択する際、glibc環境でもmusl版を先に試して失敗する既知バグの原因と回避策をまとめます。
ant applyのkind推論とagentを初めて適用する手順
ant applyはファイルの置き場所からagentやenvironmentなどのkindを自動推論します。最初のagentファイルを書いて適用し、承認までの流れを確認します。
StructuredOutputがoutputキーに包まれるバグと回避策
claude-agent-sdk-pythonのStructuredOutputツールが応答をoutputキーで包み、スキーマ検証が失敗する既知のバグの実態と回避策を解説します。
rate_limit_eventでMessageParseErrorが発生し停止する原因と対処
Python版Claude Agent SDKがrate_limit_eventでMessageParseErrorを起こしreceive_messages()が停止する既知バグの原因と対処をまとめます。
ClaudeCodeOptionsのcwdが反映されない理由と回避策 — Python Agent SDK
claude-agent-sdk-pythonのissueが報告し続けるcwd無視の症状を公式ドキュメントの仕様から読み解き、回避策と症状別の見分け方を示します。
MCP Stream closedエラーはAgent SDKの並列呼び出しで起きる
Agent SDKのcreateSdkMcpServerで複数ツールを同時に呼ぶとStream closedで失敗する既知バグの原因と、環境変数による回避策をGitHub issueの一次情報から解説します。
Agent SDKがDockerのDEBUG環境変数で動かなくなる原因と回避策
Docker環境でDEBUG環境変数を設定すると、Python版Agent SDKがCLIからの応答を受け取れなくなる既知の不具合を解説します。原因と回避策、TypeScript SDKとの挙動の違いをまとめます。
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSとは — サブエージェントのストール検知の設定
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSは、進捗のないサブエージェントを強制終了する環境変数です。既定値の連動先、中断後の挙動、他の制御との使い分けをまとめます。
MCPのツール定義はなぜコンテキストを圧迫するのか — Tool Searchが必要になった理由
MCPサーバーを増やすほどツール定義がコンテキストを消費します。公式ドキュメントの実測値をもとに、その仕組みとTool Searchが解決する範囲を説明します。
Claude Codeサブエージェントのモデル配分設計 — 役割ごとにOpus/Sonnet/Haikuを割り当てる
サブエージェントを全部同じモデルで動かすとコストと精度が釣り合わない。公式ドキュメントのmodelフィールドと料金表から、役割別の割り当て原則を導く。
Compaction blocksを会話に戻す実装パターン
Claude APIのcompactionが返すcompactionブロックは、次のリクエストへ積み戻さないと会話が続きません。基本の実装手順とストリーミング時の扱いまで示します。
Agent SDKは、ツールの接続、エージェントのループ制御、コンテキスト管理、長時間稼働の設計といった、エージェント実装の土台を提供します。
このカテゴリでは、SDKの基本構造から、評価(eval)の設計、マルチエージェント構成、運用上の工夫まで、Claudeでエージェントを作る開発者向けの情報を扱います。
Agent SDKでエージェントを実装する際は、ツール接続やループ制御といった「仕組み」だけでなく、評価(eval)とコンテキスト管理という「運用」の設計が成否を分けます。長時間稼働や複数エージェントの協調を前提にすると、最初の設計段階で何を計測し、どこで人が介在するかを決めておくことが重要です。
外部ツールとの接続にはMCP、対話的にエージェントを動かす現場ではClaude Codeのカテゴリが関連します。SDKの基礎を押さえたうえで、これらと組み合わせると実運用に近づきます。