## 概述 本教程系统讲解 Claude Code 的三大自动化能力：**Headless 非交互模式（`-p`）、Hooks 生命周期钩子、多 Agent 并行编排**。学完后你将能够在 CI/CD 流水线中集成 Claude Code、用 Hooks 构建自动化的开发护栏、用 Subagent 和 Agent Teams 实现并行批量任务处理。适合有一定 Claude Code 使用经验、希望将 AI 编码能力嵌入自动化工作流的中高级开发者。 ## 前置条件 - 已安装 Claude Code CLI（`npm install -g @anthropic-ai/claude-code`） - 拥有 Anthropic API Key 或 Claude Pro/Max 订阅 - 熟悉命令行操作和 Shell 脚本 - 了解 Git 基本操作 - 一个可用的项目代码库用于实战演练 --- ## 第一部分：Headless 非交互模式（`-p` 标志） ### 1.1 核心概念 Claude Code 的 `-p`（`--print`）标志是其自动化的基石。与交互式 REPL 模式不同，`-p` 模式接收提示后直接执行并退出，将结果输出到 stdout——这正是脚本和流水线所需的行为。  > *图表 1* ### 1.2 基础用法 **直接传参模式**：最简单的用法，将提示作为命令行参数传入。 ```bash # 单行提示 claude -p "解释 src/utils.ts 中 formatDate 函数的作用" # 指定模型 claude -p "重构这个函数" --model claude-sonnet-4-20250514 # 限制最大对话轮次（防止 Agent 循环） claude -p "修复所有 lint 错误" --max-turns 10 ``` **管道输入模式**：将文件内容或命令输出通过管道传给 Claude Code。 ```bash # 审查代码 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 的输出可以被程序解析，这是自动化集成的关键。 ```bash # JSON 格式 — 适合程序解析 claude -p "列出所有 TODO 注释" --output-format json # 流式 JSON — 适合实时展示 claude -p "重构这段代码" --output-format stream-json # 纯文本（默认） claude -p "解释这段代码" --output-format text ``` JSON 输出结构示例： ```json { "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 能做什么。 ```bash # 只允许读取文件和搜索，不允许修改 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 ``` **工具权限分级表**： | 权限级别 | 允许的工具 | 适用场景 | |---------|-----------|---------| | 只读审计 | `Read,Glob,Grep` | 代码审查、架构分析 | | 安全编辑 | `Read,Write,Edit` | 文档生成、代码格式化 | | 标准开发 | `+Bash` | 修复 bug、实现功能 | | 完全自主 | `--dangerously-skip-permissions` | CI/CD 自动修复（需沙箱） | ### 1.5 会话恢复（Session Resume） 自动化流程中经常需要在上一次对话基础上继续工作。Claude Code 提供两种会话恢复机制。 ```bash # --continue：继续最近一次会话 claude -p "继续修改测试文件" --continue # --resume：恢复指定会话（通过 session_id） claude -p "基于之前的分析继续" --resume abc123-def456 # 结合使用：恢复会话并追加指令 claude -p "在上次的基础上添加错误处理" \ --resume abc123-def456 \ --max-turns 10 ``` **会话恢复在批处理中的应用**： ```bash #!/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 常见问题与解决 | 问题 | 原因 | 解决方案 | |------|------|---------| | 输出包含 ANSI 转义码 | 终端颜色干扰 | 加 `--no-color` 或用 `--output-format json` | | Agent 无限循环 | 提示过于宽泛 | 设置 `--max-turns` 限制 | | 权限被拒绝 | 工具未授权 | 检查 `--allowedTools` 配置 | | 超时退出 | API 调用耗时过长 | 在脚本中设置 `timeout` 命令 | | Token 用尽 | 大文件导致上下文溢出 | 使用 `cat file | head -n 100` 截取 | --- ## 第二部分：Hooks 生命周期钩子 ### 2.1 什么是 Hooks Hooks 是 Claude Code 的**事件驱动自动化层**。通过在 `settings.json` 中配置 shell 命令，可以在特定生命周期事件触发时自动执行自定义逻辑——无需人工干预。这是将 AI 编码流程从"手动操作"升级为"自动治理"的关键机制。  > *图表 2* ### 2.2 五大 Hook 事件 | 事件 | 触发时机 | 典型用途 | |------|---------|---------| | `PreToolUse` | 每次工具调用**之前** | 安全拦截、参数校验、权限控制 | | `PostToolUse` | 每次工具调用**之后** | 自动格式化、日志记录、通知推送 | | `Notification` | Claude 需要通知用户时 | Slack/钉钉消息转发 | | `Stop` | Agent 停止生成时 | 自动测试、质量检查、结果汇总 | | `SessionStart` | 会话初始化时 | 环境准备、上下文注入 | ### 2.3 配置方式 Hooks 在 `settings.json` 中配置（位于 `~/.claude/settings.json` 或项目的 `.claude/settings.json`）。 ```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 } ] } } ``` **配置字段说明**： - `matcher`：正则匹配工具名称。`"Bash"` 匹配 Bash 工具，`"Write|Edit"` 匹配写入或编辑操作，省略则匹配所有工具 - `command`：要执行的 shell 命令 - `timeout`：超时时间（秒），超时后 Hook 被跳过 ### 2.4 Hook 输入输出协议 Hook 通过 **stdin** 接收 JSON 格式的事件数据，通过 **stdout** 返回 JSON 格式的响应，通过**退出码**控制行为。 **Hook 输入示例（PreToolUse）**： ```json { "session_id": "abc123", "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/old-build", "description": "清理旧构建目录" } } ``` **Hook 输出与退出码**： | 退出码 | 含义 | 行为 | |-------|------|------| | 0 | 通过 | 正常执行工具 | | 2 | 阻止 | 阻止工具调用，将 stdout 作为反馈展示给 Agent | 当退出码为 2 时，stdout 中的 JSON 会被反馈给 Agent： ```json { "decision": "block", "reason": "禁止执行 rm -rf 命令。请改用更安全的删除方式。" } ``` ### 2.5 实战：六个生产级 Hook 示例 **Hook 1：禁止危险命令** ```python #!/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) ``` **Hook 2：自动代码格式化** ```bash #!/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 ``` **Hook 3：SessionStart 环境初始化** ```bash #!/bin/bash # ~/.claude/hooks/session_init.sh # 在新会话开始时注入项目上下文 PROJECT_DIR=$(pwd) BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") cat </dev/null | head -5) 最近提交: $(git log --oneline -3 2>/dev/null) EOF exit 0 ``` **Hook 4：Stop 事件自动测试** ```bash #!/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 ``` **Hook 5：敏感文件保护** ```python #!/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) ``` **Hook 6：Slack/钉钉通知** ```bash #!/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 配置示例 ```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 集成 ```yaml # .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 错误 ```yaml # .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 "claude-bot@users.noreply.github.com" git diff --quiet || (git add -A && git commit -m "auto: fix lint errors [skip ci]" && git push) ``` ### 3.3 批量代码迁移脚本 ```bash #!/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 独立处理子任务，最终将结果汇总。  > *图表 3* ### 4.2 内建 Subagent 类型 | 类型 | 用途 | 可用工具 | |------|------|---------| | `Explore` | 快速搜索代码库 | Read, Glob, Grep 等（不可写入） | | `general-purpose` | 通用多步骤任务 | 全部工具 | | `Plan` | 架构设计和计划 | 全部工具（不可写入） | ### 4.3 使用场景与模式 **模式 1：并行研究（Research Fan-Out）** 当你需要从多个维度调研代码库时，派生多个 Explore Subagent： ``` 请并行调研以下三个方面： 1. 分析项目的认证模块架构 2. 查找所有数据库查询相关的代码 3. 梳理 API 端点的错误处理模式 使用 Task 工具同时派出3个 Explore 类型的 Subagent。 ``` **模式 2：并行开发（Development Fan-Out with Worktree）** 当多个独立功能需要同时开发时，使用 worktree 隔离： ```bash # 在 Claude Code 交互模式中 # 或通过 CLAUDE.md 中配置的指令 请并行实现以下三个独立功能： 1. 添加用户头像上传功能 2. 实现密码重置流程 3. 添加双因素认证支持 对每个功能使用 worktree 隔离的 Subagent。 ``` **模式 3：批处理自动化** ``` 对 src/ 目录下的所有控制器文件，并行执行以下任务： 1. 检查是否有缺失的输入验证 2. 验证错误处理是否完整 3. 确认是否有对应的单元测试 为每个文件派生一个 Subagent。 ``` ### 4.4 Headless 模式下的并行执行 在脚本中使用多个后台进程模拟并行： ```bash #!/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 拥有独立的终端会话，但共享任务列表和沟通通道。  > *图表 4* ### 5.2 Worktree 隔离机制 Git Worktree 是实现并行 Agent 无冲突工作的关键。每个 Agent 在独立的 worktree 目录中操作，互不干扰。 ```bash # 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 实战：全栈功能并行开发 以下脚本展示如何用 Agent Teams 模式并行开发一个全栈功能： ```bash #!/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 一键质量门禁脚本 ```bash #!/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 工作流全景图  > *图表 5* --- ## 第七部分：成本控制与最佳实践 ### 7.1 Token 消耗优化策略 | 策略 | 具体做法 | 预估节省 | |------|---------|---------| | 限制工具范围 | `--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% | ### 7.2 模型选择决策树  > *图表 6* ### 7.3 安全最佳实践清单 - [ ] 永远不要在命令行参数中传递 API Key（使用环境变量） - [ ] CI/CD 中使用 `--allowedTools` 限制最小权限 - [ ] 设置 `--max-turns` 防止无限循环消耗 Token - [ ] 使用 PreToolUse Hook 拦截危险操作 - [ ] 保护 `.env` 和 `credentials` 文件（PostToolUse Hook） - [ ] 在沙箱环境（Docker 容器）中运行完全自主模式 - [ ] 定期审计 `~/.claude/settings.json` 中的 Hook 配置 - [ ] 使用 `--output-format json` 便于日志记录和审计 ### 7.4 调试技巧 ```bash # 查看详细日志 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 ``` --- ## 延伸阅读 - [Claude Code 官方文档 — Headless 模式](https://code.claude.com/docs/en/headless) — Anthropic 官方非交互模式指南 - [Claude Code 官方文档 — Hooks 参考](https://code.claude.com/docs/en/hooks) — Hook 事件、配置 schema 和 JSON 协议 - [Claude Code 官方文档 — Agent Teams](https://code.claude.com/docs/en/agent-teams) — 多 Agent 协作编排 - [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code) — 源码和 issue 追踪 - [Trail of Bits — Claude Code 配置最佳实践](https://deepwiki.com/trailofbits/claude-code-config) — 安全配置模板 ## 参考来源 1. [Run Claude Code programmatically — Claude Code Docs](https://code.claude.com/docs/en/headless) — 官方 Headless 模式和 Agent SDK 文档 2. [Hooks reference — Claude Code Docs](https://code.claude.com/docs/en/hooks) — Hook 事件类型、JSON 协议和配置 schema 参考 3. [Claude Code Hooks: The Automation Layer Nobody Knows About — dev.to](https://dev.to/whoffagents/claude-code-hooks-the-automation-layer-nobody-knows-about-3po0) — PreToolUse/PostToolUse 实战案例 4. [Headless Claude in CI: Using -p and --max-turns — agentpatterns.ai](https://agentpatterns.ai/workflows/headless-claude-ci/) — CI/CD 中的 Headless 模式配置模式 5. [Claude Code Subagents: A 2026 Practical Guide — Tembo](https://www.tembo.io/blog/claude-code-subagents) — Subagent 并行执行和 fan-out/fan-in 模式 > [!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 等场景全覆盖。