Claude Code 完整使用说明目录什么是 Claude Code安装方法基本用法CLAUDE.md 文件与记忆系统斜杠命令与技能SkillsHooks钩子配置MCP 服务器Git 集成与工作流IDE 集成设置与配置权限与安全高级功能最佳实践与技巧1. 什么是 Claude CodeClaude Code 是 Anthropic 推出的 AI 编程工具。它能读取你的代码库、编辑文件、运行命令并通过自然语言与你的开发工具集成。支持终端、IDE、桌面应用和浏览器使用。核心工作流程当你给 Claude 一个任务时它会循环执行三个阶段收集上下文→采取行动→验证结果直到任务完成。你随时可以中断并调整方向。内置工具类别类别Claude 能做什么文件操作读取、编辑、创建、重命名、重组文件搜索按模式查找文件、使用正则搜索内容执行运行 shell 命令、启动服务器、运行测试、使用 git网络搜索网页、获取文档、查找错误信息代码智能类型错误、警告、跳转到定义、查找引用关键能力理解整个代码库跨多个文件支持 git 操作提交、分支、PR管道化和脚本化Unix 哲学每次文件编辑都有检查点可安全撤销可通过 skills、hooks、MCP 服务器和子代理扩展支持终端、VS Code、JetBrains、桌面应用、Web 和 CI/CD2. 安装方法原生安装推荐macOS / Linux / WSLcurl-fsSLhttps://claude.ai/install.sh|bashWindows PowerShellirmhttps://claude.ai/install.ps1|iexWindows CMDcurl -fsSL https://claude.ai/install.cmd -o install.cmd install.cmd del install.cmd包管理器安装HomebrewmacOS/Linuxbrewinstall--caskclaude-code注意Homebrew 安装不会自动更新需定期运行brew upgrade claude-codeWinGetWindowswinget install Anthropic.ClaudeCode注意WinGet 安装不会自动更新需定期运行winget upgrade Anthropic.ClaudeCodeNPM已废弃npminstall-ganthropic-ai/claude-code系统要求Node.js 18Windows 需要 Git for Windows原生安装支持自动更新开始使用cdyour-project claude3. 基本用法3.1 启动会话命令说明claude启动交互式会话claude query带初始提示启动claude -p query非交互式打印模式执行后退出cat file | claude -p query处理管道输入内容claude -c继续最近的对话claude -r session通过 ID 或名称恢复会话claude --permission-mode plan以计划模式启动3.2 常用参数参数用途--model name设置模型sonnet、opus 或完整名称--permission-mode mode权限模式default、acceptEdits、plan、auto、dontAsk、bypassPermissions--allowedTools预批准特定工具--disallowedTools禁用特定工具--add-dir path添加额外工作目录--worktree name在隔离的 git worktree 中启动--bare最小模式跳过自动发现--append-system-prompt追加系统提示--output-format format输出格式text、json、stream-json--max-turns n限制代理轮次--max-budget-usd amount限制花费--name name设置会话显示名称--debug启用调试日志3.3 会话管理操作说明claude -c或claude --continue恢复当前目录最近的对话claude --resume打开交互式会话选择器claude --from-pr 123恢复关联 PR 的会话/rename name重命名当前会话/resume从会话内部切换会话/clear重置上下文切换任务时使用/compact压缩对话以释放上下文空间/compact focus on X带焦点压缩3.4 键盘快捷键操作快捷键中断 ClaudeEsc撤销到上一状态Esc连按两次切换权限模式ShiftTab查看扩展思考CtrlO切换深度思考AltT(Mac:OptionT)4. CLAUDE.md 文件与记忆系统4.1 两套互补的记忆系统CLAUDE.md自动记忆谁来写你用户Claude内容指令和规则学习和模式作用范围项目级、用户级或组织级每个工作树加载时机每次会话自动加载每次会话前 200 行或 25KB4.2 CLAUDE.md 文件位置范围位置用途托管策略C:\Program Files\ClaudeCode\CLAUDE.md(Windows)组织级 IT 管理策略项目级./CLAUDE.md或./.claude/CLAUDE.md团队共享的项目指令用户级~/.claude/CLAUDE.md所有项目的个人偏好本地级./CLAUDE.local.md个人项目特定建议加入 .gitignore4.3 编写有效的 CLAUDE.md原则控制在 200 行以内使用 markdown 标题和列表具体明确“使用 2 空格缩进”而非正确格式化代码建议包含构建/测试命令代码规范架构决策命名约定常见注意事项建议排除Claude 能从代码中推断的内容标准约定冗长的解释其他功能使用path/to/file语法导入其他文件运行/init自动生成初始 CLAUDE.md支持 AGENTS.md在 CLAUDE.md 中导入AGENTS.md4.4.claude/rules/目录大型项目可将指令组织为模块化规则文件.claude/rules/ code-style.md testing.md security.md规则可通过 YAML 前置元数据限定路径范围---paths:-src/api/**/*.ts---用户级规则放在~/.claude/rules/。规则支持符号链接跨项目共享。4.5 自动记忆存储在~/.claude/projects/项目/memory/MEMORY.md是索引会话启动时加载前 200 行或 25KB主题文件按需读取使用/memory命令查看和管理纯 markdown 格式可直接编辑或删除设置中可通过autoMemoryEnabled: false关闭4.6/memory命令列出所有已加载的 CLAUDE.md 文件、规则和自动记忆。可在其中切换自动记忆并打开记忆文件进行编辑。5. 斜杠命令与技能Skills5.1 内置命令命令用途/help显示帮助/compact压缩上下文/clear清除上下文/init生成 CLAUDE.md/memory查看/编辑记忆文件/permissions管理权限规则/config打开设置/model切换模型/resume恢复会话/rename重命名会话/status显示状态信息/mcp管理 MCP 服务器/hooks浏览已配置的钩子/agents列出/创建子代理/doctor诊断问题5.2 内置技能技能用途/batch跨 5-30 个 worktree 并行编排大规模变更/claude-api加载 Claude API 参考资料/debug启用调试日志/loop定期重复执行提示/simplify审查代码质量并修复问题5.3 自定义技能技能通过SKILL.md文件扩展 Claude 的能力。位置决定作用范围位置范围~/.claude/skills/name/SKILL.md个人所有项目.claude/skills/name/SKILL.md项目特定plugin/skills/name/SKILL.md插件作用范围前置元数据字段---name:my-skilldescription:技能描述及使用场景disable-model-invocation:true# 仅用户可调用Claude 不能自动调用user-invocable:false# 仅 Claude 可调用不在 / 菜单显示allowed-tools:Bash(git*)# 技能激活时预批准的工具context:fork# 在分叉的子代理中运行agent:Explore# 用于分叉执行的代理类型model:opus# 模型覆盖paths:# 路径范围激活-src/**/*.ts---字符串替换变量$ARGUMENTS— 所有传入参数$0,$1— 按位置的单个参数${CLAUDE_SESSION_ID}— 当前会话 ID${CLAUDE_SKILL_DIR}— 技能目录路径动态上下文注入使用反引号命令语法在发送给 Claude 前执行 shell 命令---name:pr-summary---## PR diff!gh pr diff## PR comments!gh pr view--comments旧版.claude/commands/*.md文件仍可使用。同名时技能优先于命令。6. Hooks钩子配置Hooks 是在特定生命周期节点自动执行的 shell 命令、HTTP 端点、LLM 提示或代理。6.1 钩子事件事件触发时机SessionStart会话开始或恢复UserPromptSubmit用户提交提示在 Claude 处理之前PreToolUse工具调用执行前可阻止执行PermissionRequest权限对话框出现时PermissionDenied自动模式分类器拒绝工具调用时PostToolUse工具调用成功后PostToolUseFailure工具调用失败后NotificationClaude Code 发送通知SubagentStart/SubagentStop子代理启动/完成TaskCreated/TaskCompleted任务生命周期StopClaude 完成响应InstructionsLoadedCLAUDE.md 或规则文件加载ConfigChange配置文件变更FileChanged磁盘上受监视文件变更WorktreeCreate/WorktreeRemoveWorktree 生命周期PreCompact/PostCompact上下文压缩SessionEnd会话终止6.2 钩子类型Command(type: command)运行 shell 命令通过 stdin 接收 JSONHTTP(type: http)将 JSON POST 到端点Prompt(type: prompt)向 Claude 模型发送提示Agent(type: agent)启动带工具的子代理6.3 配置位置钩子放在设置文件中~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、托管策略或插件hooks/hooks.json。6.4 示例阻止危险命令{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,if:Bash(rm *),command:.claude/hooks/block-rm.sh}]}]}}6.5 退出码行为0成功解析 stdout 中的 JSON2阻塞错误stderr 反馈给 Claude其他非阻塞错误继续执行6.6PreToolUse钩子的关键字段返回hookSpecificOutput设置permissionDecision为allow、deny、ask或defer。7. MCP 服务器MCPModel Context Protocol是连接 AI 工具与外部数据源的开放标准。7.1 添加 MCP 服务器# HTTP 传输claude mcpadd--transporthttp github https://api.githubcopilot.com/mcp/# 从 JSON 配置加载claude --mcp-config ./mcp.json# 严格模式仅使用 --mcp-config 中的服务器claude --strict-mcp-config --mcp-config ./mcp.json7.2 配置作用范围范围说明用户级所有项目可用项目级通过.claude/settings.json共享本地级个人使用在.claude/settings.local.json托管级组织强制7.3 MCP 工具命名MCP 工具遵循mcp__server__tool格式。权限规则支持正则mcp__memory__.*或mcp__.*__write.*。7.4 工具搜索MCP 工具定义默认延迟加载仅在 Claude 使用特定工具时才加载完整定义。运行/mcp查看各服务器的成本。7.5 MCP 资源使用server:resource语法在提示中引用 MCP 资源。8. Git 集成与工作流8.1 提交与 PR直接告诉 Claude“提交我的更改附上描述性信息”“创建一个 PR”Claude 会自动暂存更改、编写提交信息、创建分支、打开 PR。8.2 提交归属默认情况下提交包含Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.6 noreplyanthropic.com可通过设置中的attribution自定义。8.3 Git Worktree 并行会话claude--worktreefeature-auth# 创建 .claude/worktrees/feature-auth/claude--worktreebugfix-123# 另一个隔离 worktreeclaude--worktree# 自动生成名称要点Worktree 从origin/HEAD分支分支名为worktree-name无变更时自动清理有变更时提示保留/删除建议将.claude/worktrees/加入.gitignore使用.worktreeinclude复制被 gitignore 的文件如.env到 worktree8.4 GitHub / GitLab 集成支持 GitHub Actions 自动化 PR 审查和 Issue 分类支持 GitLab CI/CD将 Issue 转为 MR9. IDE 集成9.1 VS Code 扩展安装在扩展市场搜索 “Claude Code”要求 VS Code 1.98.0。功能编辑器工具栏和活动栏中的图标并排差异查看filename或file#L5-10引用文件选中文本自动共享给 Claude权限模式切换多会话标签/窗口会话历史浏览器检查点回退代码、分叉对话或两者Chrome 浏览器集成browser插件管理 GUI远程会话恢复快捷键操作MacWindows/Linux切换输入焦点CmdEscCtrlEsc新建标签CmdShiftEscCtrlShiftEsc插入 引用OptionKAltK新建对话CmdNCtrlN内置 IDE MCP 服务器提供mcp__ide__getDiagnostics语言服务器诊断和mcp__ide__executeCodeJupyter notebook 执行。9.2 JetBrains 插件支持的 IDEIntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLand。安装从 JetBrains Marketplace 安装并重启。功能CmdEsc/CtrlEsc快速启动IDE 差异查看器中查看差异选择/上下文共享CmdOptionK/AltCtrlK文件引用快捷键诊断共享Lint、语法错误使用从 IDE 终端运行claude或从外部终端使用/ide连接。10. 设置与配置10.1 设置文件位置与范围范围位置团队共享托管服务器管理/MDM/注册表是IT 部署用户~/.claude/settings.json否项目.claude/settings.json是提交到 git本地.claude/settings.local.json否gitignore10.2 设置优先级从高到低托管设置不可被覆盖命令行参数本地项目设置 (.claude/settings.local.json)共享项目设置 (.claude/settings.json)用户设置 (~/.claude/settings.json)数组设置如permissions.allow跨范围合并并去重。10.3 关键设置示例{permissions:{allow:[Bash(npm run *),Bash(git commit *)],deny:[Bash(git push *)],defaultMode:acceptEdits},env:{MY_VAR:value},attribution:{commit:Generated with AI,pr:},autoMemoryEnabled:true,claudeMdExcludes:[**/other-team/CLAUDE.md],sandbox:{enabled:true,filesystem:{allowWrite:[/tmp/build]},network:{allowedDomains:[github.com]}}}10.4 环境变量常用环境变量ANTHROPIC_API_KEY、ANTHROPIC_MODEL、CLAUDE_CODE_EFFORT_LEVEL、MAX_THINKING_TOKENS、CLAUDE_CODE_DISABLE_AUTO_MEMORY。10.5 验证当前设置在 Claude Code 中运行/status查看哪些设置源处于活动状态。11. 权限与安全11.1 权限模式ShiftTab循环切换模式无需询问即可执行default仅读取操作acceptEdits读取、文件编辑、常用文件系统命令plan仅读取计划模式——不修改任何内容auto所有操作带后台安全分类器检查dontAsk仅预批准的工具bypassPermissions所有操作受保护路径除外11.2 受保护路径永远不自动批准目录.git、.vscode、.idea、.husky、.claudecommands/agents/skills 除外文件.gitconfig、.gitmodules、.bashrc、.zshrc、.mcp.json、.claude.json11.3 权限规则语法Tool # 匹配所有使用 Tool(specifier) # 匹配特定使用 Bash(npm run *) # Bash 的 glob 模式 Read(/path/**) # 文件的 gitignore 风格模式 WebFetch(domain:x.com) # Web 的域名匹配 Agent(Explore) # 子代理访问控制 Skill(deploy *) # 技能访问控制 mcp__server__tool # MCP 工具匹配11.4 规则评估顺序deny ask allow首个匹配生效11.5 自动模式分类器独立模型在执行前审查操作会阻止下载/执行代码、外部发送数据、生产部署、批量删除、强制推送到主分支会允许本地文件操作、声明的依赖安装、只读 HTTP、推送到当前分支连续 3 次或累计 20 次阻止后回退到手动确认需要 Team/Enterprise/API 计划和 Sonnet 4.6 或 Opus 4.611.6 沙箱Bash 命令的 OS 级文件系统和网络隔离。与权限互补权限控制 Claude 使用哪些工具沙箱限制 Bash 子进程的访问范围12. 高级功能12.1 子代理Subagents拥有独立上下文窗口、系统提示和工具访问的专用 AI 助手。内置类型类型说明Explore仅读取工具优化用于代码库探索Plan仅读取工具用于规划和分析general-purpose完整工具访问创建自定义子代理在.claude/agents/name.md创建文件--- name: security-reviewer description: 审查代码安全漏洞 tools: Read, Grep, Glob, Bash model: opus permissionMode: plan --- 你是一名资深安全工程师。审查代码中的安全漏洞。前置元数据字段name、description、tools、model、effort、permissionMode、isolation设为worktree进行隔离执行、skills预加载技能、allowed-tools。12.2 扩展思考默认启用Opus 4.6 和 Sonnet 4.6 使用自适应推理使用/effort控制low、medium、high、max或设置CLAUDE_CODE_EFFORT_LEVEL在提示中加入 “ultrathink” 一次性使用高努力度AltT切换CtrlO查看思考过程12.3 非交互模式打印模式claude-pquery# 文本输出claude-pquery--output-format json# JSON 输出claude-pquery--output-format stream-json# 流式 JSON 输出可集成到 CI 流水线、脚本、pre-commit 钩子中。12.4 Unix 管道tail-200app.log|claude-p检查异常gitdiffmain --name-only|claude-p审查这些文件caterror.log|claude-p解释这个错误output.txt12.5 远程控制从浏览器或 Claude 应用控制本地会话claude --remote-controlMy Project12.6 Web 会话claude--remote修复登录 Bug# 创建云端会话claude--teleport# 将 Web 会话恢复到本地12.7 插件Plugins将技能、钩子、子代理和 MCP 服务器打包为可安装的包。使用/plugin或claude pluginCLI 管理。12.8 Chrome 浏览器集成连接 Chrome 进行 Web 测试claude --chrome或在 VS Code 中使用browser。13. 最佳实践与技巧13.1 给 Claude 提供验证方式这是最高效的做法。始终提供测试、截图或预期输出。有验证手段时 Claude 的表现显著提升。13.2 先探索再规划最后编码使用计划模式ShiftTab或--permission-mode plan先研究再实施。审查计划通过对话完善然后让 Claude 实现。13.3 提示要具体引用具体文件、提及约束、指向示例模式。例如“编写 validateEmail 函数。测试用例‘userexample.com’ 返回 true‘invalid’ 返回 false。完成后运行测试。”13.4 配置你的环境编写有效的 CLAUDE.md200 行以内、具体、提交到 git配置权限自动模式、白名单或沙箱连接 MCP 服务器以访问外部工具设置钩子实现确定性自动化创建技能用于可复用工作流创建自定义子代理用于专门任务安装插件获取社区扩展13.5 积极管理上下文不相关的任务之间运行/clear使用子代理进行调查不膨胀主上下文需要时使用/compact focus on X使用/context跟踪上下文使用情况13.6 及时纠正方向Esc中断 Claude 的执行连按两次Esc恢复到上一状态两次纠正失败后/clear并用更好的提示重新开始13.7 避免的常见失败模式模式解决方法大杂烩会话混合不相关任务使用/clear分隔过度纠正上下文被失败污染/clear 更好的提示过度指定的 CLAUDE.md重要规则淹没果断精简信任但不验证看起来对但实际不行始终提供验证方式无限探索无范围调查填满上下文使用子代理13.8 并行会话扩展写作/审查模式一个 Claude 写另一个全新审查/batch用于 5-30 个 worktree 的大迁移claude -p用于逐文件操作代理团队用于协调并行工作参考资源资源链接官方文档https://code.claude.com/docs/en/overview.mdGitHub 仓库https://github.com/anthropics/claude-codeDiscord 社区https://anthropic.com/discord报告 Bug/bug命令或 https://github.com/anthropics/claude-code/issues本文档基于 Claude Code 最新版本编写内容可能随版本更新而变化。