Claude Code 自动化：Agent 模式与 -p 模式、Hooks、批量任务完全指南

flowchart LR
    A[Shell 脚本 / CI Pipeline] -->|claude -p "prompt"| B[Claude Code Headless]
    B --> C{工具调用}
    C -->|FileRead| D[读取文件]
    C -->|Bash| E[执行命令]
    C -->|Grep/Glob| F[搜索代码]
    C -->|Edit/Write| G[修改文件]
    D & E & F & G --> B
    B -->|stdout| H[结构化输出 JSON/Text]
    H --> A

# 最简单的用法：传入 prompt，获取文本输出
claude -p "解释 src/auth.ts 文件的核心逻辑"

# 通过管道传入内容
echo "为以下代码写单元测试：$(cat src/utils.py)" | claude -p

# 获取 JSON 格式输出，方便程序解析
claude -p --output-format json "列出 src/ 目录下所有 TODO 注释"

# 流式 JSON 输出（适合实时处理）
claude -p --output-format stream-json "重构 src/api/ 下的错误处理"

#!/bin/bash
# auto-review.sh — 对比 main 分支，自动审查当前分支的变更

set -euo pipefail

DIFF=$(git diff main...HEAD --stat)
if [ -z "$DIFF" ]; then
  echo "没有发现与 main 分支的差异"
  exit 0
fi

echo "=== 开始自动代码审查 ==="

claude -p \
  --max-turns 3 \
  --allowedTools "FileRead,Grep,Glob" \
  --output-format text \
  --system-prompt "你是一位资深代码审查专家。审查时请关注：
1. 潜在的 Bug 和边界情况
2. 安全漏洞（注入、XSS、硬编码密钥）
3. 性能问题
4. 代码风格一致性
请用中文回复，每个问题给出严重级别（高/中/低）和修复建议。" \
  "请审查当前分支相对于 main 的所有代码变更：$(git diff main...HEAD)"

chmod +x auto-review.sh
./auto-review.sh

#!/bin/bash
# find-tech-debt.sh — 自动发现技术债务并生成报告

RESULT=$(claude -p \
  --max-turns 4 \
  --allowedTools "FileRead,Grep,Glob" \
  --output-format json \
  "扫描整个项目，找出以下技术债务：
  1. 含有 TODO/FIXME/HACK 注释的代码
  2. 超过 300 行的函数
  3. 重复代码模式
  4. 缺少错误处理的异步函数
  以 JSON 格式输出结果，按严重程度排序。")

# 提取结果消息
echo "$RESULT" | jq -r '.result' > tech-debt-report.json
echo "报告已保存到 tech-debt-report.json"

# 可选：发送到 Slack
# jq -r '.result' tech-debt-report.json | slack-cli post --channel eng-alerts

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_bash.py"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_edit.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '项目规范已加载：请遵循 CLAUDE.md 中的编码规范'"
          }
        ]
      }
    ]
  }
}

{
  "session_id": "abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/test"
  }
}

#!/usr/bin/env python3
"""PreToolUse Hook: 拦截危险的 Bash 命令"""
import json
import sys
import re

def is_dangerous(command):
    normalized = ' '.join(command.lower().split())

    # 检测 rm -rf 及其变体
    dangerous_patterns = [
        r'\brm\s+.*-[a-z]*r[a-z]*f',
        r'\brm\s+.*-[a-z]*f[a-z]*r',
        r'\brm\s+--recursive\s+--force',
    ]

    # 检测危险路径
    dangerous_targets = ['/', '/*', '~', '$HOME', '..']

    for pattern in dangerous_patterns:
        if re.search(pattern, normalized):
            for target in dangerous_targets:
                if re.search(re.escape(target), normalized):
                    return True
    return False

def is_env_access(command):
    """检测对 .env 文件的访问"""
    env_patterns = [
        r'\bcat\s+.*\.env\b',
        r'\becho\s+.*>\s*\.env\b',
        r'\btouch\s+.*\.env\b',
    ]
    for pattern in env_patterns:
        if re.search(pattern, command):
            return True
    return False

# 读取 Hook 输入
data = json.load(sys.stdin)
tool_name = data.get("tool_name", "")
tool_input = data.get("tool_input", {})

if tool_name == "Bash":
    command = tool_input.get("command", "")

    if is_dangerous(command):
        print("⛔ 安全拦截：检测到危险的 rm 命令。请确认操作目标后手动执行。", file=sys.stderr)
        sys.exit(2)

    if is_env_access(command):
        print("⚠️ 警告：正在访问 .env 文件，请确保不会泄露敏感信息。", file=sys.stderr)
        sys.exit(0)  # 允许但警告

sys.exit(0)  # 正常放行

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_bash.py"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto_format.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# 自动格式化 Hook：在 Claude 编辑文件后运行

# 从 stdin 读取 Hook 数据
DATA=$(cat)
FILE_PATH=$(echo "$DATA" | jq -r '.tool_input.file_path // empty')

if [ -z "$FILE_PATH" ]; then
  exit 0
fi

# 根据文件扩展名选择格式化工具
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    npx eslint --fix "$FILE_PATH" 2>/dev/null
    ;;
  *.py)
    python3 -m black "$FILE_PATH" 2>/dev/null
    python3 -m isort "$FILE_PATH" 2>/dev/null
    ;;
  *.go)
    gofmt -w "$FILE_PATH" 2>/dev/null
    ;;
esac

# 输出反馈给 Agent
echo "✅ 已自动格式化: $FILE_PATH" >&2
exit 0

#!/bin/bash
# .claude/hooks/session_start.sh
# 在每次会话开始时向 Agent 注入项目规范

echo "📋 项目规范提醒：
- 本项目使用 TypeScript 严格模式
- 所有 API 端点必须有输入验证
- 提交前确保测试通过
- 数据库迁移使用 Drizzle ORM
- 禁止使用 any 类型" >&2

exit 0

#!/bin/bash
# hooks/stop-hook.sh — Ralph Loop 的核心

DATA=$(cat)
RESULT=$(echo "$DATA" | jq -r '.result // empty')
COMPLETION_PROMISE="COMPLETE"
MAX_ITERATIONS=50

# 检查是否包含完成信号
if echo "$RESULT" | grep -q "$COMPLETION_PROMISE"; then
  echo "🎉 任务完成！" >&2
  exit 0  # 允许退出
fi

# 检查迭代次数
ITERATION_FILE="/tmp/ralph_iteration"
CURRENT=$(cat "$ITERATION_FILE" 2>/dev/null || echo "0")
CURRENT=$((CURRENT + 1))
echo "$CURRENT" > "$ITERATION_FILE"

if [ "$CURRENT" -ge "$MAX_ITERATIONS" ]; then
  echo "⏰ 达到最大迭代次数 ($MAX_ITERATIONS)，退出循环。" >&2
  exit 0
fi

# 注入 prompt 继续循环
echo "⏳ 第 $CURRENT/$MAX_ITERATIONS 次迭代。继续工作..." >&2
PROMPT=$(cat /tmp/ralph_prompt)
echo "$PROMPT" >&2  # 将 prompt 输出到 stderr，Agent 会看到

exit 0

<!-- .claude/agents/security-scanner.md -->
---
name: security-scanner
description: 专门扫描代码中的安全漏洞
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-haiku-4-5-20251001
---

你是一位安全审计专家。你的任务是：

1. 扫描给定目录下的所有源代码文件
2. 检查以下安全漏洞：
   - SQL 注入
   - XSS 跨站脚本
   - 命令注入
   - 硬编码密钥/密码
   - 不安全的反序列化
3. 对每个发现的问题，给出：
   - 文件路径和行号
   - 严重级别（严重/高/中/低）
   - 修复建议

输出格式为 Markdown 表格。

<!-- .claude/agents/validation-adder.md -->
---
name: validation-adder
description: 为单个 API 端点文件添加输入验证
tools:
  - Read
  - Edit
  - Grep
  - Glob
model: claude-sonnet-4-6
---

你是一个代码重构专家。给定一个 API 路由文件，你需要：

1. 读取文件内容
2. 找到所有没有输入验证的端点
3. 使用 zod schema 添加请求体验证
4. 添加适当的错误处理中间件
5. 确保不破坏现有功能

项目使用的技术栈：Express.js + TypeScript + zod

请找到 src/routes/ 下的所有路由文件，然后为每个文件启动一个
validation-adder 子 Agent 并行添加输入验证。

/batch "为以下文件添加 JSDoc 注释" src/**/*.ts

/simplify

# 安装
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/main/install.sh | bash

# 使用：自动增加测试覆盖率
continuous-claude \
  --prompt "增加测试覆盖率，直到覆盖率达到 80%" \
  --max-runs 10

#!/bin/bash
# agent-loop.sh — 最简 Agent 循环

PROMPT_FILE="agent-task.md"
NOTES_FILE="AGENT_NOTES.md"
MAX_ITERATIONS=20

# 初始化笔记文件
if [ ! -f "$NOTES_FILE" ]; then
  echo "# Agent 进度笔记" > "$NOTES_FILE"
  echo "" >> "$NOTES_FILE"
  echo "## 任务" >> "$NOTES_FILE"
  cat "$PROMPT_FILE" >> "$NOTES_FILE"
fi

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "=== 迭代 $i/$MAX_ITERATIONS ==="

  RESULT=$(claude -p \
    --max-turns 10 \
    --output-format text \
    "你正在进行第 $i 次迭代（共 $MAX_ITERATIONS 次）。

    请阅读 $NOTES_FILE 了解之前的进度。

    你的核心任务是：$(cat $PROMPT_FILE)

    规则：
    1. 每次只做有意义的进展，不要试图一次完成全部工作
    2. 完成后更新 $NOTES_FILE，记录你做了什么、发现了什么、下一步应该做什么
    3. 如果你认为任务已经全部完成，在输出的最后一行写上 TASK_COMPLETE
    4. 如果遇到无法解决的问题，在最后一行写上 TASK_BLOCKED 和原因")

  echo "$RESULT"

  # 检查完成信号
  if echo "$RESULT" | grep -q "TASK_COMPLETE"; then
    echo "🎉 任务完成！"
    break
  fi

  if echo "$RESULT" | grep -q "TASK_BLOCKED"; then
    echo "⚠️ Agent 遇到阻碍，需要人工干预。"
    break
  fi
done

echo "=== Agent 循环结束 ==="

#!/bin/bash
# batch-repos.sh — 对多个仓库执行相同的 Claude Code 任务

REPOS=("api-gateway" "user-service" "payment-service" "notification-service")
TASK="升级所有依赖到最新版本，修复所有 breaking changes，确保测试通过"
MODEL="claude-sonnet-4-6"

for repo in "${REPOS[@]}"; do
  echo "=== 处理 $repo ==="
  cd "/projects/$repo" || continue

  claude -p \
    --max-turns 15 \
    --model "$MODEL" \
    "$TASK。项目：$repo。完成后运行测试确保一切正常。"

  echo "=== $repo 处理完毕 ==="
  cd - || exit
done

#!/bin/bash
# batch-repos-parallel.sh — 并行处理多个仓库

REPOS=("api-gateway" "user-service" "payment-service" "notification-service")
TASK="升级所有依赖到最新版本，修复所有 breaking changes，确保测试通过"

for repo in "${REPOS[@]}"; do
  (
    echo "=== 开始处理 $repo ==="
    cd "/projects/$repo" || exit 1

    claude -p \
      --max-turns 15 \
      --output-format json \
      "$TASK。项目：$repo。" \
      > "/tmp/claude-result-$repo.json" 2>&1

    echo "=== $repo 处理完毕 ==="
  ) &
done

# 等待所有后台任务完成
wait
echo "=== 所有仓库处理完毕 ==="

# 汇总结果
for repo in "${REPOS[@]}"; do
  echo "--- $repo ---"
  jq -r '.result // .error' "/tmp/claude-result-$repo.json" 2>/dev/null || echo "处理失败"
done

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

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

      - name: Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p \
            --max-turns 3 \
            --allowedTools "FileRead,Grep,Glob" \
            --output-format text \
            "审查这个 PR 的代码变更，关注安全漏洞、性能问题和代码质量。
            Diff: $(git diff origin/main...HEAD)"

# .github/workflows/claude-issue-handler.yml
name: Claude Issue Handler

on:
  issues:
    types: [labeled]

jobs:
  auto-fix:
    if: contains(github.event.label.name, 'claude-fix')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Process Issue
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          ISSUE_TITLE="${{ github.event.issue.title }}"
          ISSUE_BODY="${{ github.event.issue.body }}"

          claude -p \
            --max-turns 10 \
            --dangerously-skip-permissions \
            "根据以下 Issue 描述修复代码：
            标题：$ISSUE_TITLE
            内容：$ISSUE_BODY

            修复后运行测试确保通过。"

      - name: Create PR
        run: |
          BRANCH="fix/issue-${{ github.event.issue.number }}"
          git checkout -b "$BRANCH"
          git add -A
          git commit -m "fix: resolve #${{ github.event.issue.number }}"
          git push origin "$BRANCH"
          gh pr create \
            --title "fix: ${{ github.event.issue.title }}" \
            --body "Closes #${{ github.event.issue.number }}" \
            --base main

project/
├── .claude/
│   ├── settings.json          # Hooks 配置
│   ├── agents/
│   │   ├── security-scanner.md
│   │   ├── test-writer.md
│   │   └── doc-generator.md
│   └── hooks/
│       ├── pre_bash.py        # 危险命令拦截
│       ├── auto_format.sh     # 自动格式化
│       └── session_start.sh   # 会话上下文注入
├── scripts/
│   ├── auto-review.sh         # 自动代码审查
│   ├── agent-loop.sh          # Agent 循环
│   └── batch-repos.sh         # 多仓库批量操作
└── .github/
    └── workflows/
        ├── claude-review.yml
        └── claude-issue-handler.yml

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto_format.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session_start.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "FileRead",
      "Grep",
      "Glob",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff*)"
    ]
  }
}

flowchart TD
    A[开发者提交 PR] --> B[GitHub Actions 触发]
    B --> C[claude -p 代码审查]
    C --> D{审查结果}
    D -->|发现问题| E[评论到 PR]
    D -->|通过| F[等待人工确认]

    G[开发者本地编辑] --> H[Claude Code 交互模式]
    H --> I{PreToolUse Hook}
    I -->|危险命令| J[拦截 ❌]
    I -->|安全命令| K[执行]
    K --> L{PostToolUse Hook}
    L --> M[自动格式化]
    M --> N[继续工作]

    O[/batch 模式] --> P[并行处理多文件]
    P --> Q[批量添加测试/文档]

    R[大型任务] --> S[agent-loop.sh]
    S --> T[持续迭代直到完成]

    style J fill:#E74C3C,color:white
    style F fill:#2ECC71,color:white
    style M fill:#3498DB,color:white