Claude Code Agent 深度使用指南
Claude Code Agent 深度使用指南
从单次对话到多 Agent 自主编码,从一行命令到 tmux 多窗口实时可视化。
目录
- 基础:Claude Code 是什么
- 起步:单次任务交互
- 进阶:让 Agent 持续自主工作
- 高级:子 Agent 与多任务并行
- 实战:tmux + git worktree 多窗口可视化
- 终极形态:完整的多 Agent 编码工作流
- 附录:常用命令速查
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 模式:
- 搜索和理解代码结构
- 制定实施计划(步骤列表)
- 展示计划给你确认
- 你确认后,Agent 按计划逐步执行
3.2 /loop:让 Agent 定时循环执行
/loop 让 Agent 按固定间隔重复执行任务,适合持续监控场景。
> /loop 5m 检查一下 build 是否通过,如果失败就修复
这会每 5 分钟自动执行一次。Agent 会:
- 运行
pnpm build - 如果成功,报告状态
- 如果失败,读取错误信息,尝试修复
- 修复后重新验证
- 等待下一个周期
适用场景:
- 持续集成监控
- 定时检查部署状态
- 周期性数据同步
动态间隔 /loop(无参数):
> /loop 持续优化性能,每轮优化后检查 Lighthouse 分数
Agent 会自己决定每轮间隔(60s~3600s),根据任务进度自适应。
3.3 自主循环模式(Autonomous Loop)
最强大的持续工作模式。给 Agent 一个大目标,让它自己决定节奏:
> 我想把整个项目的测试覆盖率从 40% 提升到 80%。请自主工作,每完成一个模块就继续下一个,直到达标。用 /loop 模式。
Agent 会:
- 分析当前覆盖率,找出最缺测试的模块
- 按优先级排序
- 逐个模块写测试
- 每轮完成后检查进度
- 自动调整策略
- 达到目标后停止
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 会:
- 派生
code-reviewer审查代码质量 - 同时派生
security-reviewer检查安全问题 - 两个子 Agent 并行工作
- 主 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 dev5.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 并行工作
假设我们要同时做两件事:
- Agent A:给项目加 ESLint 规则
- 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 产品加支付模块。
任务拆解:
- 后端:创建支付 API、数据库 schema、webhook 处理
- 前端:支付页面、订单管理页面
- 测试:API 集成测试、E2E 测试
- 文档:更新 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-feature6.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}
done6.5 用 Claude Code 内置的 worktree 支持
Claude Code 本身也有 worktree 支持,不需要手动管理:
> 用 worktree 模式帮我实现支付模块后端
Agent 会自动:
- 创建 git worktree
- 在隔离环境中工作
- 完成后报告 worktree 路径和分支名
- 你可以选择保留或删除 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 会:
- 创建团队和任务列表
- 派生多个 Agent,各自认领任务
- 自动管理依赖关系(任务2等任务1完成)
- 各 Agent 在独立上下文中工作
- 完成后汇总结果
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 完成后先检查再合并