1. CLI 进阶概览

如果你已经掌握了 Series 5：CLI 基础的 7 个核心命令和 24 个标志，本篇将深入企业级和工程化场景：

  • CI/CD 集成：自动化代码审查、测试生成、部署流程
  • 批量处理：同时处理多个任务、多个文件、多个项目
  • 环境变量与安全：凭证管理、权限隔离、加密存储
  • 远程与分布式：远程执行、云端编织、团队协作
  • 性能优化：缓存、上下文管理、成本控制
  • 日志与可观测性：调试、监控、告警
  • 脚本化与编排：编写自动化脚本、与 CI 工具集成

2. CI/CD 集成

2.1 GitHub Actions 集成

场景：每次 PR 创建时自动生成测试代码

# .github/workflows/claude-code-tests.yml
name: Auto-generate Tests with Claude Code

on:
  pull_request:
    paths:
      - 'src/**/*.ts'

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Claude Code
        run: |
          npm install -g claude-code
          claude auth set --api-key ${{ secrets.CLAUDE_API_KEY }}
      
      - name: Generate tests
        run: |
          claude --model opus --effort max << EOF
          给这个 PR 中修改的所有文件生成单元测试。
          重点：
          1. 覆盖边界情况
          2. 测试错误处理
          3. 遵循项目风格
          EOF
      
      - name: Create PR with tests
        uses: peter-evans/create-pull-request@v5
        with:
          commit-message: 'test: auto-generated tests by Claude Code'
          title: 'Auto-generated tests for PR #${{ github.event.pull_request.number }}'
          body: '自动生成的单元测试，请审查并调整。'

2.2 GitLab CI 集成

# .gitlab-ci.yml
stages:
  - review
  - test

code-review:
  stage: review
  script:
    - claude --api-key $CLAUDE_API_KEY << EOF
      审查最近的 git diff，重点检查安全问题。
      输出格式：Markdown 注释，可直接发送到 Merge Request。
      EOF

auto-test:
  stage: test
  script:
    - claude --model sonnet --effort balanced mkdir test-reports
    - claude --agent test-generator
  artifacts:
    paths:
      - test-reports/

2.3 Jenkins 集成

// Jenkinsfile
pipeline {
  agent any
  
  stages {
    stage('Claude Code Review') {
      steps {
        withCredentials([string(credentialsId: 'claude-api-key', variable: 'CLAUDE_KEY')]) {
          sh '''
            export CLAUDE_API_KEY=$CLAUDE_KEY
            claude --model opus << EOF
            审查 src/ 目录的改动，给出修复建议。
            EOF
          '''
        }
      }
    }
    
    stage('Auto-fix') {
      steps {
        sh 'claude --agent code-formatter'
      }
    }
  }
}

3. 批量处理与并行执行

3.1 并行任务

不要顺序执行多个任务；用 & 并行化：

# ❌ 顺序执行（9 分钟）
claude --agent code-reviewer
claude --agent security-reviewer
claude --agent test-generator

# ✅ 并行执行（3 分钟）
claude --agent code-reviewer &
claude --agent security-reviewer &
claude --agent test-generator &
wait  # 等待所有后台任务完成

3.2 批量文件处理

用 find + xargs 遍历文件：

# 对所有 Python 文件生成文档
find src -name "*.py" | xargs -I {} sh -c '
  echo "Processing {}"
  claude --effort low << EOF
  为这个 Python 模块生成 docstring：
  $(cat {})
  EOF
'

# 对所有 TypeScript 文件进行类型检查
find src -name "*.ts" -not -path "*/node_modules/*" | \
  xargs -P 4 -I {} claude --agent typescript-analyzer {}

3.3 监听文件变化自动执行

用 entr 或 watchman：

# 监听 src/ 目录，一旦文件改动就运行 Claude Code
find src -type f | entr -r sh -c '
  claude --agent code-formatter
  claude --agent type-checker
  npm test
'

4. 环境变量与安全

4.1 凭证管理最佳实践

# ❌ 不要硬编码
claude --api-key sk-ant-xxx

# ✅ 用环境变量
export CLAUDE_API_KEY=sk-ant-xxx
claude

# ✅ 用 .env 文件（不提交到 Git）
cat >> .env << EOF
CLAUDE_API_KEY=sk-ant-xxx
CLAUDE_MODEL=opus
CLAUDE_EFFORT=max
GITHUB_TOKEN=ghp_xxx
SENTRY_TOKEN=xxx
EOF

# 加载 .env
export $(cat .env | xargs)

# ✅ 用密钥管理工具
export CLAUDE_API_KEY=$(vault kv get -field=key secret/claude)
export GITHUB_TOKEN=$(vault kv get -field=token secret/github)

4.2 权限隔离

# 创建权限最小的上下文
claude \
  --allowedTools "Read,Bash(git *)" \
  >> Run as read-only agent
  
# 为 CI/CD 创建专用 API key
# (从 Anthropic 控制面板创建)
export CLAUDE_CI_KEY=sk-ant-ci-xxx
export CLAUDE_API_KEY=$CLAUDE_CI_KEY

# 限制能访问的项目
export CLAUDE_PROJECT_ROOT=/safe/project/path

4.3 敏感数据脱敏

# 在发送给 Claude 前脱敏敏感数据
cat sensitive-logs.txt | \
  sed 's/[0-9]\{4\}-[0-9]\{4\}-[0-9]\{4\}-[0-9]\{4\}/CARD-REDACTED/g' | \
  sed 's/\b[a-zA-Z0-9._%+-]\+@[a-zA-Z0-9.-]\+\.[a-zA-Z]\{2,\}\b/EMAIL-REDACTED/g' | \
  claude --effort low << EOF
  找出这些日志中的错误模式。
  EOF

5. 高级环境变量配置

变量说明示例
CLAUDE_API_KEYAPI 密钥sk-ant-xxx
CLAUDE_MODEL默认模型opus/sonnet/haiku
CLAUDE_EFFORT默认努力级别low/balanced/max
CLAUDE_PROJECT_ROOT项目根目录/path/to/project
CLAUDE_TIMEOUT任务超时（毫秒）600000
CLAUDE_DEBUG启用调试日志1
CLAUDE_SKIP_HOOKS跳过所有 Hooks1
CLAUDE_LOG_LEVEL日志级别debug/info/warn/error
CLAUDE_DISABLE_ANALYTICS禁用分析1

6. 远程与分布式执行

6.1 远程主机执行

# 在远程服务器上运行 Claude Code
ssh user@remote-server << 'EOF'
  cd /path/to/project
  export CLAUDE_API_KEY=$CLAUDE_KEY
  claude --model opus --effort max << TASK
  分析 logs/ 目录中最近 24 小时的错误模式。
  TASK
EOF

6.2 容器化执行

# Dockerfile
FROM node:18-alpine

RUN npm install -g claude-code

WORKDIR /app
COPY . .

ENV CLAUDE_API_KEY=${CLAUDE_API_KEY}
ENV CLAUDE_MODEL=sonnet

CMD ["claude", "--effort", "balanced"]
# 运行
docker run --env CLAUDE_API_KEY=$CLAUDE_API_KEY \
  -v $(pwd):/app \
  my-claude-app

6.3 Kubernetes Job

# claude-code-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: claude-code-analysis
spec:
  template:
    spec:
      containers:
      - name: claude
        image: my-claude-app:latest
        env:
        - name: CLAUDE_API_KEY
          valueFrom:
            secretKeyRef:
              name: claude-secrets
              key: api-key
        volumeMounts:
        - name: code
          mountPath: /app
      volumes:
      - name: code
        hostPath:
          path: /path/to/code
      restartPolicy: Never

7. 日志与调试

7.1 启用调试模式

# 输出详细日志
export CLAUDE_DEBUG=1
claude --model opus

# 指定日志级别
export CLAUDE_LOG_LEVEL=debug
claude --agent code-reviewer

7.2 日志查看与分析

# 查看最近的日志
tail -f ~/.claude/logs/claude-*.log

# 搜索特定错误
grep -i "error" ~/.claude/logs/*.log

# 分析日志统计
cat ~/.claude/logs/*.log | \
  grep "took" | \
  sed 's/.*took //; s/ms.*//' | \
  awk '{sum+=$1; count++} END {print "Average:", sum/count, "ms"}'

7.3 结构化日志输出

# 以 JSON 格式输出日志
export CLAUDE_LOG_FORMAT=json
claude --model sonnet 2>&1 | jq '.level, .message'

# 与日志聚合工具集成（如 ELK）
claude --model opus 2>&1 | \
  jq -R 'split("|") | {timestamp: .[0], level: .[1], message: .[2:] | join("|")}' | \
  curl -X POST http://localhost:9200/claude-logs/_doc -d @-

8. 脚本化与编排

8.1 Bash 脚本编排

#!/bin/bash
# claude-workflow.sh

set -euo pipefail  # 严格模式

PROJECT_ROOT=$(cd "$(dirname "$0")" && pwd)
LOG_FILE="$PROJECT_ROOT/claude-workflow.log"

log() {
  echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

# 1. 代码审查
log "Starting code review..."
claude --agent code-reviewer > "$PROJECT_ROOT/review-report.md" 2>&1

# 2. 生成测试
log "Generating tests..."
claude --agent test-generator > "$PROJECT_ROOT/tests-generated.ts" 2>&1

# 3. 类型检查
log "Running type check..."
claude --agent typescript-analyzer > "$PROJECT_ROOT/type-report.md" 2>&1

# 4. 生成文档
log "Generating docs..."
claude --agent doc-generator > "$PROJECT_ROOT/API.md" 2>&1

log "Workflow completed!"

8.2 Python 脚本与 CLI 集成

#!/usr/bin/env python3
import subprocess
import json
from pathlib import Path

def run_claude(task: str, agent: str = None) -> dict:
    """Execute Claude Code via CLI and return structured output"""
    cmd = ['claude']
    
    if agent:
        cmd.extend(['--agent', agent])
    
    result = subprocess.run(
        cmd,
        input=task,
        capture_output=True,
        text=True
    )
    
    return {
        'returncode': result.returncode,
        'stdout': result.stdout,
        'stderr': result.stderr
    }

# 批量代码审查
project_files = list(Path('src').glob('**/*.ts'))

for file in project_files:
    print(f"Reviewing {file}...")
    result = run_claude(
        task=f"审查这个文件：{file.read_text()}",
        agent="code-reviewer"
    )
    
    if result['returncode'] == 0:
        print(f"✅ {file}")
        with open(f"{file}.review.md", 'w') as f:
            f.write(result['stdout'])
    else:
        print(f"❌ {file}: {result['stderr']}")

8.3 Makefile 编排

.PHONY: review test docs lint format

review:
    claude --agent code-reviewer

test:
    claude --agent test-generator

docs:
    claude --agent doc-generator

lint:
    claude --agent style-checker

format:
    claude --agent code-formatter

all: review test docs lint
    @echo "All tasks completed!"

注意：实际 Makefile 文件中，需要用硬制表符（Tab）而不是空格。

运行：

make all
# 或并行执行
make -j 4 review test docs

9. 性能优化

9.1 上下文缓存

# 用 -c 参数继续之前的对话（重用上下文）
claude -c << EOF
代码审查。
EOF

# 查看缓存统计
export CLAUDE_DEBUG=1
claude -c  # 输出缓存命中率

9.2 模型选择优化

#!/bin/bash

# 快速任务用 Haiku（便宜）
if [ "${1}" = "quick" ]; then
  export CLAUDE_MODEL=haiku
  export CLAUDE_EFFORT=low
fi

# 复杂任务用 Opus（准确）
if [ "${1}" = "complex" ]; then
  export CLAUDE_MODEL=opus
  export CLAUDE_EFFORT=max
fi

claude "$2"

使用：

./smart-claude.sh quick "快速代码检查"
./smart-claude.sh complex "架构设计评审"

9.3 增量处理

不重复处理已完成的文件：

#!/bin/bash

PROCESSED_FILE=".claude-processed-files"

for file in $(find src -name "*.ts"); do
  if ! grep -q "$file" "$PROCESSED_FILE"; then
    echo "Processing $file..."
    claude << EOF
    生成这个文件的文档：
    $(cat "$file")
    EOF
    
    echo "$file" >> "$PROCESSED_FILE"
  fi
done

10. 超级命令示例

一键代码仓库诊断

#!/bin/bash
# diagnose-repo.sh

echo "=== Claude Code Repository Diagnosis ==="

claude << 'DIAGNOSIS'
诊断这个代码仓库：

1. 架构分析：主要模块和职责
2. 代码质量：最严重的技术债务
3. 安全审查：潜在的安全问题
4. 性能分析：可以改进的瓶颈
5. 推荐优先级：哪些改进应该先做

输出格式：Markdown，可直接用于 README
DIAGNOSIS

# 生成可视化报告
echo "---" >> DIAGNOSIS.md
echo "Generated at: $(date)" >> DIAGNOSIS.md

智能 PR 助手

#!/bin/bash
# review-pr.sh <PR_NUMBER>

PR_NUMBER=$1
REPO="owner/repo"

# 下载 PR diff
gh pr diff $PR_NUMBER > /tmp/pr.diff

claude --model opus << EOF
审查这个 GitHub PR：

**PR #$PR_NUMBER**
$(gh pr view $PR_NUMBER --json title,body -q '.title + "\n" + .body')

**改动内容：**
$(cat /tmp/pr.diff)

请提供：
1. 代码质量反馈
2. 安全隐患
3. 性能建议
4. 给维护者的最终评分（👍/👎）
EOF

11. 故障排除与最佳实践

11.1 常见 CLI 错误

错误原因解决
API key invalid过期或错误的密钥重新生成 API key
Timeout任务太久增加 -t 或拆分任务
Permission denied文件权限问题chmod +x 脚本
Command not found未安装或路径错误which claude 检查路径

11.2 最佳实践清单

  • 用环境变量管理凭证，不硬编码
  • 为关键任务用 --effort max
  • 大任务用 --agent 隔离上下文
  • CI/CD 中用 --bare 简化输出
  • 本地开发用 CLAUDE_DEBUG=1 调试
  • 生产用 CLAUDE_LOG_LEVEL=error 减少日志
  • 定期检查 ~/.claude/logs/ 找性能瓶颈
  • 用脚本化确保重复工作的一致性

12. 参考资源

下一步：掌握了 CLI 进阶后，结合 Series 0-11 的所有功能（记忆、Skills、Hooks、MCP、Plugins 等），你已经具备构建完整 AI 工程化工作流的所有工具。🚀