My Blog
← Back to home

Claude Code Agent 深度使用指南

Claude Code Agent 深度使用指南

从单次对话到多 Agent 自主编码,从一行命令到 tmux 多窗口实时可视化。


目录

  1. 基础:Claude Code 是什么
  2. 起步:单次任务交互
  3. 进阶:让 Agent 持续自主工作
  4. 高级:子 Agent 与多任务并行
  5. 实战:tmux + git worktree 多窗口可视化
  6. 终极形态:完整的多 Agent 编码工作流
  7. 附录:常用命令速查

1. 基础:Claude Code 是什么

Claude Code 是 Anthropic 官方的命令行 AI 编码助手。它在你的终端里运行,能:

  • 读写文件、执行 shell 命令
  • 理解整个项目上下文(自动读取 CLAUDE.md、代码结构)
  • 自主规划任务、拆分步骤、逐步执行
  • 派生子 Agent 并行处理多个任务
  • 与 git、tmux、浏览器等外部工具协作

核心心智模型:不是一个聊天机器人,而是一个可以派出去干活的初级工程师。

安装与启动

# 安装
npm install -g @anthropic-ai/claude-code
 
# 在项目目录下启动
cd your-project
claude

交互模式

你输入任务 → Agent 思考 → 调用工具(读文件/写文件/执行命令) → 展示结果 → 等待下一个输入

你可以随时:

  • Escape 中断当前操作
  • 输入 /help 查看所有命令
  • 输入 /clear 清空对话历史
  • 输入 /compact 压缩上下文(长会话时有用)

2. 起步:单次任务交互

最简单的用法:一个问题

claude "这个项目的入口文件在哪?"

Claude 会搜索项目结构,找到入口文件,告诉你答案。

常见单次任务

# 修 bug
claude "登录页面点击提交后没有反应,帮我排查"
 
# 加功能
claude "在用户列表页加一个搜索框,支持按名字筛选"
 
# 重构
claude "把 src/utils/helpers.ts 里超过 50 行的函数都拆小"
 
# 写测试
claude "给 src/lib/auth.ts 写单元测试"
 
# 代码审查
claude "review 一下最近的 git 变更"

会话内持续对话

更常见的是进入交互模式后,多轮对话推进任务:

> 帮我给 chat 页面加一个消息搜索功能

(Agent 读完代码结构,给出方案)

> 方案可以,先从 API 开始实现

(Agent 实现 API,展示变更)

> 接着做前端部分,注意移动端适配

(Agent 继续实现前端)

关键习惯:把大任务拆成小步,每步确认后再推进。


3. 进阶:让 Agent 持续自主工作

很多时候你不想一步步盯着,而是希望 Agent 自己跑完整个任务链。

3.1 Plan 模式:先规划再执行

在 Claude Code 里,你可以让 Agent 先规划:

> /plan 实现一个完整的消息搜索功能,包括 API、前端组件和测试

Agent 会进入 Plan 模式:

  1. 搜索和理解代码结构
  2. 制定实施计划(步骤列表)
  3. 展示计划给你确认
  4. 你确认后,Agent 按计划逐步执行

3.2 /loop:让 Agent 定时循环执行

/loop 让 Agent 按固定间隔重复执行任务,适合持续监控场景。

> /loop 5m 检查一下 build 是否通过,如果失败就修复

这会每 5 分钟自动执行一次。Agent 会:

  1. 运行 pnpm build
  2. 如果成功,报告状态
  3. 如果失败,读取错误信息,尝试修复
  4. 修复后重新验证
  5. 等待下一个周期

适用场景

  • 持续集成监控
  • 定时检查部署状态
  • 周期性数据同步

动态间隔 /loop(无参数):

> /loop 持续优化性能,每轮优化后检查 Lighthouse 分数

Agent 会自己决定每轮间隔(60s~3600s),根据任务进度自适应。

3.3 自主循环模式(Autonomous Loop)

最强大的持续工作模式。给 Agent 一个大目标,让它自己决定节奏:

> 我想把整个项目的测试覆盖率从 40% 提升到 80%。请自主工作,每完成一个模块就继续下一个,直到达标。用 /loop 模式。

Agent 会:

  1. 分析当前覆盖率,找出最缺测试的模块
  2. 按优先级排序
  3. 逐个模块写测试
  4. 每轮完成后检查进度
  5. 自动调整策略
  6. 达到目标后停止

3.4 --allowedTools 和权限控制

让 Agent 长时间自主工作时,权限管理很重要:

# 只允许读写文件和运行测试
claude --allowedTools "Read,Write,Edit,Bash" --allowedBashCommands "pnpm test*,pnpm vitest*"
 
# 完全自主模式(危险!只在可信环境使用)
claude --dangerously-skip-permissions

推荐做法:在项目的 .claude/settings.json 中配置白名单:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(pnpm test*)",
      "Bash(pnpm lint*)",
      "Bash(pnpm build*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git add*)",
      "Bash(git commit*)"
    ]
  }
}

4. 高级:子 Agent 与多任务并行

Claude Code 内置了 Agent 系统支持并行工作。一个主 Agent 可以派生出多个子 Agent,每个子 Agent 独立处理不同任务。

4.1 子 Agent 的基本概念

主 Agent (你直接对话的)
├── 子 Agent A (探索代码库)
├── 子 Agent B (写测试)
└── 子 Agent C (做代码审查)

子 Agent 的特点:

  • 在后台运行,不阻塞主 Agent
  • 各自独立的上下文窗口
  • 完成后把结果汇报给主 Agent
  • 主 Agent 综合所有结果后给你答复

4.2 内置 Agent 类型

Claude Code 内置了多种专用 Agent:

Agent 类型 用途 典型场景
Explore 快速搜索代码 找文件、grep 关键词、理解结构
Plan 规划实施方案 拆解复杂任务、设计架构
code-reviewer 代码审查 审查 PR、检查代码质量
security-reviewer 安全审查 发现安全漏洞
build-error-resolver 修复构建错误 编译失败时自动排查
tdd-guide 测试驱动开发 先写测试再写实现
doc-updater 更新文档 同步文档和代码变更
general-purpose 通用 任何任务

4.3 在对话中使用子 Agent

你不需要直接调用子 Agent —— 主 Agent 会自动判断何时需要派生:

> 帮我审查最近的代码变更,同时检查有没有安全问题

主 Agent 会:

  1. 派生 code-reviewer 审查代码质量
  2. 同时派生 security-reviewer 检查安全问题
  3. 两个子 Agent 并行工作
  4. 主 Agent 汇总结果给你

4.4 Team 模式:多 Agent 协作

对于复杂项目,可以使用 Team 模式 —— 多个 Agent 组成团队,共享任务列表:

> 创建一个团队来完成以下任务:
> 1. 重构数据库层(Agent A)
> 2. 更新对应的 API 接口(Agent B)
> 3. 补充集成测试(Agent C)
> 4. 更新文档(Agent D)

Team 模式的工作流:

1. 创建团队 → 生成共享任务列表
2. 每个 Agent 认领任务
3. Agent 完成任务后标记完成
4. 下游 Agent 看到前置任务完成,开始自己的工作
5. 所有任务完成后,团队解散

5. 实战:tmux + git worktree 多窗口可视化

这是最精彩的部分 —— 让多个 Agent 在独立的 git 分支上并行工作,通过 tmux 窗口实时可视化。

5.1 为什么需要这个方案

问题场景:

  • Agent A 正在重构 API 层(需要改 10 个文件)
  • Agent B 正在写新功能(需要改 5 个文件)
  • 两个 Agent 改同一个项目 → 文件冲突 → 混乱

解决思路:

用 git worktree 让每个 Agent 在独立的目录工作
用 tmux 让你同时看到所有 Agent 的实时状态

5.2 Git Worktree 基础

Git worktree 允许你在同一个仓库下 checkout 多个分支到不同目录:

# 在项目根目录创建 worktree
git worktree add ../feature-auth feature/auth
git worktree add ../feature-search feature/search
 
# 现在你有:
# ./                  → 主分支(比如 main)
# ../feature-auth/    → feature/auth 分支
# ../feature-search/  → feature/search 分支
 
# 每个 worktree 是完整的工作目录,可以独立编辑、测试、提交
cd ../feature-auth && pnpm install && pnpm dev
# 在另一个终端
cd ../feature-search && pnpm install && pnpm dev

5.3 Tmux 基础

tmux 是终端复用器 —— 一个终端窗口里开多个面板:

# 安装 tmux
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS
 
# 基础操作
tmux new -s work       # 创建名为 "work" 的会话
tmux attach -t work    # 重新连接到会话
 
# 在 tmux 内:
# Ctrl+B %    → 水平分屏(左右)
# Ctrl+B "    → 垂直分屏(上下)
# Ctrl+B 方向键 → 切换面板
# Ctrl+B d    → 脱离会话(后台运行)

5.4 最简示例:两个 Agent 并行工作

假设我们要同时做两件事:

  1. Agent A:给项目加 ESLint 规则
  2. Agent B:写新功能

第一步:创建 worktree

cd /home/user/project
 
# 创建两个 worktree
git worktree add .claude/worktrees/agent-eslint -b agent-eslint HEAD
git worktree add .claude/worktrees/agent-feature -b agent-feature HEAD

第二步:启动 tmux 并布局

# 创建 tmux 会话,左右分屏
tmux new-session -s agents -d
 
# 左侧启动 Agent A(ESLint)
tmux send-keys -t agents:0.0 'cd /home/user/project/.claude/worktrees/agent-eslint && claude "给项目添加严格的 ESLint 规则,修复所有 lint 错误"' Enter
 
# 分屏
tmux split-window -h -t agents:0.0
 
# 右侧启动 Agent B(新功能)
tmux send-keys -t agents:0.1 'cd /home/user/project/.claude/worktrees/agent-feature && claude "实现用户搜索 API 端点,包括输入校验和测试"' Enter
 
# 连接查看
tmux attach -t agents

你现在会看到:

┌─────────────────────────┬─────────────────────────┐
│    Agent A: ESLint      │    Agent B: 搜索功能     │
│                         │                         │
│  ✓ 读取 eslint 配置     │  ✓ 分析现有 API 结构     │
│  ✓ 添加新规则           │  ✓ 实现 /api/search      │
│  → 修复 src/auth.ts     │  → 写输入校验            │
│  → 修复 src/utils.ts    │  → 写测试用例            │
│                         │                         │
└─────────────────────────┴─────────────────────────┘

5.5 进阶示例:四面板监控矩阵

更实用的布局 —— 左边两个 Agent 工作,右边两个监控面板:

#!/bin/bash
SESSION="dev-salon"
PROJECT="/home/user/project"
 
# 创建会话
tmux new-session -s $SESSION -d -c $PROJECT
 
# 左上:主 Agent(协调者)
tmux send-keys -t $SESSION:0.0 "claude" Enter
 
# 右上:构建监控
tmux split-window -h -t $SESSION:0.0
tmux send-keys -t $SESSION:0.1 "watch -n 10 'pnpm build 2>&1 | tail -5'" Enter
 
# 左下:测试监控
tmux split-window -v -t $SESSION:0.0
tmux send-keys -t $SESSION:0.2 "watch -n 15 'pnpm test 2>&1 | tail -10'" Enter
 
# 右下:Git 状态
tmux split-window -v -t $SESSION:0.1
tmux send-keys -t $SESSION:0.3 "watch -n 5 'git -C $PROJECT status --short'" Enter
 
# 连接
tmux attach -t $SESSION

效果:

┌─────────────────────────┬─────────────────────────┐
│                         │     构建监控             │
│    主 Agent             │  ✓ Build successful      │
│    (协调者)             │  Time: 12.3s             │
│                         │  Warnings: 0             │
│                         │                         │
├─────────────────────────┼─────────────────────────┤
│                         │     Git 状态             │
│     测试监控            │  M src/lib/auth.ts       │
│  ✓ 42/42 tests passed  │  M src/app/api/...       │
│  Coverage: 82%          │  ?? docs/new-guide.md    │
│                         │                         │
└─────────────────────────┴─────────────────────────┘

6. 终极形态:完整的多 Agent 编码工作流

把前面所有技术组合起来,构建一个完整的多 Agent 工作流。

6.1 场景描述

你的团队要实现一个大功能:给 SaaS 产品加支付模块

任务拆解:

  1. 后端:创建支付 API、数据库 schema、webhook 处理
  2. 前端:支付页面、订单管理页面
  3. 测试:API 集成测试、E2E 测试
  4. 文档:更新 API 文档和用户指南

每个任务派一个 Agent,各自在独立 worktree 上工作。

6.2 一键启动脚本

创建 scripts/multi-agent.sh

#!/bin/bash
set -e
 
SESSION="payment-feature"
PROJECT="$(pwd)"
BRANCH="feature/payment"
TASKS=("backend" "frontend" "testing" "docs")
 
echo "=== 多 Agent 工作流启动 ==="
 
# 1. 确保在最新 main 上
git checkout main
git pull origin main
 
# 2. 为每个任务创建 worktree
for task in "${TASKS[@]}"; do
    BRANCH_NAME="${BRANCH}-${task}"
    WORKTREE_PATH="${PROJECT}/.claude/worktrees/payment-${task}"
 
    echo "创建 worktree: ${task} → ${BRANCH_NAME}"
    git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME" HEAD 2>/dev/null || true
 
    # 每个 worktree 独立安装依赖
    cd "$WORKTREE_PATH"
    pnpm install --frozen-lockfile 2>/dev/null || pnpm install
    cd "$PROJECT"
done
 
# 3. 创建 tmux 会话(2x2 布局)
tmux new-session -s $SESSION -d
 
# 左上:后端 Agent
tmux send-keys -t $SESSION:0.0 \
    "cd ${PROJECT}/.claude/worktrees/payment-backend && \
     claude -p '你是后端 Agent。请实现支付模块的后端部分:
     1. 创建 payments 表的 Drizzle schema(参考现有的 src/lib/db/schema.ts)
     2. 实现 /api/payments/create 端点(调用 Stripe API)
     3. 实现 /api/payments/webhook 端点(处理 Stripe 回调)
     4. 实现订单查询 API
     5. 写单元测试
     每完成一步就 git commit。完成后报告。'" Enter
 
# 右上:前端 Agent
tmux split-window -h -t $SESSION:0.0
tmux send-keys -t $SESSION:0.1 \
    "cd ${PROJECT}/.claude/worktrees/payment-frontend && \
     claude -p '你是前端 Agent。请实现支付模块的前端部分:
     1. 创建支付页面 /billing(支付表单 + 订阅选择)
     2. 创建订单管理页面 /orders
     3. 创建支付相关的 React hooks(usePayment, useSubscription)
     4. 注意移动端适配和加载状态
     每完成一步就 git commit。完成后报告。'" Enter
 
# 左下:测试 Agent
tmux split-window -v -t $SESSION:0.0
tmux send-keys -t $SESSION:0.2 \
    "cd ${PROJECT}/.claude/worktrees/payment-testing && \
     claude -p '你是测试 Agent。等 30 秒后开始工作(等其他 Agent 先产出代码)。
     然后:
     1. 编写支付 API 的集成测试(用 Vitest)
     2. 编写支付流程的 E2E 测试(用 Playwright)
     3. 确保测试覆盖率 > 80%
     4. 所有测试必须能独立运行
     每完成一步就 git commit。完成后报告。'" Enter
 
# 右下:文档 Agent
tmux split-window -v -t $SESSION:0.1
tmux send-keys -t $SESSION:0.3 \
    "cd ${PROJECT}/.claude/worktrees/payment-docs && \
     claude -p '你是文档 Agent。请更新项目文档:
     1. 更新 API 文档,描述新的支付端点
     2. 更新 ARCHITECTURE.md,描述支付模块架构
     3. 创建 docs/PAYMENT.md 用户指南
     4. 更新 CLAUDE.md 中的相关部分
     每完成一步就 git commit。完成后报告。'" Enter
 
echo "=== 已启动 4 个 Agent ==="
echo "运行 'tmux attach -t $SESSION' 查看实时状态"
echo "运行 'tmux detach' 脱离(Agent 继续在后台工作)"

6.3 运行

chmod +x scripts/multi-agent.sh
./scripts/multi-agent.sh
 
# 查看实时状态
tmux attach -t payment-feature
 
# 脱离(Agent 继续工作)
# 按 Ctrl+B 然后按 d
 
# 随时重新连接
tmux attach -t payment-feature

6.4 合并结果

所有 Agent 完成后,合并 worktree 的变更:

# 查看各 worktree 的完成状态
for task in backend frontend testing docs; do
    echo "=== payment-${task} ==="
    git -C .claude/worktrees/payment-${task} log --oneline -5
    echo ""
done
 
# 合并到主分支(按依赖顺序)
git checkout feature/payment
 
git merge feature/payment-backend
# 解决可能的冲突
 
git merge feature/payment-frontend
# 解决可能的冲突
 
git merge feature/payment-testing
git merge feature-payment-docs
 
# 验证
pnpm install
pnpm build
pnpm test
 
# 清理 worktree
for task in backend frontend testing docs; do
    git worktree remove .claude/worktrees/payment-${task}
done

6.5 用 Claude Code 内置的 worktree 支持

Claude Code 本身也有 worktree 支持,不需要手动管理:

> 用 worktree 模式帮我实现支付模块后端

Agent 会自动:

  1. 创建 git worktree
  2. 在隔离环境中工作
  3. 完成后报告 worktree 路径和分支名
  4. 你可以选择保留或删除 worktree

6.6 更优雅的方式:用 Claude Code 的 Team 功能

最新的 Claude Code 支持 Team 模式,内置了任务队列和 Agent 协调:

> 创建一个叫 "payment" 的团队,完成支付模块开发。
> 任务列表:
> 1. 后端:支付 API + 数据库 schema(优先级最高)
> 2. 前端:支付页面 + 订单管理(依赖任务1)
> 3. 集成测试(依赖任务1)
> 4. E2E 测试(依赖任务2和3)
> 5. 文档更新(依赖所有任务)
>
> 给每个任务分配一个 Agent,并行执行无依赖的任务。

Claude Code 会:

  1. 创建团队和任务列表
  2. 派生多个 Agent,各自认领任务
  3. 自动管理依赖关系(任务2等任务1完成)
  4. 各 Agent 在独立上下文中工作
  5. 完成后汇总结果

7. 附录:常用命令速查

Claude Code CLI

# 基础
claude                          # 交互模式
claude "任务描述"                # 单次任务
claude -p "任务描述"             # 非交互模式(管道友好)
 
# 权限
claude --allowedTools "Read,Write,Edit,Bash"
claude --dangerously-skip-permissions  # 危险!完全自主
 
# 上下文
claude --resume                  # 恢复上次会话
claude --continue                # 继续上次对话

会话内命令

/help          # 帮助
/clear         # 清空对话
/compact       # 压缩上下文
/plan          # 进入规划模式
/loop [间隔]   # 循环执行(如 /loop 5m)
/tasks         # 查看任务列表
/config        # 打开配置
/model         # 切换模型

Git Worktree

git worktree add <> -b <分支> HEAD  # 创建
git worktree list                         # 列出所有
git worktree remove <>                # 删除

Tmux

tmux new -s <>           # 创建会话
tmux attach -t <>        # 连接会话
tmux ls                      # 列出会话
tmux kill-session -t <>  # 关闭会话
 
# 会话内快捷键(先按 Ctrl+B)
%      # 水平分屏
"      # 垂直分屏
方向键   # 切换面板
d      # 脱离会话
x      # 关闭当前面板

自动化脚本模板

#!/bin/bash
# multi-agent-template.sh — 可复用的多 Agent 启动脚本
 
SESSION="my-project"
PROJECT="$(pwd)"
TASKS=("task-a" "task-b")  # 替换为你的任务名
 
# 创建 worktree
for task in "${TASKS[@]}"; do
    git worktree add "${PROJECT}/.claude/worktrees/${task}" -b "agent/${task}" HEAD
done
 
# 创建 tmux 会话
tmux new-session -s $SESSION -d
 
# 为每个任务开面板
FIRST=true
for task in "${TASKS[@]}"; do
    if [ "$FIRST" = true ]; then
        FIRST=false
    else
        tmux split-window -h -t $SESSION:0.0
    fi
    tmux send-keys -t $SESSION:0.$((${#TASKS[@]} - 1)) \
        "cd ${PROJECT}/.claude/worktrees/${task} && claude" Enter
done
 
# 均匀分布面板
tmux select-layout -t $SESSION even-horizontal
 
echo "启动完成!运行: tmux attach -t $SESSION"

总结

从简到繁,Claude Code Agent 的工作模式可以分四个层次:

层次 模式 适合场景 工具
1 单次对话 快速问答、小改动 claude "任务"
2 持续对话 功能开发、修 bug 交互模式 + /plan
3 自主循环 大规模重构、测试补充 /loop + 权限配置
4 多 Agent 并行 大功能拆分、团队协作 tmux + worktree + Team

核心原则:

  • 从小开始:先在单次对话里验证思路,再扩大到自主循环
  • 权限最小化:只开放必要的工具权限
  • 隔离工作:多个 Agent 一定用 worktree 隔离
  • 可视化:tmux 让你随时看到 Agent 在干什么
  • 分步验证:Agent 完成后先检查再合并