Claude Code自动化：从-p模式到多Agent编排

本教程系统讲解 Claude Code 的三大自动化能力：Headless 非交互模式（-p）、Hooks 生命周期钩子、多 Agent 并行编排。学完后你将能够在 CI/CD 流水线中集成 Claude Code、用 Hooks 构建自动化的开发护栏、用 Subagent 和 Agent Teams 实现并行批量任务处理。适合有一定 Claude Code 使用经验、希望将 AI 编码能力嵌入自动化工作流的中高级开发者。

前置条件

第一部分：Headless 非交互模式（-p 标志）

1.1 核心概念

Claude Code 的 -p（--print）标志是其自动化的基石。与交互式 REPL 模式不同，-p 模式接收提示后直接执行并退出，将结果输出到 stdout——这正是脚本和流水线所需的行为。

1.2 基础用法

直接传参模式：最简单的用法，将提示作为命令行参数传入。

# 单行提示
claude -p "解释 src/utils.ts 中 formatDate 函数的作用"

# 指定模型
claude -p "重构这个函数" --model claude-sonnet-4-20250514

# 限制最大对话轮次（防止 Agent 循环）
claude -p "修复所有 lint 错误" --max-turns 10

管道输入模式：将文件内容或命令输出通过管道传给 Claude Code。

# 审查代码
cat src/api/auth.ts | claude -p "审查这段代码的安全性和性能问题"

# 分析 Git diff
git diff HEAD~1 | claude -p "总结本次变更的主要内容和影响范围"

# 分析日志文件
tail -100 /var/log/app.log | claude -p "分析这些错误日志，找出根本原因"

1.3 输出格式控制

--output-format 参数让 Claude Code 的输出可以被程序解析，这是自动化集成的关键。

# JSON 格式 — 适合程序解析
claude -p "列出所有 TODO 注释" --output-format json

# 流式 JSON — 适合实时展示
claude -p "重构这段代码" --output-format stream-json

# 纯文本（默认）
claude -p "解释这段代码" --output-format text

{
  "type": "result",
  "subtype": "success",
  "cost_usd": 0.0034,
  "duration_ms": 4521,
  "duration_api_ms": 3800,
  "is_error": false,
  "num_turns": 2,
  "result": "该函数用于将 ISO 8601 格式的日期字符串转换为本地化显示格式...",
  "session_id": "abc123-def456"
}

1.4 工具权限控制

在非交互模式下，Claude Code 默认拥有受限的工具权限。通过 --allowedTools 精确控制 Agent 能做什么。

# 只允许读取文件和搜索，不允许修改
claude -p "审查代码库的架构" \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 5

# 允许读写和执行命令
claude -p "修复所有 TypeScript 编译错误" \
  --allowedTools "Read,Write,Edit,Bash" \
  --max-turns 20

# 完全自主模式（谨慎使用）
claude -p "实现用户认证功能" \
  --dangerously-skip-permissions \
  --max-turns 30

1.5 会话恢复（Session Resume）

自动化流程中经常需要在上一次对话基础上继续工作。Claude Code 提供两种会话恢复机制。

权限级别	允许的工具	适用场景
只读审计	`Read,Glob,Grep`	代码审查、架构分析
安全编辑	`Read,Write,Edit`	文档生成、代码格式化
标准开发	`+Bash`	修复 bug、实现功能
完全自主	`--dangerously-skip-permissions`	CI/CD 自动修复（需沙箱）

# --continue：继续最近一次会话
claude -p "继续修改测试文件" --continue

# --resume：恢复指定会话（通过 session_id）
claude -p "基于之前的分析继续" --resume abc123-def456

# 结合使用：恢复会话并追加指令
claude -p "在上次的基础上添加错误处理" \
  --resume abc123-def456 \
  --max-turns 10

#!/bin/bash
# multi-step-refactor.sh — 多步骤重构脚本

# 第一步：分析架构
SESSION=$(claude -p "分析项目架构，列出需要重构的模块" \
  --output-format json | jq -r '.session_id')

echo "分析完成，会话ID: $SESSION"

# 第二步：基于分析结果制定计划
claude -p "根据刚才的分析，制定详细的重构计划" \
  --resume "$SESSION" \
  --output-format json > plan.json

# 第三步：执行重构
claude -p "按照重构计划开始执行第一步修改" \
  --resume "$SESSION" \
  --allowedTools "Read,Write,Edit,Bash" \
  --max-turns 15

1.6 常见问题与解决

第二部分：Hooks 生命周期钩子

2.1 什么是 Hooks

问题	原因	解决方案
输出包含 ANSI 转义码	终端颜色干扰	加 `--no-color` 或用 `--output-format json`
Agent 无限循环	提示过于宽泛	设置 `--max-turns` 限制
权限被拒绝	工具未授权	检查 `--allowedTools` 配置
超时退出	API 调用耗时过长	在脚本中设置 `timeout` 命令
Token 用尽	大文件导致上下文溢出	使用 `cat file \| head -n 100` 截取

Hooks 是 Claude Code 的事件驱动自动化层。通过在 settings.json 中配置 shell 命令，可以在特定生命周期事件触发时自动执行自定义逻辑——无需人工干预。这是将 AI 编码流程从"手动操作"升级为"自动治理"的关键机制。

2.2 五大 Hook 事件

2.3 配置方式

事件	触发时机	典型用途
`PreToolUse`	每次工具调用之前	安全拦截、参数校验、权限控制
`PostToolUse`	每次工具调用之后	自动格式化、日志记录、通知推送
`Notification`	Claude 需要通知用户时	Slack/钉钉消息转发
`Stop`	Agent 停止生成时	自动测试、质量检查、结果汇总
`SessionStart`	会话初始化时	环境准备、上下文注入

Hooks 在 settings.json 中配置（位于 ~/.claude/settings.json 或项目的 .claude/settings.json）。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 ~/.claude/hooks/pre_bash_check.py",
        "timeout": 10
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null",
        "timeout": 15
      }
    ],
    "Stop": [
      {
        "command": "bash ~/.claude/hooks/on_stop.sh",
        "timeout": 30
      }
    ],
    "SessionStart": [
      {
        "command": "bash ~/.claude/hooks/session_init.sh",
        "timeout": 10
      }
    ]
  }
}

2.4 Hook 输入输出协议

Hook 通过 stdin 接收 JSON 格式的事件数据，通过 stdout 返回 JSON 格式的响应，通过退出码控制行为。

{
  "session_id": "abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/old-build",
    "description": "清理旧构建目录"
  }
}

退出码	含义	行为
0	通过	正常执行工具
2	阻止	阻止工具调用，将 stdout 作为反馈展示给 Agent

{
  "decision": "block",
  "reason": "禁止执行 rm -rf 命令。请改用更安全的删除方式。"
}

2.5 实战：六个生产级 Hook 示例

#!/usr/bin/env python3
"""~/.claude/hooks/block_dangerous_commands.py"""
import sys, json

BLOCKED_PATTERNS = [
    "rm -rf /", "rm -rf ~", "DROP TABLE",
    "git push --force", "git reset --hard",
    "chmod 777", "curl.*|.*sh", "> /etc/"
]

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

for pattern in BLOCKED_PATTERNS:
    if pattern.lower() in command.lower():
        print(json.dumps({
            "decision": "block",
            "reason": f"安全策略阻止：检测到危险命令模式 '{pattern}'"
        }))
        sys.exit(2)

sys.exit(0)

#!/bin/bash
# ~/.claude/hooks/auto_format.sh
# PostToolUse — 写入文件后自动格式化

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.file // 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
        ;;
    *.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

exit 0

#!/bin/bash
# ~/.claude/hooks/session_init.sh
# 在新会话开始时注入项目上下文

PROJECT_DIR=$(pwd)
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")

cat <<EOF
项目目录: $PROJECT_DIR
当前分支: $BRANCH
Git 状态: $(git status --short 2>/dev/null | head -5)
最近提交: $(git log --oneline -3 2>/dev/null)
EOF

exit 0

#!/bin/bash
# ~/.claude/hooks/on_stop_run_tests.sh
# Agent 停止后自动运行相关测试

PROJECT_DIR=$(pwd)

# 检测项目类型并运行对应测试
if [ -f "package.json" ]; then
    npm test -- --passWithNoTests 2>&1 | tail -20
elif [ -f "pytest.ini" ] || [ -f "pyproject.toml" ]; then
    python3 -m pytest --tb=short -q 2>&1 | tail -20
elif [ -f "go.mod" ]; then
    go test ./... 2>&1 | tail -20
fi

exit 0

#!/usr/bin/env python3
"""~/.claude/hooks/protect_sensitive.py"""
import sys, json, os

PROTECTED_FILES = [
    ".env", ".env.production", ".env.local",
    "credentials.json", "secrets.yaml",
    "id_rsa", "id_ed25519", ".npmrc", ".pypirc"
]

data = json.load(sys.stdin)
file_path = data.get("tool_input", {}).get("file_path", "")

basename = os.path.basename(file_path)
if basename in PROTECTED_FILES:
    print(json.dumps({
        "decision": "block",
        "reason": f"安全策略：禁止修改敏感文件 '{basename}'"
    }))
    sys.exit(2)

sys.exit(0)

#!/bin/bash
# ~/.claude/hooks/notify_on_stop.sh
# Agent 完成任务后发送通知

TASK_SUMMARY=$(cat | jq -r '.stop_reason // "unknown"')
WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

curl -s -X POST "$WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d "{\"text\":\"Claude Code 任务完成: $TASK_SUMMARY\n项目: $(basename $(pwd))\n时间: $(date)\"}" \
  > /dev/null 2>&1

exit 0

2.6 完整 settings.json 配置示例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 ~/.claude/hooks/block_dangerous_commands.py",
        "timeout": 5
      },
      {
        "matcher": "Write|Edit",
        "command": "python3 ~/.claude/hooks/protect_sensitive.py",
        "timeout": 5
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash ~/.claude/hooks/auto_format.sh",
        "timeout": 15
      }
    ],
    "Stop": [
      {
        "command": "bash ~/.claude/hooks/on_stop_run_tests.sh",
        "timeout": 60
      },
      {
        "command": "bash ~/.claude/hooks/notify_on_stop.sh",
        "timeout": 10
      }
    ],
    "SessionStart": [
      {
        "command": "bash ~/.claude/hooks/session_init.sh",
        "timeout": 10
      }
    ]
  }
}

第三部分：CI/CD 集成实战

3.1 GitHub Actions 集成

# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: AI Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取 PR 变更内容
          DIFF=$(git diff origin/main...HEAD)

          # 执行 AI 审查
          REVIEW=$(echo "$DIFF" | claude -p "
            你是一名高级代码审查员。请审查以下 PR 变更：

            重点关注：
            1. 安全漏洞（SQL注入、XSS、命令注入）
            2. 性能问题（N+1查询、内存泄漏）
            3. 代码风格和最佳实践
            4. 潜在的 Bug

            输出格式：
            - 严重程度：🔴 高 / 🟡 中 / 🟢 低
            - 文件和行号
            - 具体问题描述
            - 修复建议
          " --allowedTools "Read,Glob,Grep" --max-turns 5 --output-format text)

          # 将审查结果作为 PR 评论发布
          echo "$REVIEW" > review_comment.md

          # 使用 gh CLI 发表评论
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file review_comment.md \
            --edit-last || \
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file review_comment.md

3.2 自动修复 Lint 错误

# .github/workflows/auto-fix-lint.yml
name: Auto Fix Lint Errors

on:
  push:
    branches: [develop]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup
        run: |
          npm install -g @anthropic-ai/claude-code
          npm ci

      - name: Detect and Fix Lint Errors
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 运行 lint 获取错误
          LINT_OUTPUT=$(npm run lint 2>&1 || true)

          if echo "$LINT_OUTPUT" | grep -q "error"; then
            echo "$LINT_OUTPUT" | claude -p "
              以下是 lint 错误输出。请修复所有错误：

              \$LINT_OUTPUT

              修复规则：
              - 只修改必要的行，不做多余改动
              - 保持代码原有风格
              - 每个文件修复后确保语法正确
            " --allowedTools "Read,Edit,Write,Bash" --max-turns 20
          fi

      - name: Commit fixes
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "[email protected]"
          git diff --quiet || (git add -A && git commit -m "auto: fix lint errors [skip ci]" && git push)

3.3 批量代码迁移脚本

#!/bin/bash
# migrate-js-to-ts.sh — 批量将 JS 文件迁移为 TypeScript
# 用法: ./migrate-js-to-ts.sh src/

set -euo pipefail

TARGET_DIR="${1:-src}"
LOG_FILE="migration-$(date +%Y%m%d-%H%M%S).log"

echo "=== 开始 JS → TypeScript 迁移 ===" | tee "$LOG_FILE"

# 查找所有 JS 文件（排除 node_modules）
JS_FILES=$(find "$TARGET_DIR" -name "*.js" -o -name "*.jsx" | grep -v node_modules | head -20)

TOTAL=$(echo "$JS_FILES" | wc -l)
CURRENT=0

for file in $JS_FILES; do
    CURRENT=$((CURRENT + 1))
    echo "[$CURRENT/$TOTAL] 处理: $file" | tee -a "$LOG_FILE"

    # 确定目标文件名
    if [[ "$file" == *.jsx ]]; then
        TARGET="${file%.jsx}.tsx"
    else
        TARGET="${file%.js}.ts"
    fi

    # 使用 Claude Code 进行迁移
    claude -p "
        将以下 JavaScript 代码迁移为 TypeScript。

        要求：
        1. 添加完整的类型注解
        2. 为函数参数和返回值添加类型
        3. 定义必要的 interface 和 type
        4. 使用 ES module import/export
        5. 保持原有功能和逻辑不变

        输出完整的 TypeScript 代码，不要截断。
    " --allowedTools "Read,Write" --max-turns 3 \
      < "$file" 2>&1 | tee -a "$LOG_FILE"

    # 替换原文件
    if [ -f "$TARGET" ]; then
        echo "  ✓ 已生成: $TARGET" | tee -a "$LOG_FILE"
    fi
done

echo "=== 迁移完成，共处理 $CURRENT 个文件 ===" | tee -a "$LOG_FILE"

第四部分：Subagent 并行执行

4.1 Task 工具与 Subagent 架构

Claude Code 的 Task 工具是并行执行的核心。主 Agent（Leader）可以派生出多个 Subagent，每个 Subagent 独立处理子任务，最终将结果汇总。

4.2 内建 Subagent 类型

4.3 使用场景与模式

当你需要从多个维度调研代码库时，派生多个 Explore Subagent：

类型	用途	可用工具
`Explore`	快速搜索代码库	Read, Glob, Grep 等（不可写入）
`general-purpose`	通用多步骤任务	全部工具
`Plan`	架构设计和计划	全部工具（不可写入）

请并行调研以下三个方面：
1. 分析项目的认证模块架构
2. 查找所有数据库查询相关的代码
3. 梳理 API 端点的错误处理模式

使用 Task 工具同时派出3个 Explore 类型的 Subagent。

# 在 Claude Code 交互模式中
# 或通过 CLAUDE.md 中配置的指令

请并行实现以下三个独立功能：
1. 添加用户头像上传功能
2. 实现密码重置流程
3. 添加双因素认证支持

对每个功能使用 worktree 隔离的 Subagent。

对 src/ 目录下的所有控制器文件，并行执行以下任务：
1. 检查是否有缺失的输入验证
2. 验证错误处理是否完整
3. 确认是否有对应的单元测试

为每个文件派生一个 Subagent。

4.4 Headless 模式下的并行执行

#!/bin/bash
# parallel-review.sh — 并行代码审查

FILES=("src/api/auth.ts" "src/api/users.ts" "src/api/orders.ts" "src/utils/validators.ts")
PIDS=()
RESULTS_DIR="/tmp/claude-reviews"
mkdir -p "$RESULTS_DIR"

# Fan-out：并行启动多个 Claude Code 进程
for file in "${FILES[@]}"; do
    SAFE_NAME=$(echo "$file" | tr '/' '_')
    claude -p "审查文件 $file 的代码质量、安全性和性能问题。输出结构化的审查报告。" \
        --allowedTools "Read,Glob,Grep" \
        --max-turns 5 \
        > "$RESULTS_DIR/${SAFE_NAME}.md" &
    PIDS+=($!)
    echo "启动审查: $file (PID $!)"
done

# Fan-in：等待所有进程完成
echo "等待 ${#PIDS[@]} 个审查任务完成..."
for pid in "${PIDS[@]}"; do
    wait "$pid"
    echo "PID $pid 已完成 (退出码: $?)"
done

# 汇总结果
echo ""
echo "=== 审查汇总 ==="
for file in "${FILES[@]}"; do
    SAFE_NAME=$(echo "$file" | tr '/' '_')
    echo "--- $file ---"
    head -20 "$RESULTS_DIR/${SAFE_NAME}.md"
    echo ""
done

第五部分：Agent Teams 多实例编排

5.1 Agent Teams 概念

Agent Teams 是 Claude Code 的高级功能，允许多个独立的 Claude Code 实例作为一个团队协同工作。每个 Agent 拥有独立的终端会话，但共享任务列表和沟通通道。

5.2 Worktree 隔离机制

Git Worktree 是实现并行 Agent 无冲突工作的关键。每个 Agent 在独立的 worktree 目录中操作，互不干扰。

# Claude Code 内部自动管理 worktree
# 手动创建 worktree 示例：

# 为前端 Agent 创建 worktree
git worktree add ../project-frontend feature/frontend

# 为后端 Agent 创建 worktree
git worktree add ../project-backend feature/backend

# 每个目录中运行独立的 Claude Code 实例
cd ../project-frontend && claude -p "实现用户界面组件" &
cd ../project-backend && claude -p "实现 API 端点" &

5.3 实战：全栈功能并行开发

#!/bin/bash
# team-build.sh — Agent Teams 全栈并行开发

FEATURE_NAME="$1"
BASE_BRANCH=$(git branch --show-current)

if [ -z "$FEATURE_NAME" ]; then
    echo "用法: ./team-build.sh <功能名称>"
    exit 1
fi

echo "=== 启动 Agent Teams 开发: $FEATURE_NAME ==="

# 创建 worktrees
git worktree add ".claude/worktrees/frontend" "feat/${FEATURE_NAME}-frontend" 2>/dev/null || \
    git worktree add ".claude/worktrees/frontend" -b "feat/${FEATURE_NAME}-frontend" HEAD

git worktree add ".claude/worktrees/backend" "feat/${FEATURE_NAME}-backend" 2>/dev/null || \
    git worktree add ".claude/worktrees/backend" -b "feat/${FEATURE_NAME}-backend" HEAD

git worktree add ".claude/worktrees/tests" "feat/${FEATURE_NAME}-tests" 2>/dev/null || \
    git worktree add ".claude/worktrees/tests" -b "feat/${FEATURE_NAME}-tests" HEAD

# 并行启动三个 Agent
claude -p "
你是前端开发 Agent。功能需求：$FEATURE_NAME。
请实现前端组件和页面，包括：
1. React 组件实现
2. 样式文件
3. 前端类型定义
" --allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
  --max-turns 25 \
  --output-format json \
  > /tmp/frontend-result.json &

PID_FRONTEND=$!

claude -p "
你是后端开发 Agent。功能需求：$FEATURE_NAME。
请实现后端 API 和数据层，包括：
1. API 路由和处理器
2. 数据库模型和迁移
3. 输入验证
" --allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
  --max-turns 25 \
  --output-format json \
  > /tmp/backend-result.json &

PID_BACKEND=$!

# 等待前端和后端完成后再启动测试 Agent
wait $PID_FRONTEND $PID_BACKEND

# 合并代码到测试 worktree
# ... (此处省略合并逻辑)

claude -p "
你是 QA Agent。功能需求：$FEATURE_NAME。
前端和后端代码已完成。请编写：
1. 单元测试
2. 集成测试
3. E2E 测试
确保覆盖核心功能路径和边界情况。
" --allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
  --max-turns 20 \
  --output-format json \
  > /tmp/tests-result.json

echo "=== Agent Teams 开发完成 ==="
echo "前端结果: /tmp/frontend-result.json"
echo "后端结果: /tmp/backend-result.json"
echo "测试结果: /tmp/tests-result.json"

# 清理 worktrees（可选）
# git worktree remove .claude/worktrees/frontend
# git worktree remove .claude/worktrees/backend
# git worktree remove .claude/worktrees/tests

第六部分：完整实战案例 — 自动化代码质量门禁

6.1 项目结构

my-project/
├── .claude/
│   ├── settings.json          # Hooks 配置
│   ├── hooks/
│   │   ├── block_dangerous.py # 危险命令拦截
│   │   ├── auto_format.sh     # 自动格式化
│   │   ├── run_tests.sh       # 自动测试
│   │   └── notify.sh          # 通知脚本
│   └── CLAUDE.md              # 项目级指令
├── scripts/
│   ├── batch-review.sh        # 批量审查
│   ├── parallel-analyze.sh    # 并行分析
│   └── team-build.sh          # Agent Teams
├── .github/
│   └── workflows/
│       ├── ai-review.yml      # AI 代码审查
│       └── auto-fix.yml       # 自动修复
└── src/

6.2 一键质量门禁脚本

#!/bin/bash
# quality-gate.sh — 一键代码质量门禁
# 集成 Hooks + Headless + Subagent 并行

set -euo pipefail

echo "🔍 Claude Code 代码质量门禁"
echo "=============================="

# 阶段 1：并行分析（Fan-Out）
echo ""
echo "📊 阶段 1/3：并行分析"

# 同时启动三个分析任务
ANALYSIS_DIR="/tmp/quality-gate-$$"
mkdir -p "$ANALYSIS_DIR"

claude -p "分析代码库的安全问题。检查：SQL注入、XSS、CSRF、命令注入、硬编码密钥。输出 JSON 格式的发现列表。" \
  --allowedTools "Read,Glob,Grep" --max-turns 10 \
  --output-format json > "$ANALYSIS_DIR/security.json" &
PID_SECURITY=$!

claude -p "分析代码库的性能问题。检查：N+1查询、内存泄漏、不必要的重渲染、大循环。输出结构化报告。" \
  --allowedTools "Read,Glob,Grep" --max-turns 10 \
  --output-format json > "$ANALYSIS_DIR/performance.json" &
PID_PERF=$!

claude -p "分析代码库的架构质量。检查：循环依赖、上帝类、过度耦合、缺失的抽象。输出改进建议。" \
  --allowedTools "Read,Glob,Grep" --max-turns 10 \
  --output-format json > "$ANALYSIS_DIR/architecture.json" &
PID_ARCH=$!

# 等待所有分析完成
wait $PID_SECURITY $PID_PERF $PID_ARCH
echo "  ✓ 安全分析完成"
echo "  ✓ 性能分析完成"
echo "  ✓ 架构分析完成"

# 阶段 2：生成综合报告
echo ""
echo "📋 阶段 2/3：生成综合报告"

claude -p "
基于以下三份分析报告，生成一份综合质量报告。

安全报告: $(cat "$ANALYSIS_DIR/security.json" | jq -r '.result' 2>/dev/null || echo '无数据')
性能报告: $(cat "$ANALYSIS_DIR/performance.json" | jq -r '.result' 2>/dev/null || echo '无数据')
架构报告: $(cat "$ANALYSIS_DIR/architecture.json" | jq -r '.result' 2>/dev/null || echo '无数据')

报告格式：
1. 执行摘要（通过/不通过）
2. 严重问题清单（按优先级排序）
3. 改进建议
4. 质量评分（0-100）
" --max-turns 3 > "$ANALYSIS_DIR/final-report.md"

echo "  ✓ 综合报告已生成"

# 阶段 3：决策
echo ""
echo "🚦 阶段 3/3：质量门禁决策"

SCORE=$(claude -p "阅读以下质量报告，仅输出一个0-100的数字分数。" \
  --max-turns 1 < "$ANALYSIS_DIR/final-report.md")

echo ""
echo "=============================="
echo "质量评分: $SCORE / 100"

if [ "$SCORE" -ge 80 ]; then
    echo "✅ 门禁通过 — 代码质量合格"
    cat "$ANALYSIS_DIR/final-report.md"
    exit 0
elif [ "$SCORE" -ge 60 ]; then
    echo "⚠️ 门禁警告 — 存在需要改进的问题"
    cat "$ANALYSIS_DIR/final-report.md"
    exit 0
else
    echo "❌ 门禁未通过 — 存在严重质量问题"
    cat "$ANALYSIS_DIR/final-report.md"
    exit 1
fi

6.3 工作流全景图

第七部分：成本控制与最佳实践

7.1 Token 消耗优化策略

7.2 模型选择决策树

7.3 安全最佳实践清单

7.4 调试技巧

策略	具体做法	预估节省
限制工具范围	`--allowedTools "Read,Grep"` 替代全量	30-50%
限制轮次	`--max-turns 5` 防止循环	20-40%
精确提示	"审查 auth.ts 的 SQL 注入" 而非 "审查代码"	30-50%
使用小模型	简单任务用 `--model claude-haiku-4-5`	80-90%
缓存会话	`--resume` 复用已有上下文	40-60%
截取输入	`head -n 50 file \\| claude -p`	50-70%

# 查看详细日志
claude -p "分析代码" --verbose 2>claude-debug.log

# 检查 Hook 执行情况
# Hook 的 stderr 会被记录到 Claude Code 日志中
tail -f ~/.claude/logs/hooks.log

# 测试单个 Hook
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | \
  python3 ~/.claude/hooks/block_dangerous_commands.py
echo "退出码: $?"

# 模拟 Headless 运行（不消耗 Token）
claude -p "测试提示" --dry-run

概述

前置条件

第一部分：Headless 非交互模式（`-p` 标志）

1.1 核心概念

1.2 基础用法

1.3 输出格式控制

1.4 工具权限控制

1.5 会话恢复（Session Resume）

1.6 常见问题与解决

第二部分：Hooks 生命周期钩子

2.1 什么是 Hooks

2.2 五大 Hook 事件

2.3 配置方式

2.4 Hook 输入输出协议

2.5 实战：六个生产级 Hook 示例

2.6 完整 settings.json 配置示例

第三部分：CI/CD 集成实战

3.1 GitHub Actions 集成

3.2 自动修复 Lint 错误

3.3 批量代码迁移脚本

第四部分：Subagent 并行执行

4.1 Task 工具与 Subagent 架构

4.2 内建 Subagent 类型

4.3 使用场景与模式

4.4 Headless 模式下的并行执行

第五部分：Agent Teams 多实例编排

5.1 Agent Teams 概念

5.2 Worktree 隔离机制

5.3 实战：全栈功能并行开发

第六部分：完整实战案例 — 自动化代码质量门禁

6.1 项目结构

6.2 一键质量门禁脚本

6.3 工作流全景图

第七部分：成本控制与最佳实践

7.1 Token 消耗优化策略

7.2 模型选择决策树

7.3 安全最佳实践清单

7.4 调试技巧

延伸阅读

参考来源

概述

前置条件

第一部分：Headless 非交互模式（-p 标志）

1.1 核心概念

1.2 基础用法

1.3 输出格式控制

1.4 工具权限控制

1.5 会话恢复（Session Resume）

1.6 常见问题与解决

第二部分：Hooks 生命周期钩子

2.1 什么是 Hooks

2.2 五大 Hook 事件

2.3 配置方式

2.4 Hook 输入输出协议

2.5 实战：六个生产级 Hook 示例

2.6 完整 settings.json 配置示例

第三部分：CI/CD 集成实战

3.1 GitHub Actions 集成

3.2 自动修复 Lint 错误

3.3 批量代码迁移脚本

第四部分：Subagent 并行执行

4.1 Task 工具与 Subagent 架构

4.2 内建 Subagent 类型

4.3 使用场景与模式

4.4 Headless 模式下的并行执行

第五部分：Agent Teams 多实例编排

5.1 Agent Teams 概念

5.2 Worktree 隔离机制

5.3 实战：全栈功能并行开发

第六部分：完整实战案例 — 自动化代码质量门禁

6.1 项目结构

6.2 一键质量门禁脚本

6.3 工作流全景图

第七部分：成本控制与最佳实践

7.1 Token 消耗优化策略

7.2 模型选择决策树

7.3 安全最佳实践清单

7.4 调试技巧

延伸阅读

参考来源

📎 本分类最新文章

第一部分：Headless 非交互模式（`-p` 标志）