Claude Code CLI 完整命令参考手册

Claude Code CLI 完整命令参考手册

适用版本 : Claude Code CLI v2.1.168+ 最后更新 : 2026-06-11 官方文档 : code.claude.com/docs

---

目录

• [一、CLI 命令行参数](#一、CLI 命令行参数 "#%E4%B8%80cli-%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%8F%82%E6%95%B0")
• [二、CLI 子命令](#二、CLI 子命令 "#%E4%BA%8Ccli-%E5%AD%90%E5%91%BD%E4%BB%A4")
• 三、交互式斜杠命令
• 四、键盘快捷键
• 五、配置文件系统
• [六、MCP 服务器配置](#六、MCP 服务器配置 "#%E5%85%ADmcp-%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%85%8D%E7%BD%AE")
• [七、Hooks 系统](#七、Hooks 系统 "#%E4%B8%83hooks-%E7%B3%BB%E7%BB%9F")
• 八、权限系统
• 九、插件系统
• [十、Agent 系统](#十、Agent 系统 "#%E5%8D%81agent-%E7%B3%BB%E7%BB%9F")
• [十一、Teams 系统](#十一、Teams 系统 "#%E5%8D%81%E4%B8%80teams-%E7%B3%BB%E7%BB%9F")
• [十二、Workflow 工作流系统](#十二、Workflow 工作流系统 "#%E5%8D%81%E4%BA%8Cworkflow-%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%B3%BB%E7%BB%9F")
• 十三、自进化系统
• [十四、IDE 集成](#十四、IDE 集成 "#%E5%8D%81%E5%9B%9Bide-%E9%9B%86%E6%88%90")
• 十五、环境变量参考
• 十六、常用工作流

---

一、CLI 命令行参数

claude [options] [command] [prompt]

1.1 核心参数

-p, --print --- 非交互式输出

解决什么问题 ：需要在脚本、CI/CD 或管道中调用 Claude，而不希望进入交互式对话模式。 何时使用：Shell 脚本自动化、CI/CD 流水线中的代码审查、管道组合处理文本、批量分析任务。

# 基础用法：单次问答
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 --- 继续最近会话

解决什么问题 ：中断工作后想要无缝恢复，不想重新描述上下文和需求。 何时使用：每天早上继续昨天的工作、终端意外关闭后恢复、在多个项目间切换后回到之前的项目。

# 最简单的继续方式
claude -c

# 继续会话并指定模型
claude -c --model opus

# 继续会话并以特定模式运行
claude -c --effort max

工作原理 ：-c 会读取当前工作目录 (cwd) 下最近一次会话的完整上下文并从上次中断处继续。不同目录的会话互不影响。

注意事项：

• 如果当前目录没有历史会话，会自动创建新会话
• 继续的会话与原会话共享同一个 session ID

---

-r, --resume [value] --- 恢复指定会话

解决什么问题 ：有多个并行会话，需要精确恢复到某一个特定会话（可能是几天前的）。 何时使用：恢复几天前的特定会话、在多个并行任务间切换、恢复被系统重启中断的会话。

# 交互式选择器（列出所有历史会话，支持搜索过滤）
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 并行处理、不确定的修改需要可随时丢弃。

# 创建命名 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	最快	最低	极速任务：日志分类、简单格式化、批量小任务

claude --model opus
export ANTHROPIC_MODEL=claude-opus-4-8  # 持久化设置

---

--effort <level> --- 努力级别

解决什么问题 ：控制 Claude 的思考深度------深度思考质量更高但更慢更贵，简单任务不需要深度思考。 何时使用：日常开发用 medium，复杂逻辑用 high，安全审查/架构设计用 max，简单格式化用 low。

级别	思考深度	适用场景
low	快速回答	格式转换、简单翻译
medium	适度思考（默认）	日常开发
high	深度思考	复杂逻辑
xhigh	高度深入	架构建议
max	最大努力	安全审查、关键代码

claude -p "格式化 JSON" --effort low
claude --effort max --model opus   # 最强组合

---

--name, -n <name> --- 会话命名

解决什么问题 ：多个会话后难以区分哪个是哪个，需要给会话起个有意义的名字便于后续查找。 何时使用：每次启动新会话时都应该命名。

claude -n "修复用户登录超时Bug"
claude -n "重构支付模块" --model opus --effort max

命名建议 ：动词+对象+描述，如 重构用户认证模块、修复订单列表分页Bug。

---

--session-id <uuid> --- 指定会话 ID

解决什么问题 ：需要精确控制会话标识，实现脚本化的会话管理。 何时使用：自动化脚本中管理会话生命周期。

SESSION_ID=$(uuidgen)
claude --session-id $SESSION_ID -p "分析项目结构"

---

1.2 调试参数

--debug [filter] --- 调试模式

解决什么问题 ：遇到问题需要排查------API 报错、Hooks 不触发、MCP 连接失败等。 何时使用：排查 API 调用异常、Hooks 不工作、MCP 服务器连接问题。

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 连接、或不确定为何某个行为不符合预期时。

claude --verbose -p "分析这个文件"

---

1.3 系统提示参数

--system-prompt <prompt> --- 完全替换系统提示词

解决什么问题 ：需要完全自定义 Claude 的角色和行为，不想要任何默认的 Claude Code 指令。 何时使用：构建自定义 AI 应用，需要特定角色行为（⚠️ 会移除 Claude Code 的所有内置工具使用能力，谨慎使用）。

claude --system-prompt "You are a Python code reviewer..."

--append-system-prompt <prompt> --- 追加系统提示词

解决什么问题 ：在保留 Claude Code 默认能力的基础上，追加项目特定的行为约束。 何时使用：添加项目特定的编码规范、语言偏好、框架约定（推荐用 CLAUDE.md 替代）。

claude --append-system-prompt "始终使用 Java 17 语法。所有 public 方法必须有 Javadoc。"
claude --append-system-prompt "$(cat custom-instructions.txt)"

--bare --- 极简模式

解决什么问题 ：需要最快启动速度，或者怀疑 hooks/插件导致了问题需要排查。 何时使用：排查插件冲突、受限环境运行、追求最小资源占用。

claude --bare -p "快速查询"

---

1.4 权限参数

--permission-mode <mode> --- 权限模式

解决什么问题 ：控制 Claude 执行操作时需要用户确认的频率和范围。 何时使用 ：日常开发用 acceptEdits（自动编辑，其他确认），CI/CD 用 bypassPermissions，代码阅读用 plan。

模式	编辑	命令	网络	场景
default	询问	询问	询问	不熟悉的环境
acceptEdits	自动	询问	询问	日常开发推荐
bypassPermissions	自动	自动	自动	⚠️ CI/CD/沙箱
plan	禁止	禁止	禁止	只读分析

claude --permission-mode acceptEdits
claude --permission-mode plan       # 纯分析，不修改

--allowedTools / --disallowedTools --- 工具白名单/黑名单

解决什么问题 ：需要精细控制 Claude 可以使用哪些工具，比如只允许 git 操作但不允许删除文件。 何时使用：安全敏感环境、CI/CD 自动化、限制 Claude 的破坏性操作能力。

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	实时流处理

claude -p "分析错误日志" --output-format json --json-schema '{"type":"object",...}'

---

二、CLI 子命令

2.1 claude agents --- 后台 Agent 管理

解决什么问题 ：同时运行多个 Agent 执行不同任务，需要一个管理界面来监控和控制它们。 何时使用：并行代码审查、多模块同步开发、批量任务分发与监控。

claude agents                                       # 启动管理界面
claude agents --model sonnet --effort high           # 设置 Agent 默认参数
claude agents --json                                 # JSON 输出（脚本监控）
claude agents --cwd /path/to/project                 # 限定项目范围

---

2.2 claude auth --- 认证管理

解决什么问题 ：管理 Claude Code 的登录状态------首次使用需要登录，切换账号需要重新认证，排查认证失败需要查看状态。 何时使用：首次安装后登录、切换 API Key、排查认证相关问题。

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.3 claude mcp --- MCP 服务器管理

解决什么问题 ：需要让 Claude 访问外部工具和数据源（数据库、文件系统、API 等），通过 MCP 协议标准化集成。 何时使用：集成数据库查询、文件系统操作、第三方 API、自定义工具。

添加 MCP 服务器

# 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

查看和管理

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.4 claude plugin --- 插件管理

解决什么问题 ：需要扩展 Claude Code 的功能------安装社区或自定义的 Skill、Agent、Hooks 组合包。 何时使用：安装第三方 Skill、创建自定义工作流插件、管理插件的启用/禁用/更新。

# 创建插件
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.5 claude ultrareview --- 云托管深度代码审查

解决什么问题 ：普通 /review 只是单 Agent 本地审查，对于重要 PR 需要云端多 Agent 并行交叉验证的深度审查。 何时使用：重要 PR 合并前、安全关键代码变更、发布前的最终质量把关。

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 其他子命令

# 健康检查 --- 排查 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 列表时、不确定某个命令是否存在时。

/help

会列出所有已注册的命令（内置 + 通过插件/Skill 注册的自定义命令）。

---

/clear --- 清除会话

解决什么问题 ：会话上下文过长，或者之前的讨论方向错误，需要"重置"但不想退出重启 Claude Code。 何时使用：开始讨论全新话题、上下文被错误方向污染、测试不同方案需要干净上下文。

/clear

注意事项 ：清除后无法恢复。如果想保留上下文但减少 token 消耗，用 /compact。项目的 CLAUDE.md 和 memory 不会被清除。

---

/compact --- 压缩上下文

解决什么问题 ：长时间编码会话导致上下文接近窗口上限，模型开始"遗忘"早期内容或拒绝响应。 何时使用：出现 "context window almost full" 提示、会话超过数百轮交互、完成阶段性工作准备进入下一阶段。

/compact

工作原理 ：将历史对话总结为摘要，释放大量 token 空间。通过 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 可调整自动触发阈值。

触发时机判断：

• 会话轮数 > 100 轮 → 建议主动压缩
• 出现 token 不足警告 → 必须压缩
• 开始新话题前 → 可选压缩

---

/cost --- 费用统计

解决什么问题 ：想知道当前会话用了多少 token、花了多少钱，是否在预算内。 何时使用：大规模任务后检查费用、对比不同策略的 token 效率、项目预算管控。

/cost

输出内容：输入/输出 Token 数量、缓存命中率、估算费用（美元）、当前使用的模型。

典型使用：

• 每次大的代码生成后：/cost 确认没有异常消耗
• 日终检查：/cost 汇总当天各项目的 API 费用
• 策略对比：方案 A 用了 50K token vs 方案 B 用了 200K token → 反思 prompt 效率

---

/context --- 上下文窗口分析

解决什么问题 ：不知道当前上下文用了多少空间、哪些内容占比最大、还剩多少空间。 何时使用：评估是否需要压缩、优化 CLAUDE.md 内容量、排查上下文消耗过快的原因。

/context

输出包含：已用/总 Token 数、各部分占比（系统提示词/CLAUDE.md/对话/工具结果）、剩余空间。

---

/export --- 导出会话

解决什么问题 ：需要将当前会话存档、分享给他人、或导入其他工具分析。 何时使用：项目归档、知识分享、会话分析、备份重要讨论。

/export                         # 导出到默认位置
/export ~/sessions/             # 导出到指定目录

---

/resume --- 恢复会话

解决什么问题 ：从当前会话快速跳转到另一个历史会话，不必退出重启。 何时使用：在多个并行任务间切换、回到之前的讨论、查看历史会话。

/resume                         # 打开交互式选择器
/resume abc123                  # 恢复到指定会话

---

/model --- 切换模型

解决什么问题 ：不同阶段需要不同模型能力------设计阶段要深度思考（Opus），实现阶段要速度（Sonnet）。 何时使用：架构设计时切到 Opus，编码实现时切回 Sonnet。

/model                          # 查看当前模型
/model opus                     # 切换：架构设计 / 深度分析
/model sonnet                   # 切换：日常编码（默认）
/model haiku                    # 切换：快速批量处理

典型工作流：

/model opus     → "设计支付系统的微服务拆分方案"  (深度分析)
/model sonnet   → "按照方案实现支付模块的代码"    (快速编码)

---

/fast --- 快速模式

解决什么问题 ：当前任务比较简单，不需要深度思考，想要更快的响应速度。 何时使用：简单格式化、文本翻译、快速问答。

/fast                           # 启用快速模式
/fast off                       # 关闭

---

/name --- 命名会话

解决什么问题 ：会话进行中发现之前的命名不合适，或者开始时忘了命名。 何时使用 ：会话中随时重命名，确保后续 /resume 能一眼识别。

/name 修复用户模块的死锁问题

---

3.2 代码审查与质量命令

/review --- PR 审查

解决什么问题 ：代码写完了，提交 PR 前需要全面审查------正确性、安全性、性能、可维护性。 何时使用：提交 PR 前、代码合并前、Code Review 环节。

/review

审查维度：

• 代码正确性：逻辑错误、边界条件
• 安全性：注入风险、权限问题
• 性能：N+1 查询、不必要的循环
• 可维护性：命名规范、代码重复、耦合度

最佳实践 ：/review → /fix（修复问题） → /verify（验证修复）

---

/security-review --- 安全审查

解决什么问题 ：代码可能包含安全漏洞，需要专门的安全视角审查------普通审查可能遗漏安全问题。 何时使用：涉及认证/授权的代码、处理用户输入的代码、支付/敏感数据相关代码。

/security-review

审查重点：OWASP Top 10、认证绕过、注入攻击、敏感数据泄露、不安全反序列化、加密正确性。

---

/code-review --- 代码质量审查

解决什么问题 ：代码能工作但质量不高------有重复、命名不好、逻辑复杂、效率低。 何时使用：重构前评估、代码规范化、技术债务清理。

/code-review
/code-review --effort high      # 更深入的审查

与 /review 的区别 ：/review 面向 PR 全面审查（含功能正确性），/code-review 侧重代码质量改进。

---

/simplify --- 代码简化

解决什么问题 ：代码有明显冗余------重复逻辑、过长表达式、无用变量，需要自动简化。 何时使用：代码 review 后发现冗余、重构时提取公共逻辑、减少技术债务。

/simplify

简化内容：提取重复代码、简化条件表达式、移除无用导入/变量、合并可合并的类/方法。

---

/verify --- 验证代码更改

解决什么问题 ：代码写完了但不能确定是否真的按预期工作------需要实际运行验证。 何时使用：代码修改后、Bug 修复后、新功能开发完成后。

/verify

验证流程：启动应用 → 执行相关功能 → 检查输出/日志 → 截图（Web） → 报告结果。

---

/fix --- 修复问题

解决什么问题 ：代码有问题（编译报错、运行时异常、逻辑错误），需要自动诊断并修复。 何时使用：编译/测试失败后、发现 Bug 后、代码审查发现的问题需要修复。

/fix                            # 修复最近讨论的问题
/fix 登录接口返回500错误         # 修复特定问题

---

3.3 开发流程命令

/run --- 启动应用

解决什么问题 ：需要运行项目看效果，但不想手动敲启动命令、配置环境。 何时使用：开发过程中频繁启动应用验证、运行测试、触发特定功能。

/run                            # 按项目类型自动启动
/run "启动后端并测试登录API"     # 带指令启动

Claude 会自动识别项目类型（Spring Boot / Node.js / Python 等）并使用正确的启动命令。

---

/loop --- 定时循环

解决什么问题 ：需要定期执行某个任务------监控部署状态、检查 CI/CD、轮询服务健康。 何时使用：部署后监控、CI/CD 状态轮询、定期健康检查、长时间运行任务的进度追踪。

/loop 5m /run "检查健康状态"     # 每5分钟
/loop 30m "检查部署状态"          # 每30分钟
/loop 1h /review                  # 每小时

时间格式 ：Xs（秒）、Xm（分钟）、Xh（小时）。

---

/batch --- 批量处理

解决什么问题 ：需要大规模修改（比如统一 50 个 Controller 的异常处理），手动逐个改太慢。 何时使用：全局代码规范统一、框架迁移、批量重构。

/batch "将所有 Controller 层的异常处理统一为 GlobalExceptionHandler"
/batch "将所有 DAO 接口迁移到 JPA Repository"

工作流程：分析代码库 → 拆分任务（5-30个） → 并行执行（每个在独立 worktree） → 汇总结果。

---

/workflows --- 工作流管理

解决什么问题 ：运行了 Workflow 后需要查看进度、或需要停止某个失控的工作流。 何时使用：监控长时间运行的 Workflow、调试 Workflow 脚本。

/workflows                       # 查看工作流状态
/workflows stop <id>             # 停止指定工作流

---

/tasks --- 任务管理

解决什么问题 ：复杂任务需要分解为多个子任务并追踪进度------哪个完成了、哪个还在进行、哪个被阻塞。 何时使用：多步骤任务、Team 协作、Sprint 规划。

/tasks                           # 查看所有任务
/tasks add "修复登录Bug"          # 添加
/tasks done 3                    # 完成编号为3的任务
/tasks priority 1 high           # 设置优先级

---

3.4 配置命令

/config --- 快速配置

解决什么问题 ：不想手动编辑 settings.json，需要交互式修改基础设置。 何时使用：首次使用 Claude Code 时配置偏好、快速切换主题或模型。

/config                          # 交互式配置
/config theme                    # 配置主题
/config model                    # 配置默认模型

/settings --- 打开配置文件

解决什么问题 ：需要直接编辑某个层级的 settings.json，但不确定文件在哪。 何时使用：手动修改高级配置项、排查配置问题。

/settings                        # 打开项目级
/settings user                   # 打开用户级
/settings local                  # 打开本地覆盖

/permissions --- 权限管理

解决什么问题 ：需要允许/禁止某些工具操作------比如允许 npm 但禁止 rm。 何时使用：初次配置项目安全策略、排查权限拒绝问题。

/permissions                           # 打开权限管理
/permissions allow "Bash(git *)"       # 添加允许
/permissions deny "Bash(rm *)"         # 添加拒绝

/hooks --- Hooks 管理

解决什么问题 ：需要在特定事件（工具调用前后）执行自定义脚本。 何时使用：配置自动化监控、安全拦截、通知。

/hooks                                         # 查看当前 hooks
/hooks add postToolUse "python3 monitor.py"    # 添加 hook

/statusline --- 状态栏

解决什么问题 ：想在终端看到当前模型、token 消耗、git 分支等实时信息。 何时使用：配置工作界面、提高信息可见性。

/statusline                      # 交互式配置
/statusline enable               # 启用
/statusline disable              # 禁用

可显示信息：当前模型和努力级别、Token 消耗、Git 分支/状态、当前时间。

/theme --- 切换主题

/theme light                     # 浅色
/theme dark                      # 深色

/terminal-theme --- 终端主题

/terminal-theme                  # 切换终端配色

/ide --- IDE 集成管理

解决什么问题 ：需要在 Claude Code 和 IDE 之间切换------在 IDE 中查看 Claude 建议的文件，或反之。 何时使用：开发过程中需要 IDE 和 Claude Code 协同工作。

/ide connect                     # 连接 IDE
/ide disconnect                  # 断开
/ide status                      # 查看状态

---

3.5 Agent 与插件命令

/agents --- Agent 管理

解决什么问题 ：需要查看或控制后台运行的 Agent------分配新任务、停止卡住的 Agent。 何时使用：多 Agent 并行工作时、需要监控 Agent 状态。

/agents                          # 查看运行中的 Agent
/agents spawn "审查代码"          # 创建新 Agent
/agents stop <id>                # 停止 Agent

/memory --- 记忆管理

解决什么问题 ：有些信息需要跨会话记住------项目约定、用户偏好、已确认的决策。 何时使用：保存重要的项目上下文、查看已有记忆、删除过时记忆。

/memory                          # 查看所有记忆
/memory add "这个项目使用 Java 17" # 添加
/memory delete <id>              # 删除

---

3.6 诊断与反馈命令

/init --- 初始化项目

解决什么问题 ：新项目或刚引入 Claude Code 的项目，需要自动生成 CLAUDE.md 描述代码库。 何时使用：首次在项目中使用 Claude Code、项目结构变化后更新文档。

/init

生成内容：项目概览和技术栈、构建运行命令、架构说明、关键目录文件。

/doctor --- 健康诊断

解决什么问题 ：Claude Code 表现异常------连不上、配置不生效、版本太旧。 何时使用：遇到不明错误时作为第一步排查。

/doctor

诊断内容：CLI 版本和更新状态、认证状态、配置文件有效性、网络连接。

/upgrade --- 更新 CLI

/upgrade                         # 检查并安装
/upgrade check                   # 仅检查

/bug --- 问题反馈

解决什么问题 ：发现 Claude Code 本身的 Bug，需要向 Anthropic 报告。 何时使用：遇到非预期行为、功能缺失、崩溃。

/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：

{
  "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. .claude/settings.local.json  (本地)   ← 不提交 git，个人偏好
2. .claude/settings.json       (项目)    ← 提交 git，团队共享
3. ~/.claude/settings.json     (用户)    ← 全局默认

合并规则：

• 高优先级覆盖低优先级的同名字段
• permissions.allow 数组是追加合并
• env 对象是浅合并（同名 key 覆盖）

实际案例：

// 用户级 → 所有项目的默认值
{ "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

加载控制：

claude --setting-sources user,project     # 忽略本地
claude --settings ./ci-settings.json      # 加载额外配置

---

5.2 settings.json 完整配置参考

{
  // ═══ 环境变量 ═══
  "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	该项目会话	同上（备选位置）	✅

完整模板：

# 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/ 下每一个文件和子目录的详细说明，基于实际环境分析。

5.4.1 根目录文件

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 损坏时从此恢复。

cp ~/.claude/settings.json.bak.json ~/.claude/settings.json

.mcp.json --- 用户级 MCP 配置

作用 ：存储用户级 MCP 服务器定义，所有项目共享。 何时修改：添加全局可用的数据库/API 工具时。

{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"] } } }

history.jsonl --- 命令历史

作用 ：JSONL 格式记录所有会话的命令历史，支持 ↑/↓ 浏览。 ⚠️ 隐私注意：包含你在 Claude Code 中输入的所有内容。

{"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 认证，避免重复弹窗。

---

5.4.2 核心功能目录

agents/ --- 自定义 Agent 定义

作用 ：每个 .md 文件定义一个专门的 Agent 角色。 何时添加：需要特定领域的审查专家（安全/性能/Android 等）时。

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。

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/（复盘报告）。

---

5.4.3 会话与状态目录

sessions/ --- 会话索引

作用：以 PID 命名的 JSON 文件，记录活跃会话的元信息。

{ "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。

---

5.4.4 缓存与历史目录

file-history/ --- 文件编辑历史

作用：按会话 ID 组织，追踪每个会话的文件修改记录，支持撤销。

paste-cache/ --- 粘贴内容缓存

作用 ：Ctrl+P 快速粘贴的文本缓存，以内容哈希命名。

shell-snapshots/ --- Shell 环境快照

作用 ：snapshot-{shell}-{timestamp}-{random}.sh 格式，用于会话恢复时精确还原环境。

backups/ --- 配置自动备份

作用 ：.claude.json.backup.{timestamp} 格式，每次更新配置时自动创建（约 70KB 每个）。

ls -la ~/.claude/backups/
cp ~/.claude/backups/.claude.json.backup.1781164919093 ~/.claude/settings.json  # 恢复

---

5.4.5 系统内部目录

ide/ --- IDE 集成锁文件

作用 ：以 IDE 进程 PID 命名的 .lock 文件，管理连接状态，防止重复连接。

telemetry/ --- 遥测失败事件队列

作用：网络不稳定时暂存发送失败的遥测数据，重启后自动重试。

.git/ --- 配置版本控制

作用 ：~/.claude/ 是 Git 仓库，追踪配置文件变更。

cd ~/.claude && git log --oneline -20    # 查看配置变更历史

gomoku/ --- 五子棋存档

作用：内置五子棋小游戏的存档（趣味功能）。

---

5.4.6 完整目录树

~/.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	可安全清理

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 服务器（本地进程）

{
  "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 服务器（远程服务）

{
  "mcpServers": {
    "sentry": {
      "transport": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": { "Authorization": "Bearer ${SENTRY_TOKEN}" }
    }
  }
}

6.3 安全最佳实践

1. 永远不硬编码密钥 ：使用 ${ENV_VAR} 引用
2. 项目级 MCP 需批准 ：.mcp.json 首次加载时提示确认
3. 最小权限：filesystem 只暴露必要目录
4. 定期审计 ：claude mcp list

---

七、Hooks 系统

7.1 生命周期事件

解决什么问题 ：需要在 Claude 执行操作的前后自动触发自定义逻辑------监控、安全拦截、通知、自动保存。 何时使用：记录所有操作日志、拦截危险命令、代码修改后自动格式化、完成后发通知。

用户输入命令
    ├── 🔔 preCommand     ← 命令执行前
    ├── Claude 处理...
    │   ├── 🔔 preToolUse    ← 工具调用前
    │   ├── 工具执行...
    │   └── 🔔 postToolUse   ← 工具调用后
    └── 🔔 postCommand    ← 命令执行后

7.2 Hooks 配置实战

场景一：工具调用监控

{
  "hooks": {
    "postToolUse": "python3 ~/.claude/scripts/monitor.py --tool '$tool_name' --exit '$exit_code'"
  }
}

场景二：危险操作拦截

{
  "hooks": {
    "preToolUse": "if echo '$tool_input' | grep -q 'rm -rf'; then echo '⚠️ 危险操作已拦截'; exit 1; fi"
  }
}

场景三：Git 自动暂存

{
  "hooks": {
    "postCommand": "git status --porcelain | grep -q '^M' && git add -A"
  }
}

场景四：桌面通知

{
  "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 精细权限配置

安全开发环境

{
  "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 的组合，而不是单独管理每个组件。 何时使用：创建可复用的工作流包、在团队间共享自定义工具、发布到市场。

my-plugin/
├── plugin.json                  # 必需：插件元数据
├── SKILL.md                     # 必需：Skill 主文档
├── agents/                      # 可选：自定义 Agent
├── hooks/                       # 可选：Hooks 配置
├── mcp/                         # 可选：MCP 配置
└── .claude/settings.local.json  # 插件级权限

9.2 从创建到发布

# 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 角色来处理特定领域任务，每个角色有自己的工具权限和能力边界。 何时使用：创建安全审查专家、性能分析师、代码规范检查员等专门角色。

---
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 使用方式

claude --agent security-auditor
claude agents --agent my-agent --model sonnet

---

十一、Teams 系统

11.1 Teams 架构

解决什么问题 ：单个 Agent 能力有限，复杂任务需要多个专业 Agent 协同------如代码审查需要安全+性能+规范三个视角同时审查。 何时使用：全面的代码审查、多模块并行开发、需要多专家交叉验证的复杂任务。

                 ┌─────────────┐
                 │  Team Lead  │  ← 协调，分配任务，汇总
                 └──────┬──────┘
         ┌──────────────┼──────────────┐
         ▼              ▼              ▼
  ┌───────────┐  ┌───────────┐  ┌───────────┐
  │ Code      │  │ Security  │  │ Test      │
  │ Reviewer  │  │ Auditor   │  │ Writer    │
  └───────────┘  └───────────┘  └───────────┘

⚠️ 实验性功能，需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。

11.2 使用流程

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 脚本结构

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

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) --- 并行屏障

// 所有任务并发，全部完成后返回
const results = await parallel([
  () => agent('任务A'),
  () => agent('任务B'),
  () => agent('任务C')
])

使用判断 ：需要收集所有结果后再决策时用 parallel，否则用 pipeline。

pipeline(items, stage1, stage2, ...) --- 流水线

// 每个 item 独立流经所有阶段，阶段间不等待
const results = await pipeline(
  items,
  item => stage1(item),
  result => stage2(result)
)

phase(title) / log(message) --- 进度显示

phase('审查')          // 开始新阶段
log('发现 5 个问题')    // 输出进度

---

十三、自进化系统

13.1 五维闭环

解决什么问题 ：Claude Code 在运行中会反复出现某些错误模式，需要自动检测、分析、修复这些模式，让系统越来越稳定。 何时自动运行：通过 Cron 定时触发，或手动通过命令触发。

执行 → 监控 → 复盘 → 改写 → 沉淀 → (反馈到下次执行)

环节	组件	功能
① 执行	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 使用方式

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 日常开发

claude -c                                       # 继续昨天
# 在会话中：讨论 → 生成代码 → /run → /fix → /review → commit

16.2 PR 审查

# 快速审查
/review → /code-review → /simplify

# 深度审查（重要 PR）
claude ultrareview main --timeout 60

16.3 大规模重构

claude -w refactor --model opus --effort max    # 隔离环境
/batch "将认证模块从 Session 迁移到 JWT"         # 批量执行
/review → /verify                                # 审查验证

16.4 CI/CD 集成

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 定时监控

/loop 10m /run "检查 API 健康"
/loop 1h "检查过去1小时的应用日志，报告新增错误"

16.6 MCP 集成

claude mcp add db -e PG_HOST=prod -- npx @modelcontextprotocol/server-postgres
# 在会话中自然语言："查询今天 crash_log 表的错误分布"
claude mcp remove db                             # 用完移除

---

信息来源 : Claude Code CLI --help 输出、Workflow 系统文档、实际环境配置分析、使用经验总结。 官方文档 : code.claude.com/docs API 文档 : docs.anthropic.com