Claude Code SDK #13：自动化脚本全解——`-p` 开关背后的完整标志体系，把 Claude Code 嵌进任意流水线

用了很久 Claude Code，你可能一直把它当交互式助手用。

但它还有另一张脸：一个可以被 cat、bash、Python、CI/CD 直接调用的命令行组件。这张脸的入口只有一个标志：-p（--print）。

掌握 -p 背后那套完整的「自动化标志体系」，Claude Code 就变成了你流水线里的一个可编程节点——接受 stdin、输出 JSON、控制预算、限制轮次、快速启动、提升缓存命中率。

1. `-p` 是什么：把交互模式变成管道组件

默认的 claude 命令会启动一个交互式 TUI 会话。加上 -p（--print）之后，行为完全不同：

claude -p "解释这个函数"

Claude 执行完毕后直接退出，把结果打到 stdout。没有 TUI，没有等待，可以被 |、> 或脚本捕获。

管道直接可用：

cat error.log | claude -p "分析这段报错，给出最可能的原因和修复建议"

从这里出发，所有自动化标志才有了用武之地。

2. 输出格式三选一

格式	标志	适用场景
`text`	默认或 `--output-format text`	人类可读输出、Shell 脚本直接处理字符串
`json`	`--output-format json`	结构化结果，Python/Node 解析 ResultMessage
`stream-json`	`--output-format stream-json`	实时处理每条消息，搭配 `--verbose` + `--include-partial-messages`

json 模式下，输出是完整的 ResultMessage 对象，包含 result（最终文本）、total_cost_usd（本次花费）、num_turns（实际轮次数）、usage.cache_read_input_tokens（缓存命中量）等字段——可直接用于成本审计和日志追踪。

# 拿到 JSON 后用 jq 提取结果和花费
claude -p "重构 utils.py 中的 parse_config 函数" \
  --output-format json | jq '{result: .result, cost: .total_cost_usd}'

stream-json 是 #11 期介绍的流式输出在 CLI 层的等价物：每条 StreamEvent 实时落到 stdout，适合构建进度 UI 或需要工具调用实时可见性的场景。

3. 控制轮次与预算：防止脚本失控

自动化场景最怕两件事：无限循环和意外超支。

# 最多跑 5 轮，超出则以错误退出
claude -p "找出 src/ 下所有潜在的 SQL 注入漏洞" \
  --max-turns 5

# 最多花 2 美元，超出则停止
claude -p "批量注释 api/ 目录下每个函数" \
  --max-budget-usd 2.00

--max-turns 超限会以非零退出码退出，可在 Shell 中用 || 或 $? 捕获。--max-budget-usd 在预算耗尽时同样中止任务。两个标志都只在 -p 模式下生效。

`--bare` 模式与完整模式功能对比 — `--bare` vs 完整模式的功能差异，AI 生成示意图

4. `--bare`：最小模式，加速脚本启动

默认启动时，Claude Code 会自动发现 Hooks、Skills、Plugins、MCP 服务器、CLAUDE.md 记忆文件……这些对交互会话有价值，但对批量脚本是纯开销。

claude --bare -p "校对这段文档，只修改明显的语法错误"

--bare 的效果：

跳过：Hooks 自动发现、Skills/Commands、Plugins、MCP 自动配置、auto memory、CLAUDE.md
保留：Bash、文件读取、文件编辑工具
环境变量等价：设置 CLAUDE_CODE_SIMPLE=1 可替代 --bare

结果是一个极轻量的 Claude 实例，启动延迟显著降低，适合高频批量调用。

5. `--exclude-dynamic-system-prompt-sections`：CI 场景的缓存命中率利器

这是一个鲜为人知但价值很高的标志。

Claude Code 默认系统 Prompt 里包含「机器相关信息」——当前工作目录、环境变量、机器 ID、内存路径……这些信息在不同机器上不同，导致不同 Worker 的系统 Prompt 哈希不一致，Prompt 缓存无法复用。

claude -p \
  --exclude-dynamic-system-prompt-sections \
  "分析这个 TypeScript 项目的依赖关系"

加上这个标志之后：机器相关信息被移到第一条用户消息里（而非系统 Prompt）。系统 Prompt 内容跨 Worker 保持一致，缓存命中率大幅提升——在 CI/CD 多 Worker 并行场景，这个标志直接影响 API 调用成本。

适用前提：只对默认系统 Prompt 生效；如果你用了 --system-prompt 替换了整个系统 Prompt，此标志自动失效。

`--append-system-prompt` 追加策略与 `--system-prompt` 替换策略对比 — 追加策略保留默认工具指引，替换策略完全接管系统 Prompt，AI 生成示意图

6. 系统 Prompt 定制：两种策略

# 追加策略：保留默认工具指引 + 补充领域规则
claude -p \
  --append-system-prompt "始终用中文回复，代码注释也用中文" \
  "重构 database.ts 的连接池逻辑"

# 替换策略：完全自定义（需自行包含工具说明）
claude -p \
  --system-prompt-file ./prompts/code-reviewer.txt \
  "review 这个 PR 的安全问题"

选择原则很清晰：

追加（--append-system-prompt / --append-system-prompt-file）：你希望 Claude 仍是一个编程助手，只是额外遵循你的规则。默认工具指引和安全限制保留。
替换（--system-prompt / --system-prompt-file）：你的场景跟编程无关，或者需要完全不同的 Identity。替换会丢弃默认工具指引和安全约束，适合完全受控的非交互 Pipeline。

两种标志都对当前调用生效，不持久化。

7. 会话管理：继续上下文与禁用持久化

在脚本中继续上次对话

# 继续最近的会话（print 模式）
claude -c -p "刚才找到的那个 bug，现在帮我写单元测试覆盖"

--fork-session 可以在 resume 时创建新 session ID，避免污染原会话历史：

claude --resume auth-refactor --fork-session -p "基于这个会话做一个只读分析"

无状态脚本：禁用持久化

# 不保存到磁盘，不可恢复，适合敏感批量任务
claude -p --no-session-persistence "分析这段包含密钥的配置文件"

等价环境变量：CLAUDE_CODE_SKIP_PROMPT_HISTORY=1。

8. 完整自动化脚本示例

把上面各标志组合成一个典型的 CI 代码审查脚本：

#!/bin/bash
set -euo pipefail

DIFF=$(git diff HEAD~1)
RESULT=$(echo "$DIFF" | claude -p \
  --output-format json \
  --max-turns 3 \
  --max-budget-usd 1.00 \
  --bare \
  --exclude-dynamic-system-prompt-sections \
  --append-system-prompt "仅报告安全漏洞和严重 bug，不报告风格问题" \
  "分析这个 diff，找出安全漏洞和严重 bug")

REVIEW=$(echo "$RESULT" | jq -r '.result')
COST=$(echo "$RESULT" | jq -r '.total_cost_usd')

echo "审查完成，花费：\$${COST}"
echo "$REVIEW"

这个脚本：

从 git diff 读取变更作为 stdin（管道输入）
输出 JSON 结构以便提取结果和成本
限制轮次（--max-turns 3）和预算（--max-budget-usd 1.00）
用 --bare 跳过不需要的扩展加快启动
用 --exclude-dynamic-system-prompt-sections 提升缓存命中率
用 --append-system-prompt 限定审查范围

docs.anthropic.comhttps://docs.anthropic.com/en/docs/claude-code/cli-reference外部链接

正在加载内容卡片…

9. `claude agents --json`：后台会话的脚本管理

-p 模式是同步的——调用等结果。Claude Code 还支持后台会话，适合长时任务：

# 启动后台 Agent，立即返回 session ID
claude --bg "调查 flaky test 的根因，生成分析报告"

# 以 JSON 格式列出所有活跃的后台会话（适合脚本解析）
claude agents --json

# 查看某个后台会话的实时输出
claude logs 7c5dcf5d

claude agents --json 输出的数组包含 session ID、启动时间、当前状态，可直接用 jq 处理，适合构建多 Agent 编排脚本。

10. 五条实践建议

1. text vs json 按消费者决定：人类脚本或 bash 处理字符串，用默认 text；需要解析 ResultMessage 字段（cost、turns、usage）用 json；需要实时流用 stream-json。

2. --bare 是批量脚本的默认选项：除非你明确需要 MCP 工具或 Hooks，批量任务都应加 --bare，减少不必要的启动发现流程。

3. CI 多 Worker 必加 --exclude-dynamic-system-prompt-sections：这个标志在单机运行几乎感觉不到差异，但在并行 CI 环境能显著提升缓存命中率，直接降低成本。

4. --max-turns 和 --max-budget-usd 作为安全网，不可省略：生产脚本里不带这两个限制，等于开了一个没有上限的 API 调用入口。

5. --append-system-prompt 优先于 --system-prompt：除非你的场景跟编程工具完全不同，否则追加比替换安全——你不需要自己重新编写工具指引和安全说明。

下期 #14 预告：与 IDE 集成全解——--ide 标志、VS Code / JetBrains 集成、诊断信息如何从 IDE 流入 Agent 上下文、/add-dir 多目录权限边界。

文档来源：1 2