适用版本: Claude Code CLI v2.1.168+ 最后更新: 2026-06-11
一、CLI 命令行参数
|
1
|
claude [options] [command] [prompt]
|
1.1 核心参数
-p, --print— 非交互式输出
解决什么问题:需要在脚本、CI/CD 或管道中调用 Claude,而不希望进入交互式对话模式。 何时使用:Shell 脚本自动化、CI/CD 流水线中的代码审查、管道组合处理文本、批量分析任务。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
# 基础用法:单次问答
claude -p "解释这个函数的实现逻辑"
# 管道输入:将文件内容传给 Claude 分析
cat src/main.js | claude -p "找出所有潜在的空指针问题"
# 管道输出:将 Claude 的输出传给其他命令
claude -p "列出 src/ 下所有 Java 文件的用途" | grep "Controller"
# 结合 git 工作流:分析最近的提交
git log --oneline -20 | claude -p "总结最近的提交活动,按功能分类"
# 代码生成到文件
claude -p "生成一个 Dockerfile,用于 Spring Boot 应用" > Dockerfile
# 指定模型的非交互查询
claude -p "解释这段代码" --model opus
|
注意事项:
- -p 模式下不保留会话历史,每次调用都是独立的
- 如果需要上下文连续对话,应使用 -c(继续会话)或 -r(恢复会话)
- 管道输入时,Claude 会将 stdin 的内容作为上下文的一部分
- 可以结合 --output-format json 在脚本中获取结构化输出
-c, --continue— 继续最近会话
解决什么问题:中断工作后想要无缝恢复,不想重新描述上下文和需求。 何时使用:每天早上继续昨天的工作、终端意外关闭后恢复、在多个项目间切换后回到之前的项目。
|
1
2
3
4
5
6
7
8
|
# 最简单的继续方式
claude -c
# 继续会话并指定模型
claude -c --model opus
# 继续会话并以特定模式运行
claude -c --effort max
|
工作原理:-c 会读取当前工作目录 (cwd) 下最近一次会话的完整上下文并从上次中断处继续。不同目录的会话互不影响。
注意事项:
- 如果当前目录没有历史会话,会自动创建新会话
- 继续的会话与原会话共享同一个 session ID
-r, --resume [value]— 恢复指定会话
解决什么问题:有多个并行会话,需要精确恢复到某一个特定会话(可能是几天前的)。 何时使用:恢复几天前的特定会话、在多个并行任务间切换、恢复被系统重启中断的会话。
|
1
2
3
4
5
6
7
8
9
10
11
|
# 交互式选择器(列出所有历史会话,支持搜索过滤)
claude -r
# 恢复到指定 UUID 的会话
claude -r abc123-def456-789
# 恢复并派生新会话(保留原会话的上下文但不修改它)
claude -r abc123-def456-789 --fork-session
# 恢复链接到某个 PR 的会话
claude -r --from-pr 123
|
会话选择器交互:↑/↓ 浏览、Enter 选中、显示名称/时间/工作目录/消息数。
-w, --worktree [name]— Git Worktree 隔离
解决什么问题:需要在独立沙箱中尝试大规模重构,不想污染当前工作区,或者想让多个 Agent 并行处理不同任务。 何时使用:实验性重构、同时开发多个独立功能、Agent 并行处理、不确定的修改需要可随时丢弃。
|
1
2
3
4
5
6
7
8
|
# 创建命名 worktree
claude -w feature-refactor
# worktree + tmux 会话(多窗口管理)
claude -w feature-refactor --tmux
# worktree + 指定模型 + 高努力级别(复杂重构)
claude -w major-refactor --model opus --effort max
|
配置项:worktree.baseRef 控制基准分支(fresh 从 origin/default-branch 创建,head 从当前 HEAD 创建)。完成后可选择 keep(保留)或 remove(丢弃)。
--model <model>— 指定模型
解决什么问题:不同任务对能力和速度的需求不同——简单任务不需要最强大(最贵)的模型,复杂任务需要最强推理能力。 何时使用:复杂架构设计选择 Opus、日常编码选择 Sonnet、批量简单处理选择 Haiku。
| 值 |
对应的模型 |
速度 |
成本 |
适用场景 |
| sonnet |
Claude Sonnet 4.6 |
快 |
中 |
日常开发首选:代码生成、Bug 修复、文档编写 |
| opus |
Claude Opus 4.8 |
慢 |
高 |
最强大:复杂架构、深度分析、安全审查 |
| haiku |
Claude Haiku 4.5 |
最快 |
最低 |
极速任务:日志分类、简单格式化、批量小任务 |
|
1
2
|
claude --model opus
export ANTHROPIC_MODEL=claude-opus-4-8 # 持久化设置
|
--effort <level>— 努力级别
解决什么问题:控制 Claude 的思考深度——深度思考质量更高但更慢更贵,简单任务不需要深度思考。 何时使用:日常开发用 medium,复杂逻辑用 high,安全审查/架构设计用 max,简单格式化用 low。
| 级别 |
思考深度 |
适用场景 |
| low |
快速回答 |
格式转换、简单翻译 |
| medium |
适度思考(默认) |
日常开发 |
| high |
深度思考 |
复杂逻辑 |
| xhigh |
高度深入 |
架构建议 |
| max |
最大努力 |
安全审查、关键代码 |
|
1
2
|
claude -p "格式化 JSON" --effort low
claude --effort max --model opus # 最强组合
|
--name, -n <name>— 会话命名
解决什么问题:多个会话后难以区分哪个是哪个,需要给会话起个有意义的名字便于后续查找。 何时使用:每次启动新会话时都应该命名。
|
1
2
|
claude -n "修复用户登录超时Bug"
claude -n "重构支付模块" --model opus --effort max
|
命名建议:动词+对象+描述,如 重构用户认证模块、修复订单列表分页Bug。
--session-id <uuid>— 指定会话 ID
解决什么问题:需要精确控制会话标识,实现脚本化的会话管理。 何时使用:自动化脚本中管理会话生命周期。
|
1
2
|
SESSION_ID=$(uuidgen)
claude --session-id $SESSION_ID -p "分析项目结构"
|
1.2 调试参数
--debug [filter]— 调试模式
解决什么问题:遇到问题需要排查——API 报错、Hooks 不触发、MCP 连接失败等。 何时使用:排查 API 调用异常、Hooks 不工作、MCP 服务器连接问题。
|
1
2
3
4
5
|
claude --debug # 全部调试信息
claude --debug api # 仅 API 调用日志
claude --debug hooks # 仅 Hooks 执行日志
claude --debug api,hooks # 组合过滤
claude --debug api --debug-file ./debug.log # 写入文件
|
| 过滤器 |
追踪内容 |
| api |
API 请求/响应、token 消耗、重试 |
| hooks |
Hooks 触发和执行完整日志 |
| tools |
工具调用入参和返回值 |
| mcp |
MCP 服务器连接和通信 |
| auth |
认证流程日志 |
--verbose— 详细输出
解决什么问题:需要看到更多运行时信息来排查问题。 何时使用:排查配置加载、MCP 连接、或不确定为何某个行为不符合预期时。
|
1
|
claude --verbose -p "分析这个文件"
|
1.3 系统提示参数
--system-prompt <prompt>— 完全替换系统提示词
解决什么问题:需要完全自定义 Claude 的角色和行为,不想要任何默认的 Claude Code 指令。 何时使用:构建自定义 AI 应用,需要特定角色行为(?? 会移除 Claude Code 的所有内置工具使用能力,谨慎使用)。
|
1
|
claude --system-prompt "You are a Python code reviewer..."
|
--append-system-prompt <prompt>— 追加系统提示词
解决什么问题:在保留 Claude Code 默认能力的基础上,追加项目特定的行为约束。 何时使用:添加项目特定的编码规范、语言偏好、框架约定(推荐用 CLAUDE.md 替代)。
|
1
2
|
claude --append-system-prompt "始终使用 Java 17 语法。所有 public 方法必须有 Javadoc。"
claude --append-system-prompt "$(cat custom-instructions.txt)"
|
--bare— 极简模式
解决什么问题:需要最快启动速度,或者怀疑 hooks/插件导致了问题需要排查。 何时使用:排查插件冲突、受限环境运行、追求最小资源占用。
|
1
|
claude --bare -p "快速查询"
|
1.4 权限参数
--permission-mode <mode>— 权限模式
解决什么问题:控制 Claude 执行操作时需要用户确认的频率和范围。 何时使用:日常开发用 acceptEdits(自动编辑,其他确认),CI/CD 用 bypassPermissions,代码阅读用 plan。
| 模式 |
编辑 |
命令 |
网络 |
场景 |
| default |
询问 |
询问 |
询问 |
不熟悉的环境 |
| acceptEdits |
自动 |
询问 |
询问 |
日常开发推荐 |
| bypassPermissions |
自动 |
自动 |
自动 |
?? CI/CD/沙箱 |
| plan |
禁止 |
禁止 |
禁止 |
只读分析 |
|
1
2
|
claude --permission-mode acceptEdits
claude --permission-mode plan # 纯分析,不修改
|
--allowedTools/--disallowedTools— 工具白名单/黑名单
解决什么问题:需要精细控制 Claude 可以使用哪些工具,比如只允许 git 操作但不允许删除文件。 何时使用:安全敏感环境、CI/CD 自动化、限制 Claude 的破坏性操作能力。
|
1
2
|
claude --allowedTools "Bash(git *) Read Edit Write"
claude --disallowedTools "Bash(rm *) Bash(sudo *)"
|
1.5 输出格式参数
--output-format <format>— 输出格式
解决什么问题:需要程序化解析 Claude 的输出,而不是人类阅读的纯文本。 何时使用:脚本集成用 json,实时流处理用 stream-json,人类阅读用 text(默认)。
| 格式 |
适用场景 |
| text |
人类阅读(默认) |
| json |
脚本解析、API 集成 |
| stream-json |
实时流处理 |
|
1
|
claude -p "分析错误日志" --output-format json --json-schema '{"type":"object",...}'
|
二、CLI 子命令
2.1claude agents— 后台 Agent 管理
解决什么问题:同时运行多个 Agent 执行不同任务,需要一个管理界面来监控和控制它们。 何时使用:并行代码审查、多模块同步开发、批量任务分发与监控。
|
1
2
3
4
|
claude agents # 启动管理界面
claude agents --model sonnet --effort high # 设置 Agent 默认参数
claude agents --json # JSON 输出(脚本监控)
claude agents --cwd /path/to/project # 限定项目范围
|
2.2claude auth— 认证管理
解决什么问题:管理 Claude Code 的登录状态——首次使用需要登录,切换账号需要重新认证,排查认证失败需要查看状态。 何时使用:首次安装后登录、切换 API Key、排查认证相关问题。
|
1
2
3
4
5
6
7
8
|
claude auth login --console # API Key 计费登录
claude auth login --claudeai # Claude 订阅登录
claude auth login --sso # 企业 SSO 登录
claude auth login --email dev@company.com # 预填邮箱
claude auth status # 查看登录状态
claude auth status --json # JSON 输出(脚本检测)
claude auth logout # 登出
|
典型场景:
- 新机器首次使用:claude auth login --console 然后输入 API Key
- 企业环境:claude auth login --sso
- CI 环境:先设置 ANTHROPIC_API_KEY 环境变量,无需手动 login
2.3claude mcp— MCP 服务器管理
解决什么问题:需要让 Claude 访问外部工具和数据源(数据库、文件系统、API 等),通过 MCP 协议标准化集成。 何时使用:集成数据库查询、文件系统操作、第三方 API、自定义工具。
添加 MCP 服务器
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
# stdio 传输(本地进程)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
claude mcp add postgres -e PG_HOST=localhost -e PG_PORT=5432 -- npx -y @modelcontextprotocol/server-postgres
# HTTP 传输(远程服务)
claude mcp add --transport http my-api https://mcp.example.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer xxx"
# OAuth 认证
claude mcp add --transport http oauth-server https://oauth.example.com/mcp --client-id "my-id" --client-secret
# 配置范围
claude mcp add -s user filesystem -- npx @modelcontextprotocol/server-filesystem /tmp
claude mcp add -s project db-server -- npx @modelcontextprotocol/server-postgres
|
查看和管理
|
1
2
3
4
5
|
claude mcp list # 列出所有
claude mcp get filesystem # 查看详情(含工具列表)
claude mcp remove filesystem # 删除
claude mcp add-from-claude-desktop # 从 Claude Desktop 导入
claude mcp serve # 启动 Claude Code 作为 MCP 服务器
|
2.4claude plugin— 插件管理
解决什么问题:需要扩展 Claude Code 的功能——安装社区或自定义的 Skill、Agent、Hooks 组合包。 何时使用:安装第三方 Skill、创建自定义工作流插件、管理插件的启用/禁用/更新。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
# 创建插件
claude plugin init my-skill # 基础脚手架
claude plugin init full-plugin --with skills,agents,hooks # 含额外组件
# 安装
claude plugin install my-plugin # 从市场安装
# 查看
claude plugin list # 已安装列表
claude plugin list --available # 含市场可用
claude plugin details my-plugin # 组件清单 + token 估算
# 管理
claude plugin enable my-plugin # 启用
claude plugin disable my-plugin # 禁用
claude plugin update my-plugin # 更新
claude plugin uninstall my-plugin # 卸载
claude plugin prune # 清理无用的自动依赖
claude plugin validate ./my-plugin # 验证清单格式
claude plugin tag ./my-plugin # 创建发布 tag
|
2.5claude ultrareview— 云托管深度代码审查
解决什么问题:普通 /review 只是单 Agent 本地审查,对于重要 PR 需要云端多 Agent 并行交叉验证的深度审查。 何时使用:重要 PR 合并前、安全关键代码变更、发布前的最终质量把关。
|
1
2
3
4
|
claude ultrareview main # 审查相对于 main 的变更
claude ultrareview 123 # 审查指定 PR
claude ultrareview main --json # JSON 输出(自定义处理)
claude ultrareview main --timeout 60 # 设置超时(默认 30 分钟)
|
ultrareview vs /review:
| 特性 |
ultrareview |
/review |
| 执行方式 |
云端多 Agent 并行 |
本地单 Agent |
| 审查深度 |
多维度交叉验证 |
单维度分析 |
| 耗时 |
分钟级 |
秒级 |
| 适用 |
重要 PR、安全关键代码 |
日常代码审查 |
2.6 其他子命令
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
# 健康检查 — 排查 CLI 安装/配置问题
claude doctor
# 版本管理 — 安装/切换 CLI 版本
claude install latest # 最新版
claude install stable # 稳定版
claude install v2.1.168 # 指定版本
# 长期认证 — 避免反复登录(需要 Claude 订阅)
claude setup-token
# 项目清理 — 释放磁盘空间
claude project purge --dry-run # 预览
claude project purge -i # 交互式确认
claude project purge --all # 清理所有项目
# 更新 CLI
claude update
# 自动模式 — 查看/优化自动权限模式规则
claude auto-mode config # 查看当前规则
claude auto-mode defaults # 查看默认规则
claude auto-mode critique # AI 评估自定义规则
|
三、交互式斜杠命令
在交互式会话中输入以 / 开头的命令。每个命令都标注了何时使用和解决什么问题。
3.1 会话控制命令
/help— 帮助信息
解决什么问题:记不住有哪些斜杠命令、某个命令的用法是什么。 何时使用:开始使用 Claude Code 时、需要查看所有可用 Skill 列表时、不确定某个命令是否存在时。
会列出所有已注册的命令(内置 + 通过插件/Skill 注册的自定义命令)。
/clear— 清除会话
解决什么问题:会话上下文过长,或者之前的讨论方向错误,需要"重置"但不想退出重启 Claude Code。 何时使用:开始讨论全新话题、上下文被错误方向污染、测试不同方案需要干净上下文。
注意事项:清除后无法恢复。如果想保留上下文但减少 token 消耗,用 /compact。项目的 CLAUDE.md 和 memory 不会被清除。
/compact— 压缩上下文
解决什么问题:长时间编码会话导致上下文接近窗口上限,模型开始"遗忘"早期内容或拒绝响应。 何时使用:出现 "context window almost full" 提示、会话超过数百轮交互、完成阶段性工作准备进入下一阶段。
工作原理:将历史对话总结为摘要,释放大量 token 空间。通过 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 可调整自动触发阈值。
触发时机判断:
- 会话轮数 > 100 轮 → 建议主动压缩
- 出现 token 不足警告 → 必须压缩
- 开始新话题前 → 可选压缩
/cost— 费用统计
解决什么问题:想知道当前会话用了多少 token、花了多少钱,是否在预算内。 何时使用:大规模任务后检查费用、对比不同策略的 token 效率、项目预算管控。
输出内容:输入/输出 Token 数量、缓存命中率、估算费用(美元)、当前使用的模型。
典型使用:
- 每次大的代码生成后:/cost 确认没有异常消耗
- 日终检查:/cost 汇总当天各项目的 API 费用
- 策略对比:方案 A 用了 50K token vs 方案 B 用了 200K token → 反思 prompt 效率
/context— 上下文窗口分析
解决什么问题:不知道当前上下文用了多少空间、哪些内容占比最大、还剩多少空间。 何时使用:评估是否需要压缩、优化 CLAUDE.md 内容量、排查上下文消耗过快的原因。
输出包含:已用/总 Token 数、各部分占比(系统提示词/CLAUDE.md/对话/工具结果)、剩余空间。
/export— 导出会话
解决什么问题:需要将当前会话存档、分享给他人、或导入其他工具分析。 何时使用:项目归档、知识分享、会话分析、备份重要讨论。
|
1
2
|
/export # 导出到默认位置
/export ~/sessions/ # 导出到指定目录
|
/resume— 恢复会话
解决什么问题:从当前会话快速跳转到另一个历史会话,不必退出重启。 何时使用:在多个并行任务间切换、回到之前的讨论、查看历史会话。
|
1
2
|
/resume # 打开交互式选择器
/resume abc123 # 恢复到指定会话
|
/model— 切换模型
解决什么问题:不同阶段需要不同模型能力——设计阶段要深度思考(Opus),实现阶段要速度(Sonnet)。 何时使用:架构设计时切到 Opus,编码实现时切回 Sonnet。
|
1
2
3
4
|
/model # 查看当前模型
/model opus # 切换:架构设计 / 深度分析
/model sonnet # 切换:日常编码(默认)
/model haiku # 切换:快速批量处理
|
典型工作流:
|
1
2
|
/model opus → "设计支付系统的微服务拆分方案" (深度分析)
/model sonnet → "按照方案实现支付模块的代码" (快速编码)
|
/fast— 快速模式
解决什么问题:当前任务比较简单,不需要深度思考,想要更快的响应速度。 何时使用:简单格式化、文本翻译、快速问答。
|
1
2
|
/fast # 启用快速模式
/fast off # 关闭
|
/name— 命名会话
解决什么问题:会话进行中发现之前的命名不合适,或者开始时忘了命名。 何时使用:会话中随时重命名,确保后续 /resume 能一眼识别。
3.2 代码审查与质量命令
/review— PR 审查
解决什么问题:代码写完了,提交 PR 前需要全面审查——正确性、安全性、性能、可维护性。 何时使用:提交 PR 前、代码合并前、Code Review 环节。
审查维度:
- 代码正确性:逻辑错误、边界条件
- 安全性:注入风险、权限问题
- 性能:N+1 查询、不必要的循环
- 可维护性:命名规范、代码重复、耦合度
最佳实践:/review → /fix(修复问题) → /verify(验证修复)
/security-review— 安全审查
解决什么问题:代码可能包含安全漏洞,需要专门的安全视角审查——普通审查可能遗漏安全问题。 何时使用:涉及认证/授权的代码、处理用户输入的代码、支付/敏感数据相关代码。
审查重点:OWASP Top 10、认证绕过、注入攻击、敏感数据泄露、不安全反序列化、加密正确性。
/code-review— 代码质量审查
解决什么问题:代码能工作但质量不高——有重复、命名不好、逻辑复杂、效率低。 何时使用:重构前评估、代码规范化、技术债务清理。
|
1
2
|
/code-review
/code-review --effort high # 更深入的审查
|
与 /review 的区别:/review 面向 PR 全面审查(含功能正确性),/code-review 侧重代码质量改进。
/simplify— 代码简化
解决什么问题:代码有明显冗余——重复逻辑、过长表达式、无用变量,需要自动简化。 何时使用:代码 review 后发现冗余、重构时提取公共逻辑、减少技术债务。
简化内容:提取重复代码、简化条件表达式、移除无用导入/变量、合并可合并的类/方法。
/verify— 验证代码更改
解决什么问题:代码写完了但不能确定是否真的按预期工作——需要实际运行验证。 何时使用:代码修改后、Bug 修复后、新功能开发完成后。
验证流程:启动应用 → 执行相关功能 → 检查输出/日志 → 截图(Web) → 报告结果。
/fix— 修复问题
解决什么问题:代码有问题(编译报错、运行时异常、逻辑错误),需要自动诊断并修复。 何时使用:编译/测试失败后、发现 Bug 后、代码审查发现的问题需要修复。
|
1
2
|
/fix # 修复最近讨论的问题
/fix 登录接口返回500错误 # 修复特定问题
|
3.3 开发流程命令
/run— 启动应用
解决什么问题:需要运行项目看效果,但不想手动敲启动命令、配置环境。 何时使用:开发过程中频繁启动应用验证、运行测试、触发特定功能。
|
1
2
|
/run # 按项目类型自动启动
/run "启动后端并测试登录API" # 带指令启动
|
Claude 会自动识别项目类型(Spring Boot / Node.js / Python 等)并使用正确的启动命令。
/loop— 定时循环
解决什么问题:需要定期执行某个任务——监控部署状态、检查 CI/CD、轮询服务健康。 何时使用:部署后监控、CI/CD 状态轮询、定期健康检查、长时间运行任务的进度追踪。
|
1
2
3
|
/loop 5m /run "检查健康状态" # 每5分钟
/loop 30m "检查部署状态" # 每30分钟
/loop 1h /review # 每小时
|
时间格式:Xs(秒)、Xm(分钟)、Xh(小时)。
/batch— 批量处理
解决什么问题:需要大规模修改(比如统一 50 个 Controller 的异常处理),手动逐个改太慢。 何时使用:全局代码规范统一、框架迁移、批量重构。
|
1
2
|
/batch "将所有 Controller 层的异常处理统一为 GlobalExceptionHandler"
/batch "将所有 DAO 接口迁移到 JPA Repository"
|
工作流程:分析代码库 → 拆分任务(5-30个) → 并行执行(每个在独立 worktree) → 汇总结果。
/workflows— 工作流管理
解决什么问题:运行了 Workflow 后需要查看进度、或需要停止某个失控的工作流。 何时使用:监控长时间运行的 Workflow、调试 Workflow 脚本。
|
1
2
|
/workflows # 查看工作流状态
/workflows stop <id> # 停止指定工作流
|
/tasks— 任务管理
解决什么问题:复杂任务需要分解为多个子任务并追踪进度——哪个完成了、哪个还在进行、哪个被阻塞。 何时使用:多步骤任务、Team 协作、Sprint 规划。
|
1
2
3
4
|
/tasks # 查看所有任务
/tasks add "修复登录Bug" # 添加
/tasks done 3 # 完成编号为3的任务
/tasks priority 1 high # 设置优先级
|
3.4 配置命令
/config— 快速配置
解决什么问题:不想手动编辑 settings.json,需要交互式修改基础设置。 何时使用:首次使用 Claude Code 时配置偏好、快速切换主题或模型。
|
1
2
3
|
/config # 交互式配置
/config theme # 配置主题
/config model # 配置默认模型
|
/settings— 打开配置文件
解决什么问题:需要直接编辑某个层级的 settings.json,但不确定文件在哪。 何时使用:手动修改高级配置项、排查配置问题。
|
1
2
3
|
/settings # 打开项目级
/settings user # 打开用户级
/settings local # 打开本地覆盖
|
/permissions— 权限管理
解决什么问题:需要允许/禁止某些工具操作——比如允许 npm 但禁止 rm。 何时使用:初次配置项目安全策略、排查权限拒绝问题。
|
1
2
3
|
/permissions # 打开权限管理
/permissions allow "Bash(git *)" # 添加允许
/permissions deny "Bash(rm *)" # 添加拒绝
|
/hooks— Hooks 管理
解决什么问题:需要在特定事件(工具调用前后)执行自定义脚本。 何时使用:配置自动化监控、安全拦截、通知。
|
1
2
|
/hooks # 查看当前 hooks
/hooks add postToolUse "python3 monitor.py" # 添加 hook
|
/statusline— 状态栏
解决什么问题:想在终端看到当前模型、token 消耗、git 分支等实时信息。 何时使用:配置工作界面、提高信息可见性。
|
1
2
3
|
/statusline # 交互式配置
/statusline enable # 启用
/statusline disable # 禁用
|
可显示信息:当前模型和努力级别、Token 消耗、Git 分支/状态、当前时间。
/theme— 切换主题
|
1
2
|
/theme light # 浅色
/theme dark # 深色
|
/terminal-theme— 终端主题
|
1
|
/terminal-theme # 切换终端配色
|
/ide— IDE 集成管理
解决什么问题:需要在 Claude Code 和 IDE 之间切换——在 IDE 中查看 Claude 建议的文件,或反之。 何时使用:开发过程中需要 IDE 和 Claude Code 协同工作。
|
1
2
3
|
/ide connect # 连接 IDE
/ide disconnect # 断开
/ide status # 查看状态
|
3.5 Agent 与插件命令
/agents— Agent 管理
解决什么问题:需要查看或控制后台运行的 Agent——分配新任务、停止卡住的 Agent。 何时使用:多 Agent 并行工作时、需要监控 Agent 状态。
|
1
2
3
|
/agents # 查看运行中的 Agent
/agents spawn "审查代码" # 创建新 Agent
/agents stop <id> # 停止 Agent
|
/memory— 记忆管理
解决什么问题:有些信息需要跨会话记住——项目约定、用户偏好、已确认的决策。 何时使用:保存重要的项目上下文、查看已有记忆、删除过时记忆。
|
1
2
3
|
/memory # 查看所有记忆
/memory add "这个项目使用 Java 17" # 添加
/memory delete <id> # 删除
|
3.6 诊断与反馈命令
/init— 初始化项目
解决什么问题:新项目或刚引入 Claude Code 的项目,需要自动生成 CLAUDE.md 描述代码库。 何时使用:首次在项目中使用 Claude Code、项目结构变化后更新文档。
生成内容:项目概览和技术栈、构建运行命令、架构说明、关键目录文件。
/doctor— 健康诊断
解决什么问题:Claude Code 表现异常——连不上、配置不生效、版本太旧。 何时使用:遇到不明错误时作为第一步排查。
诊断内容:CLI 版本和更新状态、认证状态、配置文件有效性、网络连接。
/upgrade— 更新 CLI
|
1
2
|
/upgrade # 检查并安装
/upgrade check # 仅检查
|
/bug— 问题反馈
解决什么问题:发现 Claude Code 本身的 Bug,需要向 Anthropic 报告。 何时使用:遇到非预期行为、功能缺失、崩溃。
|
1
2
|
/bug # 交互式提交
/bug "Hooks 在特定场景下不触发" # 快速提交
|
四、键盘快捷键
4.1 完整快捷键速查表
快捷键配置存储在 ~/.claude/keybindings.json 中。
会话控制
| 快捷键 |
功能 |
何时使用 |
| Ctrl+C |
取消输出/返回提示 |
Claude 回答跑偏时中断 |
| Ctrl+D |
退出会话 |
完成任务后退出 |
| Ctrl+L |
清屏 |
输出太多需要视觉刷新 |
| Ctrl+O |
新会话 |
开始全新讨论 |
| Ctrl+S |
发送消息 |
提交当前 prompt |
| Ctrl+T |
会话选择器 |
在历史会话间切换 |
| Ctrl+R |
恢复最近会话 |
快速回到上次工作 |
上下文与编辑
| 快捷键 |
功能 |
何时使用 |
| Ctrl+K |
清除上下文 |
快速重置对话 |
| Ctrl+Shift+I |
IDE 集成 |
打开/关闭 IDE 同步 |
| Ctrl+P |
粘贴最近文件路径 |
快速引用文件 |
| Ctrl+E |
文件浏览器 |
浏览项目文件 |
| Ctrl+F |
搜索 |
搜索当前会话文本 |
| ↑/↓ |
历史命令 |
浏览之前输入 |
| Tab |
补全/切换焦点 |
自动补全路径 |
| Shift+Enter |
换行 |
多行消息 |
面板
| 快捷键 |
功能 |
| Ctrl+Shift+P |
命令面板 |
| Ctrl+Shift+O |
大纲视图 |
| Ctrl+Shift+M |
MCP 管理 |
| Ctrl+Shift+S |
状态栏 |
4.2 自定义快捷键
编辑 ~/.claude/keybindings.json:
|
1
2
3
4
5
6
7
8
9
10
|
{
"bindings": [
{ "key": "Ctrl+Q", "action": "quit" },
{ "key": "Ctrl+B", "action": "toggle-sidebar" },
{ "key": "Ctrl+G", "action": "open-git-panel" },
{ "key": "Ctrl+Shift+R", "action": "run-command:/review" },
// 和弦键:先按 Ctrl+K,再按 Ctrl+B
{ "key": "Ctrl+K Ctrl+B", "action": "toggle-sidebar" }
]
}
|
常用 Action:quit、toggle-sidebar、toggle-debug、open-git-panel、open-file-browser、clear-screen、new-session、run-command:/xxx。
五、配置文件系统
5.1 配置层级与优先级
核心问题:团队共享配置 vs 个人偏好,如何优雅共存?
三级配置系统(优先级从高到低):
|
1
2
3
|
1. .claude/settings.local.json (本地) ← 不提交 git,个人偏好
2. .claude/settings.json (项目) ← 提交 git,团队共享
3. ~/.claude/settings.json (用户) ← 全局默认
|
合并规则:
- 高优先级覆盖低优先级的同名字段
- permissions.allow 数组是追加合并
- env 对象是浅合并(同名 key 覆盖)
实际案例:
|
1
2
3
4
5
6
7
8
9
10
|
// 用户级 → 所有项目的默认值
{ "model": "sonnet", "theme": "dark", "effort": "medium" }
// 项目级 → 团队约定:这个项目需要 Opus 和高努力
{ "model": "opus", "effort": "max" }
// 实际生效:model=opus, effort=max, theme=dark(继承)
// 本地级 → 个人 override
{ "theme": "light" }
// 实际生效:model=opus, effort=max, theme=light
|
加载控制:
|
1
2
|
claude --setting-sources user,project # 忽略本地
claude --settings ./ci-settings.json # 加载额外配置
|
5.2 settings.json 完整配置参考
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
|
{
// ═══ 环境变量 ═══
"env": {
"ANTHROPIC_API_KEY": "sk-ant-api03-xxx",
"ANTHROPIC_BASE_URL": "https://api.anthropic.com",
"ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
"ANTHROPIC_MAX_TOKENS": "8192",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75",
"CLAUDE_CODE_EFFORT_LEVEL": "max",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true",
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
// ═══ 模型与努力 ═══
"model": "sonnet",
"effort": "max",
// ═══ 外观 ═══
"theme": "dark",
"alwaysThinkingEnabled": true,
// ═══ 权限 ═══
"permissions": {
"allow": ["Bash(git:*)", "Bash(npm:*)", "Bash(mvn:*)", "Read", "Edit", "Write"],
"deny": ["Bash(rm -rf:*)", "Bash(sudo:*)"],
"defaultMode": "acceptEdits"
},
// ═══ 状态栏 ═══
"statusLine": {
"type": "command",
"command": "echo '???? $(basename $PWD) | ???? $(git branch --show-current 2>/dev/null)'"
},
// ═══ Hooks ═══
"hooks": {
"postToolUse": "python3 ~/.claude/scripts/monitor.py"
}
}
|
5.3 CLAUDE.md 详解
核心问题:如何让 Claude Code 在每个项目中自动遵循特定的编码规范和项目约定?
文件位置与作用域:
| 文件 |
何时加载 |
作用 |
提交 Git |
| ~/.claude/CLAUDE.md |
所有会话 |
个人全局偏好 |
? |
| {project}/CLAUDE.md |
该项目会话 |
项目技术栈约定 |
? |
| {project}/.claude/CLAUDE.md |
该项目会话 |
同上(备选位置) |
? |
完整模板:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
# CLAUDE.md
## 项目概述
Spring Boot 3.2 + Vue 3 的监控数据采集分析平台。
## 技术栈
- Backend: Java 17 + Spring Boot 3.2.5 + JPA
- Frontend: Vue 3 + Vite + Element Plus
- DB: MySQL 8.0 + Flyway 迁移
- Cache: Redis 7
## 构建命令
- 后端: `mvn clean package -DskipTests`
- 前端: `cd frontend && npm run dev`
- 测试: `mvn test -Dtest=ClassName#methodName`
## 代码规范
- 所有 public 方法必须有 Javadoc
- Controller 层使用 @Valid 做参数校验
- 异常统一由 GlobalExceptionHandler 处理
## API 路由
- /api/v1/** — 数据上报
- /admin/** — 管理后台
|
5.4 ~/.claude 目录完整剖析
以下是 ~/.claude/ 下每一个文件和子目录的详细说明,基于实际环境分析。
根目录文件
CLAUDE.md — 用户全局指令
作用:定义对所有项目生效的个人偏好和规则。每次 Claude Code 启动时自动加载。 何时创建/修改:首次使用 Claude Code 时、需要添加全局编码偏好时。
格式:Markdown。 管理:vim ~/.claude/CLAUDE.md 或通过对话修改。?? 自进化系统修改此文件需用户确认。
settings.json — 用户全局配置
作用:存储所有项目的默认配置——模型、权限、Hooks、环境变量。最重要的配置文件。 何时修改:更改默认模型、添加权限规则、配置 Hooks。
管理:vim ~/.claude/settings.json 或 /settings user。? permissions/env/model 字段禁止自进化系统修改。
settings.json.bak.json — 配置备份
作用:settings.json 的自动备份副本。Claude Code 更新或修改配置时自动创建。 何时使用:settings.json 损坏时从此恢复。
|
1
|
cp ~/.claude/settings.json.bak.json ~/.claude/settings.json
|
.mcp.json — 用户级 MCP 配置
作用:存储用户级 MCP 服务器定义,所有项目共享。 何时修改:添加全局可用的数据库/API 工具时。
|
1
|
{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"] } } }
|
history.jsonl — 命令历史
作用:JSONL 格式记录所有会话的命令历史,支持 ↑/↓ 浏览。 ?? 隐私注意:包含你在 Claude Code 中输入的所有内容。
|
1
|
{"display":"用户命令","pastedContents":{},"timestamp":1781165706131,"project":"/path","sessionId":"uuid"}
|
.gitignore — Git 忽略规则
作用:~/.claude/ 目录本身是 Git 仓库,此文件排除 sessions/projects/telemetry 等敏感/易变内容。
.last-cleanup — 最后清理时间
作用:记录最后一次自动清理的时间戳。系统自动维护。
mcp-needs-auth-cache.json — MCP 认证缓存
作用:缓存哪些 MCP 服务器需要 OAuth 认证,避免重复弹窗。
核心功能目录
agents/ — 自定义 Agent 定义
作用:每个 .md 文件定义一个专门的 Agent 角色。 何时添加:需要特定领域的审查专家(安全/性能/Android 等)时。
|
1
2
3
4
5
6
|
agents/
├── anr-reviewer.md # Android ANR 审查
├── gpu-cpu-reviewer.md # GPU/CPU 性能审查
├── memory-leak-reviewer.md # 内存泄露审查
├── perf-integrator.md # 性能审查整合
└── marketing-*.md # 各平台营销策略师
|
skills/ — 已安装的 Skill/插件
作用:存放所有已安装 Skill。每个子目录 = 一个 Skill/插件。 何时添加:通过 claude plugin install 或 claude plugin init。
|
1
2
3
4
5
6
|
skills/
├── figma-to-android/ # Figma → Android UI
├── self-evolution/ # 自进化(review.md + evolve.md)
├── android-code-style/ # Android 代码规范
├── pdf/ docx/ pptx/ xlsx/ # 办公文档处理
└── ... # 20+ Skill
|
teams/ — Agent Teams 配置
作用:多 Agent 协作的团队配置。?? 实验性功能。 何时使用:需要多个专业 Agent 协同完成复杂任务时。
scripts/ — 自定义辅助脚本
作用:存放被 Hooks 调用的自定义脚本。 内容:monitor.py(工具调用监控)、auto_review.py(自主复盘触发)。
evolution/ — 自进化系统数据
作用:存储运行日志和变更历史。 内容:changelog.md(版本历史)、run_logs.jsonl(工具调用日志)、reviews/(复盘报告)。
会话与状态目录
sessions/ — 会话索引
作用:以 PID 命名的 JSON 文件,记录活跃会话的元信息。
|
1
|
{ "pid":14464, "sessionId":"uuid", "cwd":"/path", "name":"task-name", "status":"idle" }
|
session-env/ — 会话环境快照
作用:按 session-id 存储 shell 环境变量,恢复会话时还原。
projects/ — 项目状态与持久记忆
作用:按项目路径组织的数据。子目录命名:/Users/xxx/project → -Users-xxx-project。 子目录:<session-id>.jsonl(对话记录,可达 500KB+)、memory/(持久记忆,MEMORY.md 为索引)。
tasks/ — 任务列表数据
作用:按 Team/会话 ID 组织,存储结构化任务数据。
plans/ — 计划模式文档
作用:Plan Mode 生成的计划文件。命名格式:adjective-verb-noun.md。
缓存与历史目录
file-history/ — 文件编辑历史
作用:按会话 ID 组织,追踪每个会话的文件修改记录,支持撤销。
paste-cache/ — 粘贴内容缓存
作用:Ctrl+P 快速粘贴的文本缓存,以内容哈希命名。
shell-snapshots/ — Shell 环境快照
作用:snapshot-{shell}-{timestamp}-{random}.sh 格式,用于会话恢复时精确还原环境。
backups/ — 配置自动备份
作用:.claude.json.backup.{timestamp} 格式,每次更新配置时自动创建(约 70KB 每个)。
|
1
2
|
ls -la ~/.claude/backups/
cp ~/.claude/backups/.claude.json.backup.1781164919093 ~/.claude/settings.json # 恢复
|
系统内部目录
ide/ — IDE 集成锁文件
作用:以 IDE 进程 PID 命名的 .lock 文件,管理连接状态,防止重复连接。
telemetry/ — 遥测失败事件队列
作用:网络不稳定时暂存发送失败的遥测数据,重启后自动重试。
.git/ — 配置版本控制
作用:~/.claude/ 是 Git 仓库,追踪配置文件变更。
|
1
|
cd ~/.claude && git log --oneline -20 # 查看配置变更历史
|
gomoku/ — 五子棋存档
作用:内置五子棋小游戏的存档(趣味功能)。
完整目录树
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
~/.claude/
├── ???? CLAUDE.md # 用户全局指令
├── ???? settings.json # 用户全局配置
├── ???? settings.json.bak.json # 配置备份
├── ???? .mcp.json # 用户级 MCP 配置
├── ???? history.jsonl # 命令历史 (~200KB)
├── ???? .gitignore # Git 忽略规则
├── ???? .last-cleanup # 清理时间戳
├── ???? mcp-needs-auth-cache.json # MCP 认证缓存
│
├── ???? .git/ # 配置版本控制
├── ???? agents/ # 自定义 Agent (11个)
├── ???? skills/ # 已安装 Skill (20+)
├── ???? teams/ # Agent Teams 配置
├── ???? scripts/ # 辅助脚本 (monitor.py, auto_review.py)
├── ???? evolution/ # 自进化 (changelog, logs, reviews)
│
├── ???? sessions/ # 会话索引 (<pid>.json)
├── ???? session-env/ # 会话环境快照
├── ???? projects/ # 项目状态 (<session>.jsonl + memory/)
├── ???? tasks/ # 任务列表
├── ???? plans/ # 计划文档
│
├── ???? file-history/ # 文件编辑历史
├── ???? paste-cache/ # 粘贴缓存
├── ???? shell-snapshots/ # Shell 环境快照
├── ???? cache/ # 通用缓存
├── ???? backups/ # 配置备份 (~70KB×N)
│
├── ???? ide/ # IDE 锁文件
├── ???? telemetry/ # 遥测队列
└── ???? gomoku/ # 五子棋存档
|
5.4.7 磁盘空间与清理
| 目录 |
典型大小 |
趋势 |
清理建议 |
| history.jsonl |
~200KB |
增长 |
可安全删除 |
| projects/*.jsonl |
500KB+/会话 |
随会话增长 |
清理旧会话 |
| backups/ |
~70KB×N |
每次更新+1 |
保留最近3-5个 |
| shell-snapshots/ |
每文件几KB |
每会话+1 |
可安全清理 |
| session-env/ |
很小 |
每会话+1 |
可安全清理 |
|
1
2
|
claude project purge --dry-run # 预览
find ~/.claude/projects -name "*.jsonl" -mtime +7 -delete # 清理7天前
|
六、MCP 服务器配置
6.1 MCP 是什么
解决什么问题:Claude 运行在沙箱中,无法直接访问数据库、文件系统、外部 API。MCP 通过标准化协议让 Claude 安全地调用外部工具。 何时使用:需要 Claude 查询数据库、操作文件系统、调用第三方 API、使用自定义工具时。
核心概念:
- MCP 服务器:提供工具/资源/提示词的外部进程
- 传输协议:stdio(本地进程)、HTTP(远程服务)、SSE(事件流)
- 配置范围:user(全局)、project(项目)、local(本地)
6.2 配置完整示例
stdio 服务器(本地进程)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects", "/tmp"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": { "PG_HOST": "localhost", "PG_PASSWORD": "${PG_PASSWORD}" }
},
"git": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git", "/path/to/repo"]
}
}
}
|
HTTP 服务器(远程服务)
|
1
2
3
4
5
6
7
8
9
|
{
"mcpServers": {
"sentry": {
"transport": "http",
"url": "https://mcp.sentry.dev/mcp",
"headers": { "Authorization": "Bearer ${SENTRY_TOKEN}" }
}
}
}
|
6.3 安全最佳实践
- 永远不硬编码密钥:使用 ${ENV_VAR} 引用
- 项目级 MCP 需批准:.mcp.json 首次加载时提示确认
- 最小权限:filesystem 只暴露必要目录
- 定期审计:claude mcp list
七、Hooks 系统
7.1 生命周期事件
解决什么问题:需要在 Claude 执行操作的前后自动触发自定义逻辑——监控、安全拦截、通知、自动保存。 何时使用:记录所有操作日志、拦截危险命令、代码修改后自动格式化、完成后发通知。
|
1
2
3
4
5
6
7
|
用户输入命令
├── ???? preCommand ← 命令执行前
├── Claude 处理...
│ ├── ???? preToolUse ← 工具调用前
│ ├── 工具执行...
│ └── ???? postToolUse ← 工具调用后
└── ???? postCommand ← 命令执行后
|
7.2 Hooks 配置实战
场景一:工具调用监控
|
1
2
3
4
5
|
{
"hooks": {
"postToolUse": "python3 ~/.claude/scripts/monitor.py --tool '$tool_name' --exit '$exit_code'"
}
}
|
场景二:危险操作拦截
|
1
2
3
4
5
|
{
"hooks": {
"preToolUse": "if echo '$tool_input' | grep -q 'rm -rf'; then echo '?? 危险操作已拦截'; exit 1; fi"
}
}
|
场景三:Git 自动暂存
|
1
2
3
4
5
|
{
"hooks": {
"postCommand": "git status --porcelain | grep -q '^M' && git add -A"
}
}
|
场景四:桌面通知
|
1
2
3
4
5
|
{
"hooks": {
"postCommand": "osascript -e 'display notification \"命令执行完毕\" with title \"Claude Code\"'"
}
}
|
八、权限系统
8.1 六种权限模式
解决什么问题:Claude 执行操作时,有的用户可以完全信任(自动化),有的环境需要步步确认(安全敏感)。 何时使用:日常开发用 acceptEdits,CI/CD 用 bypassPermissions,代码阅读用 plan。
| 模式 |
编辑 |
命令 |
网络 |
推荐场景 |
| default |
询问 |
询问 |
询问 |
新用户/不熟悉环境 |
| acceptEdits |
自动 |
询问 |
询问 |
日常开发(推荐) |
| dontAsk |
自动 |
自动 |
询问 |
受信任项目 |
| bypassPermissions |
自动 |
自动 |
自动 |
?? CI/CD |
| plan |
????禁止 |
????禁止 |
????禁止 |
只读分析 |
8.2 精细权限配置
安全开发环境
|
1
2
3
4
5
6
7
8
9
10
11
|
{
"permissions": {
"defaultMode": "acceptEdits",
"allow": [
"Bash(git:*)", "Bash(npm:*)", "Bash(mvn:*)", "Bash(docker:ps,logs,compose*)",
"Bash(ls,cat,echo,pwd,mkdir,touch,cp,mv,find)",
"Read", "Edit", "Write", "Glob", "Grep"
],
"deny": ["Bash(rm -rf:*)", "Bash(sudo:*)", "Bash(curl:*)", "Bash(ssh:*)"]
}
}
|
8.3 通配符规则
| 规则 |
匹配 |
| Bash(git *) |
所有 git 命令 |
| Bash(npm:install,run,test) |
仅这三个子命令 |
| * |
所有工具 |
九、插件系统
9.1 插件完整结构
解决什么问题:需要打包分发 Skill + Agent + Hooks + MCP 的组合,而不是单独管理每个组件。 何时使用:创建可复用的工作流包、在团队间共享自定义工具、发布到市场。
|
1
2
3
4
5
6
7
|
my-plugin/
├── plugin.json # 必需:插件元数据
├── SKILL.md # 必需:Skill 主文档
├── agents/ # 可选:自定义 Agent
├── hooks/ # 可选:Hooks 配置
├── mcp/ # 可选:MCP 配置
└── .claude/settings.local.json # 插件级权限
|
9.2 从创建到发布
|
1
2
3
4
5
6
7
8
9
10
11
12
|
# 1. 创建
claude plugin init my-plugin --with skills,agents,hooks,mcp
# 2. 编辑 SKILL.md 和 plugin.json
# 3. 本地验证
claude plugin validate ./my-plugin
claude --plugin-dir ./my-plugin # 本地测试
# 4. 发布
cd ./my-plugin && git init && git add -A && git commit -m "v1.0.0"
claude plugin tag .
|
十、Agent 系统
10.1 Agent 定义文件
解决什么问题:需要专门的 AI 角色来处理特定领域任务,每个角色有自己的工具权限和能力边界。 何时使用:创建安全审查专家、性能分析师、代码规范检查员等专门角色。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
---
name: security-auditor
description: 专注于安全漏洞审查的专家
model: opus
tools: Read, Grep, Glob, Bash(git *), Bash(grep *)
effort: xhigh
---
# 安全审查专家
## 审查重点
1. OWASP Top 10:注入、认证失效、敏感数据泄露
2. 认证与授权:JWT 使用、权限绕过、Session 安全
3. 注入攻击:SQL 注入、命令注入、XSS
4. 数据保护:硬编码密钥、日志敏感信息
## 输出格式
- 严重级别:Critical / High / Medium / Low
- 文件路径 + 行号 + 问题描述 + 修复建议
|
10.2 内置 Agent 类型
| Agent 类型 |
可用工具 |
典型用途 |
| general-purpose |
全部 |
通用任务 |
| Explore |
Read, Grep, Glob |
代码库探索 |
| Plan |
全部(禁用编辑) |
架构规划 |
| claude-code-guide |
Read, WebFetch |
Claude Code 帮助 |
10.3 使用方式
|
1
2
|
claude --agent security-auditor
claude agents --agent my-agent --model sonnet
|
十一、Teams 系统
11.1 Teams 架构
解决什么问题:单个 Agent 能力有限,复杂任务需要多个专业 Agent 协同——如代码审查需要安全+性能+规范三个视角同时审查。 何时使用:全面的代码审查、多模块并行开发、需要多专家交叉验证的复杂任务。
|
1
2
3
4
5
6
7
8
9
|
┌─────────────┐
│ Team Lead │ ← 协调,分配任务,汇总
└──────┬──────┘
┌──────────────┼──────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Code │ │ Security │ │ Test │
│ Reviewer │ │ Auditor │ │ Writer │
└───────────┘ └───────────┘ └───────────┘
|
实验性功能,需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。
11.2 使用流程
|
1
2
3
|
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude --agent team-lead
# 在 Team Lead 中创建 Team、分配任务、派发 Agent、汇总结果
|
十二、Workflow 工作流系统
12.1 Workflow 概念
解决什么问题:需要确定性的多 Agent 编排——不是让 AI 决定怎么做,而是用代码精确控制流程(并行、流水线、条件分支、循环)。 何时使用:大规模代码审查(多维度 × 多文件)、批量重构(scan→review→fix→verify)、需要结构化输出的自动化流程。
12.2 Workflow 脚本结构
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
|
export const meta = {
name: 'comprehensive-review',
description: '多维度代码审查',
phases: [
{ title: '扫描', detail: '扫描变更文件' },
{ title: '审查', detail: '并行审查' },
{ title: '验证', detail: '交叉验证' }
]
}
phase('扫描')
const changedFiles = await agent('列出变更文件', {
schema: { type: 'object', properties: { files: { type: 'array' } } }
})
phase('审查')
const findings = await pipeline(
[{ key: 'bugs' }, { key: 'security' }, { key: 'perf' }],
dim => agent(`审查 ${dim.key}`, { schema: FINDINGS_SCHEMA }),
review => parallel(
review.findings.map(f => () =>
agent(`验证: ${f.title}`, { schema: VERDICT_SCHEMA })
)
)
)
return { confirmed: findings.flat().filter(f => f.verdict?.isReal) }
|
12.3 核心 API
agent(prompt, opts)— 启动子 Agent
|
1
2
3
4
|
const result = await agent('分析代码质量') // 返回文本
const bugs = await agent('查找Bug', { schema: BUG_SCHEMA }) // 返回验证过的 JSON
await agent('重构', { isolation: 'worktree' }) // 隔离环境中运行
await agent('审查', { agentType: 'security-auditor' }) // 使用特定 Agent
|
parallel(thunks)— 并行屏障
|
1
2
3
4
5
6
|
// 所有任务并发,全部完成后返回
const results = await parallel([
() => agent('任务A'),
() => agent('任务B'),
() => agent('任务C')
])
|
使用判断:需要收集所有结果后再决策时用 parallel,否则用 pipeline。
pipeline(items, stage1, stage2, ...)— 流水线
|
1
2
3
4
5
6
|
// 每个 item 独立流经所有阶段,阶段间不等待
const results = await pipeline(
items,
item => stage1(item),
result => stage2(result)
)
|
phase(title)/log(message)— 进度显示
|
1
2
|
phase('审查') // 开始新阶段
log('发现 5 个问题') // 输出进度
|
十三、自进化系统
13.1 五维闭环
解决什么问题:Claude Code 在运行中会反复出现某些错误模式,需要自动检测、分析、修复这些模式,让系统越来越稳定。 何时自动运行:通过 Cron 定时触发,或手动通过命令触发。
|
1
|
执行 → 监控 → 复盘 → 改写 → 沉淀 → (反馈到下次执行)
|
| 环节 |
组件 |
功能 |
| ① 执行 |
Claude 会话 |
正常执行任务 |
| ② 监控 |
postToolUse Hook → monitor.py |
采集工具调用结果/耗时/错误 |
| ③ 复盘 |
/自主复盘 → review.md |
分析错误模式,判定严重级别 |
| ④ 改写 |
/自我进化 → evolve.md |
生成改进方案,worktree 中验证 |
| ⑤ 沉淀 |
evolution/changelog.md |
记录变更,反馈到下次执行 |
13.2 安全边界
| 级别 |
可修改 |
示例 |
| ? 自主 |
skills/、scripts/、evolution/ |
优化 Skill 提示词 |
| ?? 需确认 |
CLAUDE.md、settings.json hooks |
变更用户指令 |
| ? 禁止 |
settings.json permissions/env/model |
扩大权限 |
十四、IDE 集成
14.1 支持的功能
| 功能 |
VS Code |
JetBrains |
| 自动检测 |
? |
? |
| 文件跳转 |
? |
? |
| 内联建议 |
? |
? |
| Diff 预览 |
? |
? |
14.2 使用方式
|
1
2
3
4
|
claude --ide # 启动时连接 IDE
claude --chrome # Chrome 集成
/ide connect # 会话中连接
Ctrl+Shift+I # 快捷键
|
十五、环境变量参考
15.1 完整环境变量表
| 变量 |
说明 |
示例 |
必需 |
| ANTHROPIC_API_KEY |
API 密钥 |
sk-ant-api03-xxx |
? |
| ANTHROPIC_BASE_URL |
API URL |
https://api.anthropic.com |
? |
| ANTHROPIC_MODEL |
默认模型 |
claude-sonnet-4-20250514 |
? |
| ANTHROPIC_MAX_TOKENS |
最大 Token |
8192 |
? |
| CLAUDE_CODE_SUBAGENT_MODEL |
子 Agent 模型 |
claude-sonnet-4-6 |
? |
| CLAUDE_AUTOCOMPACT_PCT_OVERRIDE |
压缩阈值% |
75 |
? |
| CLAUDE_CODE_EFFORT_LEVEL |
努力级别 |
max |
? |
| CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS |
启用 Teams |
1 |
? |
| CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC |
禁用非必要流量 |
true |
? |
15.2 模型版本
| 简称 |
当前模型 ID |
特点 |
| sonnet |
claude-sonnet-4-20250514 |
速度能力平衡(默认) |
| opus |
claude-opus-4-20250514 |
最强推理 |
| haiku |
claude-haiku-4-5-20251001 |
最快速最便宜 |
十六、常用工作流
16.1 日常开发
|
1
2
|
claude -c # 继续昨天
# 在会话中:讨论 → 生成代码 → /run → /fix → /review → commit
|
16.2 PR 审查
|
1
2
3
4
5
|
# 快速审查
/review → /code-review → /simplify
# 深度审查(重要 PR)
claude ultrareview main --timeout 60
|
16.3 大规模重构
|
1
2
3
|
claude -w refactor --model opus --effort max # 隔离环境
/batch "将认证模块从 Session 迁移到 JWT" # 批量执行
/review → /verify # 审查验证
|
16.4 CI/CD 集成
|
1
2
3
4
5
|
claude -p "审查这次变更:$(git diff origin/main...HEAD)" \
--output-format json --permission-mode bypassPermissions
claude -p "修复 lint 错误:$(npm run lint 2>&1)" \
--permission-mode bypassPermissions
|
16.5 定时监控
|
1
2
|
/loop 10m /run "检查 API 健康"
/loop 1h "检查过去1小时的应用日志,报告新增错误"
|
16.6 MCP 集成
|
1
2
3
|
claude mcp add db -e PG_HOST=prod -- npx @modelcontextprotocol/server-postgres
# 在会话中自然语言:"查询今天 crash_log 表的错误分布"
claude mcp remove db # 用完移除
|