Claude Code 通关手册（八）：你还在跟 AI 聊天？高手早就用代码驱动了

claude -p "分析 src/app/page.tsx 的性能问题"

# 默认：纯文本输出（适合人类阅读）
claude -p "列出项目中的 TODO 注释" --output-format text

# JSON：结构化输出（适合程序解析）
claude -p "列出项目中的 TODO 注释" --output-format json

# Stream JSON：逐条消息流式输出（适合实时处理）
claude -p "重构 ArticleList 组件" --output-format stream-json

# 提取 JSON 中的文本内容
claude -p "检查 package.json 中有没有过期的依赖" \
  --output-format json | jq -r '.result'

claude -p "你的指令" \
  --output-format json \        # 输出格式：text / json / stream-json
  --max-turns 3 \               # 最大执行轮次（控制成本）
  --allowedTools Read,Grep \    # 限制可用工具（安全）
  --model sonnet                # 指定模型

#!/bin/bash
# review-recent.sh — 批量审查最近修改的文件

OUTPUT_FILE="review-report.json"
echo"[]" > "$OUTPUT_FILE"

for file in $(git diff --name-only HEAD~5 -- '*.ts''*.tsx'); do
echo"🔍 审查: $file"

  result=$(claude -p "审查 $file 的代码质量。关注：
    1. TypeScript 类型安全
    2. React 最佳实践
    3. 性能隐患
    输出 JSON：{\"file\": \"文件名\", \"issues\": [{\"severity\": \"high/medium/low\", \"line\": 行号, \"message\": \"描述\"}]}" \
    --output-format json \
    --max-turns 2 \
    --allowedTools Read,Grep,Glob 2>/dev/null)

# 追加到报告
echo"$result" >> "$OUTPUT_FILE"
done

echo"✅ 审查完成，报告: $OUTPUT_FILE"

#!/bin/bash
# 从 Git 提交记录自动生成 Changelog

git log --oneline origin/main...HEAD | \
claude -p "基于这些 Git 提交记录，生成一份结构化的 Changelog。
分类为：✨ 新功能、🐛 Bug修复、🔧 优化、📝 文档。
用 Markdown 格式输出。" \
--output-format text \
--max-turns 1 > CHANGELOG.md

echo "✅ Changelog 已生成"

# TypeScript / JavaScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

export ANTHROPIC_API_KEY="your-api-key"

import { query } from"@anthropic-ai/claude-agent-sdk";

// 最简用法
forawait (const message of query({ prompt: "分析当前目录的项目结构" })) {
if (message.type === "assistant") {
    // Claude 的回复
    for (const block of message.message.content) {
      if (block.type === "text") {
        console.log(block.text);
      }
    }
  }

if (message.type === "result") {
    // 最终结果
    console.log("完成:", message.result);
  }
}

const result = query({
  prompt: "审查 src/app/api/ 下的所有 API 路由",
  options: {
    // 模型选择
    model: "sonnet",
    
    // 权限模式
    permissionMode: "bypassPermissions",  // CI 环境用这个
    // 其他选项："default"（正常交互）、"acceptEdits"（自动同意编辑）
    
    // 限制可用工具
    allowedTools: ["Read", "Grep", "Glob"],
    
    // 最大执行轮次
    maxTurns: 5,
    
    // 自定义系统提示
    systemPrompt: "你是一个严格的代码审查专家...",
    
    // 设置来源（是否加载本地配置文件）
    settingSources: ["project"],  // 只加载项目级配置
    // 默认 [] 表示不加载任何文件配置，完全由代码控制
  }
});

devpulse-doc-gen/
├── package.json
├── tsconfig.json
└── src/
    └── index.ts        ← 主逻辑

// src/index.ts
import { query } from"@anthropic-ai/claude-agent-sdk";
import * as fs from"fs";
import * as path from"path";
import { glob } from"glob";

// ========== 配置 ==========
const COMPONENTS_DIR = "../devpulse/src/components";
const OUTPUT_DIR = "../devpulse/docs/components";
const MODEL = "sonnet";

// ========== 核心函数：为单个组件生成文档 ==========
asyncfunction generateDocForComponent(filePath: string): Promise<string> {
const fileName = path.basename(filePath, path.extname(filePath));
let docContent = "";

forawait (const message of query({
    prompt: `阅读组件文件 ${filePath}，生成 Markdown 格式的组件文档。

要求：
1. 组件概述（一句话说明用途）
2. Props 表格（名称、类型、是否必填、默认值、说明）
3. 使用示例（至少 2 个：基础用法 + 高级用法）
4. 注意事项（常见错误、性能考虑）
5. 相关组件

输出纯 Markdown，不要代码块包裹。`,
    options: {
      model: MODEL,
      allowedTools: ["Read", "Grep", "Glob"],
      maxTurns: 3,
      permissionMode: "bypassPermissions",
    },
  })) {
    if (message.type === "result") {
      docContent = message.result;
    }
  }

return docContent;
}

// ========== 主流程 ==========
asyncfunction main() {
// 1. 找到所有组件文件
const componentFiles = await glob(`${COMPONENTS_DIR}/**/*.tsx`, {
    ignore: ["**/*.test.tsx", "**/__tests__/**"],
  });

console.log(`📦 找到 ${componentFiles.length} 个组件文件`);

// 2. 确保输出目录存在
  fs.mkdirSync(OUTPUT_DIR, { recursive: true });

// 3. 逐个生成文档
for (const file of componentFiles) {
    const componentName = path.basename(file, ".tsx");
    console.log(`📝 生成文档: ${componentName}`);

    try {
      const doc = await generateDocForComponent(file);
      const outputPath = path.join(OUTPUT_DIR, `${componentName}.md`);
      fs.writeFileSync(outputPath, doc, "utf-8");
      console.log(`  ✅ 完成 → ${outputPath}`);
    } catch (err) {
      console.error(`  ❌ 失败: ${componentName}`, err);
    }
  }

console.log(`\n🎉 文档生成完成，共 ${componentFiles.length} 个组件`);
}

main().catch(console.error);

npx tsx src/index.ts

📦 找到 12 个组件文件
📝 生成文档: ArticleCard
  ✅ 完成 → ../devpulse/docs/components/ArticleCard.md
📝 生成文档: ArticleList
  ✅ 完成 → ../devpulse/docs/components/ArticleList.md
📝 生成文档: Header
  ✅ 完成 → ../devpulse/docs/components/Header.md
...
🎉 文档生成完成，共 12 个组件

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

asyncdef review_code():
    asyncfor message in query(
        prompt="审查 src/app/api/posts/route.ts 的安全问题",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep"],
            permission_mode="bypassPermissions",
            max_turns=3,
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(review_code())

┌──────────────────────────────────────────────────────────┐
│     Headless vs TypeScript SDK vs Python SDK              │
├──────────────┬─────────────────┬─────────────────────────┤
│ 维度          │ Headless (CLI)   │ Agent SDK (TS / Python) │
├──────────────┼─────────────────┼─────────────────────────┤
│ 使用方式      │ claude -p "..."  │ query({ prompt: "..." })│
├──────────────┼─────────────────┼─────────────────────────┤
│ 适合场景      │ Shell 脚本       │ 复杂工具、Web 服务、     │
│              │ 简单自动化       │ 多轮对话、会话恢复       │
│              │ CI/CD 流水线     │                         │
├──────────────┼─────────────────┼─────────────────────────┤
│ 学习成本      │ 低（就是命令行） │ 中（需要了解异步迭代器） │
├──────────────┼─────────────────┼─────────────────────────┤
│ 灵活度        │ 中              │ 高（完全编程控制）       │
├──────────────┼─────────────────┼─────────────────────────┤
│ 输出控制      │ text/json/      │ 逐条消息流式处理         │
│              │ stream-json     │ 完整的类型系统           │
├──────────────┼─────────────────┼─────────────────────────┤
│ 多轮对话      │ 不支持          │ 支持（会话管理）         │
├──────────────┼─────────────────┼─────────────────────────┤
│ 自定义工具    │ 不支持          │ 支持（MCP 集成）         │
├──────────────┼─────────────────┼─────────────────────────┤
│ 推荐起步场景  │ PR 审查脚本     │ 文档生成器               │
│              │ Changelog 生成  │ 代码质量仪表盘           │
│              │ 批量格式检查    │ 自定义 AI 开发工具       │
└──────────────┴─────────────────┴─────────────────────────┘

选择建议：
• 能用 Headless 解决的 → 用 Headless（简单就是好）
• Headless 不够用了 → 上 Agent SDK
• 两者可以混用——Shell 脚本调 claude -p，复杂逻辑用 SDK

┌──────────────────────────────────────────────────────────┐
│          自动化场景的权限策略                                │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  只读任务（审查、分析、文档生成）：                         │
│  --allowedTools Read,Grep,Glob                           │
│                                                          │
│  写入任务（代码生成、重构）：                               │
│  --allowedTools Read,Write,Edit,Grep,Glob                │
│  ⚠️ 必须有 Git 版本控制，方便回滚                         │
│                                                          │
│  执行任务（运行测试、构建）：                               │
│  --allowedTools Read,Bash,Grep,Glob                      │
│  ⚠️ 搭配 PreToolUse Hook 拦截危险命令                    │
│                                                          │
│  永远不要：                                                │
│  ❌ permissionMode: "bypassPermissions"                  │
│     + allowedTools 不限制                                 │
│  ❌ 在没有版本控制的目录里运行写入任务                     │
│  ❌ 给自动化脚本访问生产数据库的权限                      │
│                                                          │
└──────────────────────────────────────────────────────────┘

# ❌ 危险：不限制轮次
claude -p "重构整个项目的类型系统"

# ✅ 安全：限制 5 轮
claude -p "重构整个项目的类型系统" --max-turns 5