<!-- title: Claude Code自动化三引擎：从-p到Routines实战 -->

# Claude Code 自动化三引擎：从 `-p` 到 Routines 实战

## 概述

Claude Code 提供了三层递进的自动化能力：本地脚本层的 `-p` 无头模式、代码库级的 `/batch` 并行迁移、云端托管的 Routines 定时任务。本教程将逐一拆解每层引擎的核心 API、输出格式、权限模型和成本控制策略，并通过一个完整的"PR 自动审查 → 代码迁移 → 夜间巡检"流水线串联三者。适合已掌握 Claude Code 基础操作、希望将其嵌入 CI/CD 或定时任务的中高级开发者。

**适用人群**：有 3 个月以上 Claude Code 使用经验的开发者、DevOps 工程师、技术负责人。

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code ≥ v2.1.63 | `/batch` 命令从此版本开始提供，`claude --version` 检查 |
| Node.js ≥ 20 | Claude Code 运行环境 |
| ANTHROPIC_API_KEY | 无头模式必须通过环境变量认证 |
| Git 仓库 | `/batch` 和 Routines 依赖 Git 隔离 |
| Claude Pro/Max/Team 计划 | Routines 云端执行需要付费计划 |

```bash
# 检查版本
claude --version

# 如果版本过低，更新
claude update

# 验证 API Key 可用
echo $ANTHROPIC_API_KEY | head -c 10
```

---

## 第一层引擎：`-p` 无头模式——从终端到脚本的桥梁

### 1.1 核心语法与三件套

无头模式的本质是把 Claude Code 从交互式 REPL 变成一个可管道化的命令行工具。它由三个核心标志控制：

```bash
# 基础用法：单次提问，纯文本输出
claude -p "这个项目的认证模块做了什么？"

# 进阶：结构化 JSON 输出
claude -p "列出 auth.py 中所有函数名" --output-format json

# 高级：实时流式 JSON + 工具执行观察
claude -p "审查最近的 diff" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages
```

**三个标志的三角关系**：

```
-p (非交互) + --bare (确定性启动) + --output-format json (结构化输出)
```

- **`-p`**（或 `--print`）：进入非交互模式，接收提示词，输出结果后退出
- **`--bare`**：跳过所有自动发现——hooks、skills、plugins、MCP 服务器、CLAUDE.md 链。只使用你显式传入的标志。这是 CI 环境的**必选项**
- **`--output-format`**：控制返回格式（`text` / `json` / `stream-json`）

### 1.2 三种输出格式深度解析

```mermaid
flowchart LR
    A[claude -p] --> B{--output-format?}
    B -->|text| C[纯文本<br/>人类可读<br/>机器不友好]
    B -->|json| D[单次JSON信封<br/>result + session_id<br/>+ cost_usd]
    B -->|stream-json| E[换行分隔JSON流<br/>每个事件一行<br/>实时可观测]
    C --> F[适合: 快速问答]
    D --> G[适合: CI脚本<br/>结果解析]
    E --> H[适合: Dashboard<br/>长时间任务监控]
```

**格式一：`text`（默认）**

```bash
claude -p "解释 auth.py 中 OAuth2 的实现逻辑"
# 直接输出纯文本，和终端看到的一样
```

**格式二：`json`——CI 脚本的主力**

```bash
claude -p "审查这个 diff 并报告问题" \
  --output-format json | jq '.result'
```

JSON 输出包含以下关键字段：

```json
{
  "result": "审查结论文本...",
  "session_id": "abc-123-def",
  "total_cost_usd": 0.034,
  "num_turns": 2,
  "usage": {
    "input_tokens": 15200,
    "output_tokens": 890
  }
}
```

成本字段 `total_cost_usd` 让你无需登录 Anthropic 控制台就能按调用追踪花费。

**格式三：`stream-json`——实时可观测的杀手级格式**

```bash
# 最小流式消费者：jq 过滤文本 token
claude -p "写一首关于代码的诗" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages \
  | jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
```

`stream-json` 输出的事件类型包括：

| 事件类型 | 含义 | 关键字段 |
|----------|------|----------|
| `system` / `session_start` | 会话初始化 | `session_id` |
| `system` / `api_retry` | API 重试中 | `attempt`, `max_retries`, `error_status` |
| `stream_event` / `text_delta` | 文本 token 增量 | `delta.text` |
| `tool_use` | 工具调用 | `tool_name`, `tool_input` |
| `tool_result` | 工具返回 | `output` |
| `result` | 最终结果 | `result`, `total_cost_usd` |

`api_retry` 事件对长时间运行任务至关重要——它告诉你 Claude 正在等待速率限制重置，而不是卡死了：

```json
{
  "type": "system",
  "subtype": "api_retry",
  "attempt": 2,
  "max_retries": 5,
  "retry_delay_ms": 2000,
  "error_status": 429,
  "error": "rate_limit"
}
```

### 1.3 管道操作与文件批处理

`-p` 模式读取 stdin，因此可以无缝接入 Unix 管道：

```bash
# 管道输入：将构建错误喂给 Claude 分析
cat build-error.log | claude -p '简洁解释这个构建错误的根因' > analysis.md

# 管道 diff：代码审查脚本
git diff main | claude -p "你是拼写检查器。找出这个 diff 中的所有拼写错误，每行格式：文件名:行号" \
  --output-format json | jq -r '.result'

# 批量文件处理：为每个 Python 文件生成文档字符串
find src -name "*.py" -type f | while read file; do
  claude -p "为这个文件添加 docstring: $(cat "$file")" \
    --allowedTools "Edit" \
    --output-format json \
    | jq -r '.result' > "${file}.docstringd"
done
```

**注意**：管道 stdin 上限为 10MB（v2.1.128+）。超过时写入文件，在提示词中引用路径。

### 1.4 会话延续与多轮对话

无头模式不限于单轮交互。通过 `--continue` 和 `--resume` 可以链式调用：

```bash
# 第一步：分析代码
SESSION=$(claude -p "分析 auth.py 的安全漏洞" --output-format json | jq -r '.session_id')

# 第二步：延续同一会话，要求修复
claude -p "现在修复你刚才发现的所有漏洞" \
  --resume "$SESSION" \
  --allowedTools "Edit,Bash,Read"

# 第三步：验证修复
claude -p "运行测试验证修复" \
  --resume "$SESSION" \
  --allowedTools "Bash"
```

`--continue` 延续最近一次会话，`--resume <session_id>` 恢复指定会话。

### 1.5 `--bare` 模式详解

在 CI/CD 环境中，`--bare` 是你的安全网。它做了这些事：

```bash
claude --bare -p "总结这个文件" --allowedTools "Read"
```

| 行为 | 默认模式 | `--bare` 模式 |
|------|----------|--------------|
| 认证方式 | OAuth + keychain | 仅 `ANTHROPIC_API_KEY` |
| 加载 Hooks | 自动发现 | 不加载 |
| 加载 Skills | 自动发现 | 不加载 |
| 加载 MCP 服务器 | 从 `.mcp.json` 发现 | 不加载 |
| 加载 CLAUDE.md | 链式加载 | 不加载 |
| 确定性 | 依赖本地配置 | 每台机器一致 |

在 `--bare` 模式下，你需要显式传入上下文：

```bash
# 传入自定义系统提示
claude --bare -p "审查代码" \
  --append-system-prompt "你是一个安全审计专家"

# 传入 MCP 配置
claude --bare -p "查询数据库" \
  --mcp-config '{"mcpServers":{"postgres":{...}}}'

# 传入自定义 Agent
claude --bare -p "执行任务" \
  --agents '{"agents":[...]}'
```

### 1.6 JSON Schema 约束输出

当你需要 Claude 返回结构化数据而非自由文本时，使用 `--json-schema`：

```bash
# 提取函数列表为 JSON 数组
claude -p "提取 auth.py 中所有函数名" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "functions": {
        "type": "array",
        "items": {"type": "string"}
      }
    },
    "required": ["functions"]
  }'
```

响应中结构化数据出现在 `structured_output` 字段：

```bash
# 用 jq 提取结构化输出
claude -p "提取函数名" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'
```

---

## 第二层引擎：`/batch` 命令——代码库级并行迁移

### 2.1 `/batch` 与 `-p` 的本质区别

这两个经常被混淆，但它们服务于完全不同的场景：

| 维度 | `/batch` | `-p` 无头模式 |
|------|----------|--------------|
| 执行环境 | 交互式会话内的斜杠命令 | 终端一次性执行 |
| 核心用途 | 代码库级迁移和重构 | CI/CD 集成、脚本自动化 |
| 并行机制 | 自动生成多个 Agent 并行 | 通过 shell 脚本手动控制 |
| Git 集成 | 每个代理独立 Worktree，自动创建 PR | 标准 Git 操作（脚本控制） |
| 引入版本 | v2.1.63+ | 初始版本 |

**选择原则**：对整个项目做批量变更用 `/batch`；嵌入现有流水线用 `-p`。

### 2.2 `/batch` 三阶段执行流程

```mermaid
flowchart TB
    A["/batch migrate from lodash to native"] --> B[阶段1: 调研与规划]
    B --> C[Explore Agent 扫描代码库]
    C --> D[分解为 5-30 个独立单元]
    D --> E{用户批准计划?}
    E -->|否| F[修改计划或中止]
    E -->|是| G[阶段2: 并行执行]
    G --> H["Agent 1<br/>Worktree A"]
    G --> I["Agent 2<br/>Worktree B"]
    G --> J["Agent N<br/>Worktree N"]
    H --> K[阶段3: 追踪与合并]
    I --> K
    J --> K
    K --> L[创建独立 PR]
    L --> M[聚合报告]
```

**阶段一：调研与规划**

编排器 Agent 进入规划模式，启动 Explore Agent 扫描代码库。它识别目标文件、模式和调用点，将工作分解为 5-30 个独立可合并的单元。如果找不到验证路径，会提示用户确认。

**阶段二：并行执行**

每个单元生成一个后台 Agent，所有 Agent 真正并行运行。每个 Agent 配置：
- `isolation: "worktree"`：独立 Git Worktree 隔离
- 自包含提示词：包含单元范围、修改指令、验证方法

**阶段三：追踪与结果**

所有单元完成后，编排器生成聚合报告并创建独立 PR。

### 2.3 典型用例与命令

```bash
# 在 Claude Code 交互式会话中执行
> /batch 将所有 lodash 调用替换为原生等价实现

> /batch 为所有无类型函数参数添加类型注解

> /batch 将所有数据库列名从 camelCase 改为 snake_case

> /batch 将 React 组件迁移到 Vue 组合式 API
```

每个命令都会触发上述三阶段流程。`/batch` 的速度优势来自真正的并行——比逐个发送提示词快最多 10 倍。

### 2.4 `/batch` 与 `/simplify` 的配合

`/simplify` 是 `/batch` 的自然搭档，专注于代码质量审查而非迁移：

```
/simplify 启动三个并行审查 Agent:
├── 代码复用 Agent → 发现重复逻辑、遗漏的抽象
├── 代码质量 Agent → 标记可读性问题、架构缺陷
└── 效率 Agent → 检测性能问题、资源浪费
```

**推荐工作流**：

```
实现功能 → /simplify 清理代码 → /batch 执行跨文件迁移 → CI 审查
```

---

## 第三层引擎：Routines——云端托管定时任务

### 3.1 Routines 是什么

Routines 是 2026 年 4 月推出的研究预览功能。一个 Routine 就是一组保存的 Claude Code 配置：提示词 + 仓库 + 连接器，打包后在 Anthropic 托管的云基础设施上自动运行。**笔记本合上也能继续工作**。

Routines 有三种触发器：

| 触发器 | 说明 | 典型场景 |
|--------|------|----------|
| **定时触发** | 按小时/每天/每周/一次性运行 | 每日 Issue 清理、每周文档漂移检测 |
| **API 触发** | HTTP POST 到专属端点 | 部署后冒烟测试、告警自动修复 |
| **GitHub 触发** | PR 打开/合并/Release 发布时 | PR 自动审查、SDK 跨语言同步 |

### 3.2 创建 Routine

**方式一：从 Web 界面创建**

1. 访问 `claude.ai/code/routines`，点击 New routine
2. 命名并编写提示词（**提示词是核心**——Routine 自主运行，必须自包含且明确）
3. 选择 GitHub 仓库（运行时从默认分支克隆）
4. 选择云环境（控制网络访问和环境变量）
5. 添加连接器（Slack、Linear、GitHub 等外部服务）
6. 配置触发器

**方式二：从 CLI 创建**

```bash
# 在 Claude Code 交互会话中
> /schedule
```

**关键配置项**：

```yaml
Routine 配置:
  提示词: "自包含的任务描述，包含成功标准"
  仓库: [repo1, repo2]
  环境:
    网络访问: Trusted / Restricted / None
    环境变量: {API_KEY: "***", SLACK_WEBHOOK: "***"}
    安装脚本: "npm ci && npm run build"
  连接器: [Slack, Linear, GitHub]
  触发器:
    - 类型: schedule
      cron: "0 9 * * 1-5"  # 工作日早上9点
    - 类型: api
      endpoint: /routines/{id}/trigger
    - 类型: github
      events: [pull_request.opened]
```

### 3.3 三种触发器详解

**定时触发**

```bash
# 每晚 2 点运行安全扫描
触发器: schedule
cron: "0 2 * * *"
提示词: "扫描最近24小时合并的PR，检查是否引入新的安全漏洞。如果有，在相关PR下留言并通知 #security Slack频道。"

# 每周一上午清理 backlog
触发器: schedule
cron: "0 9 * * 1"
提示词: "读取本周新增的 Issues，按模块打标签、分配 Owner，在 Slack 发送摘要。"
```

**API 触发**

```bash
# 部署后触发验证
curl -X POST https://api.claude.ai/routines/{id}/trigger \
  -H "Authorization: Bearer $CLAUDE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "生产环境部署完成，版本 v2.3.1。请运行冒烟测试。"}'
```

API 触发支持传入 `text` 字段作为动态上下文，让同一个 Routine 可以响应不同事件。

**GitHub 触发**

```yaml
触发器:
  类型: github
  事件: pull_request.opened
  过滤:
    仓库: myorg/backend-api
    分支: "!dependabot/*"  # 排除 dependabot PR
```

GitHub 触发器会在 PR 创建时自动克隆仓库，Claude 创建 `claude/` 前缀的分支进行变更。

### 3.4 Routines 的安全边界

Routine 运行在云端，以你的身份执行操作。关键安全原则：

- Routine 的所有操作（commit、PR、Slack 消息）都显示为你的身份
- 仓库分支权限控制 Routine 可以推送到哪些分支
- 环境的网络访问级别限制出站连接
- 连接器只访问你授权的服务
- 每个 Routine 都有独立的 API 端点和 Bearer Token

### 3.5 Routines vs `-p` vs `/batch` 选择决策

```text
flowchart TD
    A[需要自动化] --> B{任务范围?}
    B -->|单个文件/快速问答| C[-p 无头模式]
    B -->|整个代码库迁移| D[/batch 命令]
    B -->|定时/事件驱动| E[Routines]

    C --> F{需要持续运行?}
    F -->|否| G[shell 脚本 + claude -p]
    F -->|是| H[CI/CD 管道 + -p]

    D --> I{需要审查后合并?}
    I -->|是| J[/batch + 自动 PR]
    I -->|否| K[直接提交]

    E --> L{触发方式?}
    L -->|定时| M[Schedule Trigger]
    L -->|HTTP 调用| N[API Trigger]
    L -->|Git 事件| O[GitHub Trigger]
```

| 场景 | 推荐方案 | 理由 |
|------|----------|------|
| CI 中审查 PR | `-p` + `--bare` | 确定性、可审计、低成本 |
| 全项目 API 迁移 | `/batch` | 并行 Agent、Worktree 隔离 |
| 每日 Issue 清理 | Routines + 定时触发 | 笔记本关闭也能运行 |
| 部署后健康检查 | Routines + API 触发 | 按需触发、云端执行 |
| SDK 跨语言同步 | Routines + GitHub 触发 | PR 合并自动触发 |
| 批量文件处理 | `-p` + shell 循环 | 灵活、可管道化 |

---

## Hooks：连接三层引擎的神经系统

### 4.1 Hooks 生命周期全景

Hooks 是在 Claude Code 生命周期特定节点执行的脚本、HTTP 调用或 LLM 提示。它们让你在不需要修改 Claude Code 本身的情况下注入自定义逻辑。

```mermaid
timeline
    title Claude Code 生命周期中的 Hook 事件
    section 会话级
        SessionStart : 会话开始时
        Setup : --init-only 或 -p + --init 时
        SessionEnd : 会话结束时
    section 轮次级
        UserPromptSubmit : 用户提交提示词后
        InstructionsLoaded : CLAUDE.md 加载时
        Stop : Claude 完成响应时
    section 工具级
        PreToolUse : 工具执行前（可阻止）
        PermissionRequest : 权限弹窗时
        PostToolUse : 工具成功执行后
        PostToolUseFailure : 工具执行失败后
        PostToolBatch : 批量工具调用完成后
    section Agent 级
        SubagentStart : 子 Agent 启动时
        SubagentStop : 子 Agent 完成时
        TaskCreated : 任务创建时
        TaskCompleted : 任务完成时
```

总共 25+ 个 Hook 事件，覆盖了从会话启动到工具调用的每一个关键节点。

### 4.2 Hook 配置结构

Hooks 在 `.claude/settings.json` 中配置：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ${CLAUDE_FILE_PATH}"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/enhance-prompt.py"
          }
        ]
      }
    ]
  }
}
```

### 4.3 Hook 四种处理器类型

| 类型 | 说明 | 适用场景 |
|------|------|----------|
| **command** | 执行 Shell 命令 | 格式化、lint、阻止危险操作 |
| **http** | 发送 HTTP POST | 通知外部系统、审计日志 |
| **prompt** | 返回 LLM 提示给 Claude | 动态注入上下文、修改行为 |
| **agent** | 启动独立 Agent | 复杂决策、多条件判断 |

### 4.4 关键 Hook 事件实战

**PreToolUse：安全门禁**

```bash
#!/bin/bash
# .claude/hooks/block-destructive.sh
# 读取 stdin 中的 JSON 输入
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# 阻止 rm -rf 和 force push
if echo "$COMMAND" | grep -qE 'rm -rf|push --force|reset --hard'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "阻止破坏性操作: '"$COMMAND"'"
    }
  }'
  exit 0
fi
# 不输出任何内容表示放行
```

**PostToolUse：自动格式化**

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null"
          }
        ]
      }
    ]
  }
}
```

**Stop：完成通知**

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message '任务完成' -sound default"
          }
        ]
      }
    ]
  }
}
```

**UserPromptSubmit：提示词增强**

```bash
#!/bin/bash
# .claude/hooks/enhance-prompt.py
import json, sys

data = json.load(sys.stdin)
prompt = data.get("user_prompt", "")

# 注入项目上下文
context = """
项目上下文:
- 技术栈: Next.js 15 + TypeScript + Prisma
- 编码规范: ESLint strict, Prettier
- 测试框架: Vitest
- 分支策略: feature/* → develop → main
"""

output = {
    "hookSpecificOutput": {
        "hookEventName": "UserPromptSubmit",
        "appendedUserPrompt": context + "\n" + prompt
    }
}
json.dump(output, sys.stdout)
```

### 4.5 Setup Hook：CI/CD 的初始化利器

Setup Hook 是专门为 CI 环境设计的。配合 `--init-only` 标志，可以只运行初始化脚本而不启动会话：

```bash
# 只运行 Setup hooks 然后退出
claude --init-only

# 在 -p 模式中先运行 Setup 再执行任务
claude -p "运行测试" --init

# 维护模式：运行 Setup + 自动修复
claude -p "修复 lint 错误" --maintenance
```

Setup Hook 配置示例：

```json
{
  "hooks": {
    "Setup": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm ci && npm run build && echo '环境准备完成'"
          }
        ]
      }
    ]
  }
}
```

---

## Auto Mode：减少 93% 的权限弹窗

### 5.1 问题与解决方案

Anthropic 内部数据：Claude Code 用户**批准了 93% 的权限弹窗**。这意味着绝大多数弹窗只是形式——用户看都不看就点确认。Auto Mode 用一个两层 AI 分类器自动化这个过程：

```mermaid
flowchart TD
    A[Claude Code 操作] --> B{快速过滤器<br/>单 token 分类}
    B -->|明显安全| C[直接执行]
    B -->|不确定| D{思维链审查<br/>深度推理}
    D -->|审查通过| C
    D -->|需要人工| E[弹出权限请求]

    style C fill:#4caf50,color:#fff
    style E fill:#f44336,color:#fff
```

**第一层：快速过滤器**——单 token 分类判断操作是否明显安全。安全的直接放行，延迟极低。

**第二层：思维链审查**——快速过滤器无法决定时，第二个模型进行深度推理，然后决定执行还是升级给开发者。

**例外情况**：涉及凭证、关键基础设施、生产部署的操作，无论分类器结论如何，仍然需要人工确认。

### 5.2 使用建议

- Auto Mode 不赋予新权限——它只是自动化那些本来就会被批准的权限
- 建议在隔离环境中使用，不要直接指向生产系统
- 分类器可能产生假阳性（阻止无害操作）和假阴性（放过有风险的操作）
- 最佳实践：在开发环境开启 Auto Mode，生产环境保持手动审批

---

## 实战案例：三级自动化流水线

### 场景描述

构建一个完整的自动化流水线，覆盖日常开发的核心环节：

1. **PR 自动审查**（`-p` 无头模式 + GitHub Actions）
2. **全项目 TypeScript 迁移**（`/batch` 命令）
3. **每日安全巡检**（Routines 定时触发）
4. **安全门禁**（Hooks PreToolUse）

### 步骤一：PR 自动审查 GitHub Actions

创建 `.github/workflows/claude-review.yml`：

```yaml
name: Claude PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          DIFF=$(git diff --unified=3 "$BASE_SHA"..."$HEAD_SHA")
          echo "$DIFF" | claude -p \
            --bare \
            --output-format json \
            --allowedTools "Read,Grep,Glob" \
            --max-turns 5 \
            "Review this diff. Flag only issues that would cause bugs or security vulnerabilities.
             If there are none, say so. Keep response under 400 words." \
            > review.json

      - name: Post Review
        run: node .github/scripts/post-review.js
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

创建 `.github/scripts/post-review.js`：

```javascript
const fs = require('fs');
const { execSync } = require('child_process');

const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
const body = review.result || 'No review generated.';
const cost = review.total_cost_usd || 0;

// 发布 PR 评论
execSync(`gh pr comment --body "## Claude Code Review (cost: $${cost.toFixed(4)})\n\n${body}"`, {
  stdio: 'inherit'
});
```

### 步骤二：全项目 API 路由迁移

在交互式 Claude Code 会话中：

```
> /batch 将所有 REST API 路由从 Express 风格迁移到 Hono 框架
```

`/batch` 会自动：
1. 扫描所有路由文件
2. 分解为独立迁移单元（每个文件一个）
3. 在独立 Worktree 中并行执行
4. 为每个单元创建 PR

### 步骤三：每日安全巡检 Routine

在 `claude.ai/code/routines` 创建：

```
名称: 每日安全巡检
提示词: |
  1. 检查最近 24 小时合并的 PR
  2. 扫描新增的依赖项是否有已知漏洞（npm audit）
  3. 检查是否有硬编码的 secret 或 API key
  4. 如果发现问题，在对应 PR 下留言，并通知 #security Slack 频道
  5. 如果一切正常，在 #dev-ops 频道发送"安全巡检通过"

仓库: myorg/backend-api
环境: Default (Trusted network)
连接器: Slack (#security, #dev-ops), GitHub
触发器: 
  - 类型: schedule
    cron: "0 2 * * *"  # 每天凌晨 2 点
```

### 步骤四：安全门禁 Hooks

在项目根目录 `.claude/settings.json` 中配置：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": ".claude/hooks/gate-destructive.sh"
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(*.env*)",
            "command": ".claude/hooks/block-env-edit.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/auto-permission.py"
          }
        ]
      }
    ]
  }
}
```

自动权限审批脚本 `.claude/hooks/auto-permission.py`：

```python
#!/usr/bin/env python3
import json, sys, os

data = json.load(sys.stdin)
tool = data.get("tool_name", "")
action = data.get("tool_input", {})

# 安全操作白名单：自动批准
SAFE_PATTERNS = {
    "Read": None,          # 读操作全部放行
    "Grep": None,          # 搜索全部放行
    "Glob": None,          # 文件查找全部放行
    "Bash": ["git status", "git diff", "git log", "npm test", "npm run lint"],
    "Edit": None,          # 需要额外检查
}

decision = {"hookSpecificOutput": {"hookEventName": "PermissionRequest"}}

if tool in ("Read", "Grep", "Glob"):
    decision["hookSpecificOutput"]["permissionDecision"] = "allow"
elif tool == "Bash":
    cmd = action.get("command", "")
    if any(cmd.startswith(safe) for safe in SAFE_PATTERNS["Bash"]):
        decision["hookSpecificOutput"]["permissionDecision"] = "allow"
    else:
        decision["hookSpecificOutput"]["permissionDecision"] = "ask"
else:
    decision["hookSpecificOutput"]["permissionDecision"] = "ask"

json.dump(decision, sys.stdout)
```

### 完整架构总览

```mermaid
flowchart TB
    subgraph 触发层
        PR[PR 事件] --> GH[GitHub Actions]
        CRON[定时调度] --> RT[Routines 云端]
        API[HTTP 调用] --> RT
        DEV[开发者操作] --> CC[Claude Code 交互式]
    end

    subgraph 执行层
        GH --> HP["-p 无头模式<br/>--bare --output-format json"]
        CC --> BAT["/batch 命令<br/>并行 Agent"]
        RT --> CLOUD[云端 Claude Code 会话]
    end

    subgraph 安全层
        HP --> HK["Hooks 神经系统"]
        BAT --> HK
        CLOUD --> HK
        HK --> PTU["PreToolUse: 安全门禁"]
        HK --> PRT["PermissionRequest: 自动审批"]
        HK --> ATU["PostToolUse: 格式化"]
    end

    subgraph 输出层
        HP --> JSON["JSON / stream-json"]
        BAT --> PRS["独立 PR + 聚合报告"]
        CLOUD --> SLACK["Slack 通知"]
        CLOUD --> GHIS["GitHub Issue 评论"]
    end

    style HK fill:#ff9800,color:#fff
    style RT fill:#9c27b0,color:#fff
```

---

## 成本控制与最佳实践

### 成本追踪

```bash
# 每次调用后提取成本
claude -p "分析代码" --output-format json | jq '{cost: .total_cost_usd, turns: .num_turns}'

# 批量任务成本聚合
total=0
for file in src/*.py; do
  cost=$(claude -p "审查: $(cat $file)" --output-format json | jq '.total_cost_usd')
  total=$(echo "$total + $cost" | bc)
  echo "$file: \$$cost"
done
echo "总计: \$$total"
```

### 最佳实践清单

| 层级 | 实践 | 原因 |
|------|------|------|
| `-p` 模式 | 始终使用 `--bare` | CI 中确保确定性 |
| `-p` 模式 | 设置 `timeout-minutes` | 防止 $180 的意外账单 |
| `-p` 模式 | 用 `--allowedTools` 限制工具 | 审查作业不应有 Edit 权限 |
| `/batch` | 先在小范围测试 | 确认迁移策略正确后再全量 |
| `/batch` | 审查每个 PR | 自动化不等于免审查 |
| Routines | 提示词自包含 | 自主运行时无人补充上下文 |
| Routines | 最小权限原则 | 只授权必需的连接器和分支 |
| Hooks | 异步 Hook 用于非关键任务 | 避免阻塞主流程 |
| 通用 | 用 `--max-turns` 限制轮次 | 防止无限循环 |

---

## 延伸阅读

- [Claude Code 官方文档：无头模式](https://code.claude.com/docs/en/headless) — `-p` 标志完整参考
- [Claude Code 官方文档：Hooks 参考](https://code.claude.com/docs/en/hooks) — 25+ Hook 事件完整规范
- [Claude Code 官方文档：Routines](https://code.claude.com/docs/en/routines) — 云端定时任务配置指南

## 参考来源

1. [Run Claude Code programmatically - Claude Code Docs](https://code.claude.com/docs/en/headless) — 官方无头模式完整文档，涵盖 `-p`、`--bare`、输出格式、会话延续
2. [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks) — 官方 Hooks 事件规范，25+ 生命周期事件的 JSON 输入输出格式
3. [Automate work with routines - Claude Code Docs](https://code.claude.com/docs/en/routines) — 官方 Routines 文档，三种触发器类型和云端执行架构
4. [Claude Code in CI/CD: headless patterns for real pipelines - Refactix](https://refactix.com/ai-development-engineering/claude-code-ci-cd-headless-patterns-production) — 生产级 CI/CD 集成模式，含 GitHub Actions 完整工作流
5. [Claude Code stream-json: the output format that changes everything - BackgroundClaude](https://backgroundclaude.com/blog/stream-json) — stream-json 格式深度解析和消费者实现
6. [Claude Code Routines and Auto Mode - ChatForest](https://chatforest.com/reviews/claude-code-routines-auto-mode-autonomous-developer-automation-2026/) — Auto Mode 双层分类器架构和 Routines 定价分析

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)