claude-code-agent

Claude Code Agent

Claude Code CLI を使って、タスクを独立した Claude Code セッションに委任して実行します。

claude -p は Claude Code Agent SDK の CLI エントリーポイントと考えることができます。旧ドキュメントでは headless mode と呼ばれることがありますが、動作は現在の -p エントリーポイントと同じ機能ラインです。

前提条件

1. Claude Code CLI をインストールします：npm install -g @anthropic-ai/claude-code
2. 認証が完了していることを確認します：claude auth login
3. claude auth status --text で現在のログイン状態をすばやく確認できます
4. 先に対象プロジェクトのディレクトリへ移動してから実行することをおすすめします。自動化で呼び出す場合は、デフォルトで claude -p を使用します

呼び出し方法

新しいセッション（デフォルト）

claude -p "你的任务描述" --output-format json --permission-mode bypassPermissions --model <flagship> --effort high

単一の JSON オブジェクトを返します。よく使うフィールドは次のとおりです。

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "回复内容",
  "session_id": "81a5f75b-...",
  "total_cost_usd": 0.0944715,
  "usage": { "input_tokens": 3, "output_tokens": 4 }
}

• session_id からセッション ID を抽出し、後続の複数ターンの会話に使用します
• result から Claude の最終応答を抽出します
• is_error、subtype、usage、total_cost_usd を使ってエラーの有無を判断し、コストを記録します
• --json-schema も渡した場合、実際にスキーマの制約を受けた結果は structured_output フィールドにあります。result が空になることがあるため、構造化された結果として読み取らないでください

イベントストリーム出力（stream-json）

claude -p "你的任务描述" --output-format stream-json --verbose --model <workhorse> --effort medium

stream-json には --verbose が必須です。指定しないと CLI はエラーを返します。現在よく使われるイベントは次のとおりです。

{"type":"system","subtype":"init","session_id":"bb6067a9-..."}
{"type":"assistant","message":{"content":[{"type":"text","text":"OK"}]}}
{"type":"result","subtype":"success","result":"OK","session_id":"bb6067a9-..."}

• 自動化スクリプトでは通常、最後の type == "result" を最終結果として扱います
• type == "assistant" は完了後の応答全体を取得するのに適していますが、安定した途中増分の取得方法ではありません
• system／hook／rate-limit イベントは通常のノイズです。最終回答として扱わないでください
• system/init には model、tools、plugins、plugin_errors などの起動メタデータが含まれます。プラグインが実際に読み込まれたかを検証するスクリプトでは、このイベントが最も役立ちます

トークン単位の増分テキストが必要な場合は、--include-partial-messages を追加し、type == "stream_event" かつ event.delta.type == "text_delta" のイベントを解析します。

指定したセッションを続行

claude -p "后续提问" --output-format json --model <workhorse> --effort medium --resume "session_id"

直近のセッションを続行（ショートカット）

claude -p "后续提问" --output-format json --model <workhorse> --effort medium --continue

• --continue は現在のディレクトリで直近に行われたセッションを自動的に再開します
• 明確な session_id をすでに保存している場合や、より安定したスクリプト動作が必要な場合は、--resume を優先してください

パイプ入力／stdin

cat logs.txt | claude -p "Explain the failure in these logs" --output-format json --model <workhorse> --effort low

• ログ、長文、生成途中の成果物を子 Claude Code に直接渡すのに適しています
• 上位ツール自体が stream-json を出力する場合は、--input-format stream-json の併用を検討してください

⚠️ --no-session-persistence：セッションを復元できません

--no-session-persistence を追加すると、このセッションはディスクに書き込まれないため、後から --resume や --continue で復元できません。次のような場面に限って使用してください。

• 追加の質問をしないと決まっている、一度限りの簡単な質疑応答
• セッション一覧を汚さないようにする、CI／スクリプトでの一時的な呼び出し
• ローカルに記録を残したくない、機密性の高いタスク

後から質問する可能性が少しでもある場合は、--no-session-persistence を追加しないでください。

claude CLI パラメーター

出力と結果

フラグ	説明
-p, --print	非対話モードです。json／stream-json の出力には必須です
--output-format FORMAT	text（デフォルト）／json／stream-json
--verbose	詳細モードを有効にします。stream-json では必須です
--include-partial-messages	stream-json に部分メッセージのチャンクを出力します
--include-hook-events	stream-json に hook のライフサイクルイベント全体を含めます
--json-schema SCHEMA	JSON Schema で構造化出力を制約します

セッション管理

フラグ	説明
-r, --resume SESSION_OR_NAME	指定したセッション ID またはセッション名を復元します
-c, --continue	現在のディレクトリの直近のセッションを復元します
--fork-session	resume／continue の際に、新しいセッションとして分岐します
--from-pr NUMBER	指定した PR に関連付けられたセッションを復元します
--session-id UUID	セッション ID を明示的に指定します
-n, --name NAME	セッションの表示名を設定します。後で --resume <name> を使用できます
--no-session-persistence	セッションを永続化しません

入力とストリーミング連携

フラグ	説明
--input-format FORMAT	text（デフォルト）／stream-json。プログラムから上流入力を渡す場合に使用します
--replay-user-messages	stream-json 入力モードで、ユーザーメッセージを stdout に再生します
--permission-prompt-tool TOOL	非対話モードで、権限確認を指定した MCP ツールに委任します

権限とツールの範囲

フラグ	説明
--permission-mode MODE	default／acceptEdits／plan／auto／dontAsk／bypassPermissions
--allowedTools TOOLS	"Read,Grep,Glob,Bash(git *)" のように、特定のツールを許可リストに追加します
--disallowedTools TOOLS	特定のツールを無効にします
--tools TOOLS	使用可能なツールセットを指定します。"" はすべて無効にし、"default" はすべて使用します
--dangerously-skip-permissions	すべての権限チェックを直接スキップします。非常に高いリスクがあります
--allow-dangerously-skip-permissions	セッションで「権限チェックをスキップ」を選択可能なモードとして有効にできるようにします

acceptEdits は、「ファイルへの書き込みは許可するが、すべての Bash／ネットワーク機能を一律に開放したくない」スクリプトによる修正に適しています。dontAsk は、厳しく制限された CI に適しています。許可リストにない操作や読み取り専用コマンドセット以外の操作は、対話型の確認に進まず、直接失敗します。

モデルとコンテキスト

フラグ	説明
--model MODEL	モデルを指定します。明示的に渡すことをおすすめします
--effort LEVEL	思考の強度：low／medium／high／xhigh／max
--max-turns N	エージェント型ターン数を制限します。自動化の子セッションに上限を設ける場合に使用します
--max-budget-usd AMOUNT	最大費用を制限します
--fallback-model MODEL	--print モードで過負荷になった場合に自動的に切り替えるモデルです
--system-prompt PROMPT	デフォルトのシステムプロンプトを置き換えます
--append-system-prompt PROMPT	システムプロンプトを追加します
--system-prompt-file FILE	ファイルからシステムプロンプトを読み込みます
--append-system-prompt-file FILE	ファイルからシステムプロンプトを追加します
--exclude-dynamic-system-prompt-sections	cwd／環境／git の状態などの動的情報をシステムプロンプトから除外し、マシン間でのキャッシュ再利用を向上させます
--add-dir DIR	追加でアクセス可能なディレクトリを追加します
--mcp-config CONFIG	MCP 設定（ファイルまたは JSON 文字列）を読み込みます
--settings FILE_OR_JSON	追加の settings を読み込みます

运行环境

Flag	说明
-w, --worktree [NAME]	为该任务创建隔离 worktree
--tmux	配合 --worktree 创建 tmux / iTerm pane 会话
--bare	scripted / SDK 推荐的 clean-room 模式：跳过 hooks、skills、plugins、MCP、auto memory 和 CLAUDE.md 自动发现
--disable-slash-commands	禁用所有 skills / slash commands
--agent AGENT	指定当前会话使用的 agent
--agents JSON	注入自定义 agents 定义
--plugin-dir PATH	为当前会话额外加载 plugin 目录
--chrome / --no-chrome	打开或关闭 Claude in Chrome 集成

--bare 下只会应用你显式传入的 flags；它不会读取本地 OAuth / keychain。需要 Anthropic 鉴权时，通常改用 ANTHROPIC_API_KEY 或在 --settings 里提供 apiKeyHelper。

多轮对话

1. 首次 claude -p ... --output-format json 获取 session_id
2. 后续追问用 claude -p ... --resume "session_id"，或在同目录用 --continue
3. 自动跟踪 session_id，用户无需手动理解完整协议
4. 不同任务各自新建会话；多个 session_id 互不干扰

模型与 effort 选择

根据任务复杂度显式指定 --model 和 --effort：

任务复杂度	model	effort	适用场景
高	<flagship>	high	架构设计、复杂重构、多文件编码
中	<workhorse>	medium	单文件功能实现、bug 修复、一般分析
低	<workhorse>	low	简单问答、代码解释、快速续问

文档里的 <flagship> / <workhorse> 是占位符，不是真实模型 ID。档位在分派时按平台当前模型梯队解析，不要写死模型名——模型代际更替时档位语义不变：flagship → 平台当前最强推理模型；workhorse → 比 flagship 低一档、性价比更高的模型。实际值用 claude --help 或平台公告里的当前别名（如 fable / opus / sonnet）替换。

推荐参数组合

场景	model	effort	permission-mode	其他 flags
复杂编码	<flagship>	high	bypassPermissions	--output-format json
一般编码	<workhorse>	medium	bypassPermissions	--output-format json
脚本化小修复	<workhorse>	medium	acceptEdits	--bare --allowedTools "Bash,Read,Edit"
代码审查	<workhorse>	medium	plan	--allowedTools "Read,Grep,Glob,Bash(git *)"
锁死的 CI 检查	<workhorse>	medium	dontAsk	--bare --allowedTools "Read,Grep,Glob"
快速问答	<workhorse>	low	default	--no-session-persistence（⚠️ 不可恢复）
工具链消费事件流	<workhorse>	medium	视任务而定	--output-format stream-json --verbose
有边界的自动化子会话	<workhorse>	medium	视任务而定	--max-turns 3 --max-budget-usd 1
干净子进程 / prompt 实验	<workhorse>	medium	default 或 plan	--bare
结构化输出	<workhorse>	medium	default	--json-schema schema.json
隔离执行	<flagship>	high	bypassPermissions	--worktree feature-x

使用规则

1. 自动化调用默认用 -p + --output-format json：拿稳定的单对象结果；只有确实需要事件流时再切 stream-json
2. stream-json 一律配 --verbose：这是 CLI 的硬约束，不是建议
3. 始终显式传 --model 和 --effort：避免默认值漂移
4. 始终在目标项目目录运行：先 cd /path/to/project，不要让 Claude 在错误仓库执行
5. 编码任务用 bypassPermissions，审查任务用 plan + 工具白名单：plan 不是硬沙箱，仍要配 --allowedTools
6. 保持对话连续：只要后续可能追问，就不要加 --no-session-persistence
7. --continue 适合“继续刚才那个任务”；需要可追踪脚本行为、跨目录稳定性或明确会话绑定时，用 --resume
8. 需要隔离修改时优先 --worktree：比手工切目录更稳，也更适合子 agent 独立执行
9. 向用户报告结果时优先取 result 字段：必要时再补 session_id、成本和 token 使用
10. 如果只允许读，不要只依赖提示词：同时加 plan、工具白名单或 --tools 限制，避免子进程意外写文件
11. 需要更可控的自动化边界时，加 --max-turns：避免子会话在模糊任务里跑得过深
12. scripted / SDK 调用默认优先 --bare：这样不会继承本地 CLAUDE.md、skills、plugins、MCP 和 auto memory，结果也更可复现
13. -p 模式里不要依赖 /commit 之类交互式 slash commands：直接用自然语言描述任务；必要时显式给 --append-system-prompt、--allowedTools 或 --json-schema

Prompt References

按任务类型按需加载对应 reference，不要把所有默认 prompt 一次性塞进主上下文：

• 编码 / 诊断 / 规划 / 窄修复：读 references/task-prompt-recipes.md
• 代码审查 / 挑战式审查 / 测试缺口检查：读 references/review-prompt-recipes.md
• 委派 handoff / 独立 worker / 续接同一 session：读 references/delegation-prompt-recipes.md

这些 reference 提供的是可直接复用或轻改的默认 prompt 模板；优先复制最接近的模板，再删掉不需要的块。

示例

编码任务

cd /path/to/project && claude -p \
  "Implement a REST API for TODO items with CRUD endpoints. Use Express.js." \
  --output-format json \
  --permission-mode bypassPermissions \
  --model <flagship> \
  --effort high

返回的 result 是自然语言总结，session_id 用于后续追问。

继续最近会话

cd /path/to/project && claude -p \
  "Continue from the current state. Add unit tests for the new endpoints and report only the final outcome." \
  --output-format json \
  --model <workhorse> \
  --effort medium \
  --continue

适合“刚才那个任务继续做”，不想手动保存 session_id 的场景。

事件流输出给上层工具

cd /path/to/project && claude -p \
  "Review the current diff and stream back progress plus a final verdict." \
  --output-format stream-json \
  --verbose \
  --permission-mode plan \
  --allowedTools "Read,Grep,Glob,Bash(git *)" \
  --model <workhorse> \
  --effort medium

适合上层 agent 或脚本：中间读 assistant / system 事件，最后读 result。

流式抽取纯文本增量

claude -p "Write a short changelog entry" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

适合你自己的上层 UI 或脚本只想吃连续文本 token，不想自己处理整条事件流。

管道输入日志或长文本

cat logs.txt | claude -p \
  "Explain the failure in these logs. Return root cause, evidence, and the smallest safe next step." \
  --output-format json \
  --model <workhorse> \
  --effort low

适合把父进程已经拿到的大段上下文直接流给子 Claude Code，而不是再落成临时 prompt。

结构化输出给另一个工具

claude -p \
  "Extract the main exported function names from src/auth.ts." \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' | \
  jq '.structured_output'

适合上层 agent、CI 或脚本只消费结构化字段；注意真正受 schema 约束的结果在 structured_output，不是 result。

代码审查

cd /path/to/project && claude -p \
  "Review git diff HEAD~1. Focus on correctness, regression risk, and missing tests. Findings first." \
  --output-format json \
  --permission-mode plan \
  --allowedTools "Read,Grep,Glob,Bash(git *)" \
  --model <workhorse> \
  --effort medium

隔离 worktree 执行

cd /path/to/project && claude -p \
  "Implement the fix in an isolated worktree, run the most relevant tests, and summarize the final result." \
  --output-format json \
  --permission-mode bypassPermissions \
  --model <flagship> \
  --effort high \
  --worktree fix-login-timeout

适合让子 Claude Code 独立完成一段实现，而不直接污染当前工作树。

干净子进程 / prompt 实验

先决条件：这个示例假设你已经通过 ANTHROPIC_API_KEY 或 --settings 里的 apiKeyHelper 提供鉴权。--bare 不会读取本地 OAuth / keychain，所以直接依赖 claude auth login 的环境会报 Not logged in。

cd /path/to/project && ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" claude -p \
  "Review src/auth.ts for contract drift only." \
  --output-format json \
  --permission-mode plan \
  --allowedTools "Read,Grep,Glob" \
  --model <workhorse> \
  --effort medium \
  --bare \
  --max-turns 3

适合做更可复现的 scripted 调用，不希望本地 CLAUDE.md、插件、skills 或 auto memory 影响输出。