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

# 检查版本
claude --version

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

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

# 基础用法：单次提问，纯文本输出
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 (结构化输出)

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/>长时间任务监控]

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

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

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

# 最小流式消费者：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'

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

# 管道输入：将构建错误喂给 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

# 第一步：分析代码
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"

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

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

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

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

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

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

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[聚合报告]

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

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

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

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

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

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

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

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]

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

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

# 部署后触发验证
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。请运行冒烟测试。"}'

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

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]

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 : 任务完成时

{
  "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"
          }
        ]
      }
    ]
  }
}

#!/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
# 不输出任何内容表示放行

{
  "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"
          }
        ]
      }
    ]
  }
}

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

#!/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)

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

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

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

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

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

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 }}

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'
});

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

名称: 每日安全巡检
提示词: |
  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": {
    "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"
          }
        ]
      }
    ]
  }
}

#!/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)

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

# 每次调用后提取成本
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"