Claude Code 完全操作指南：从入门到精通的智能编程实战手册

AGENTICCODINGTOOL·操作完全指南ClaudeCode完全操作指南从入门到精通的智能编程实战手册覆盖CLI命令·权限模式·Skills·Subagents·MCP·Git工作流2026年版目录01基础入门ClaudeCode是什么·启动与基本会话02命令与交互CLI命令·快捷键·斜杠命令03核心机制权限模式·PlanMode·上下文·CLAUDE.md04高级扩展自定义命令·Skills·Subagents·Hooks·MCP05工作流与实战Git工作流·IDE集成·模型选择·实战建议06附录命令速查·目录结构·输入前缀共41页·五大章节+附录01基础入门认识ClaudeCode·启动会话·基本交互PART01/0501·基础入门ClaudeCode是智能体式编码工具ClaudeCode是Anthropic官方推出的智能体式（agentic）编码工具，运行在终端中。它不是一个补全插件，而是一个能够自主完成多步任务的代理。能读搜索、打开、理解整个代码库能写创建、修改、重构文件能跑执行shell命令、跑测试、看报错能协作调用git/gh，提交代码、开PR终端原生界面·深色主题·语法高亮ClaudeCode·智能体式编码工具01·基础入门四大核心特点定义使用体验特点说明终端原生直接在你已有的工作流里，无需切换IDE，与git、npm、docker等命令行工具无缝协作无需手动喂上下文自主搜索代码库，不需要你逐个@文件，能自动理解项目结构和依赖关系权限可控每个写操作/命令执行都可以要求确认，四种权限模式灵活切换，安全与效率兼得可扩展通过Skills、Hooks、MCP、Subagents深度定制，连接外部工具和数据源，构建专属工作流关键洞察：终端原生+自主上下文+权限可控+高度可扩展，构成了ClaudeCode区别于其他AI编码工具的核心竞争力。01·基础入门四种可用形态覆盖全场景多端同步·桌面·移动·WebCLI（终端）本文重点，最强大最灵活的形态，适合深度开发者桌面应用（macOS/Windows）独立桌面客户端，适合不想在终端里工作的场景Web应用浏览器访问claude.ai进入code，可启动云端会话IDE扩展（VSCode、JetBrains）在编辑器内直接使用，改动以diff形式显示01·基础入门首次启动与认证方式cd/path/to/your/projectclaude在项目目录下运行claude命令即可启动。首次启动会引导你完成认证流程。三种认证方式Claude订阅账号Pro/Max订阅用户，走浏览器OAuth登录，额度包含在订阅内，最便捷的方式APIKeyAnthropicConsoleAPIKey，按token计费，适合需要精确控制成本的团队和个人企业接入AmazonBedrock或GoogleVertexAI，配置对应环境变量，数据不出企业网络边界提示：企业用户建议使用Bedrock或VertexAI接入，配合LLM网关统一管控，确保数据安全与合规。01·基础入门基本交互与常用启动方式REPL自然语言交互>这个项目的入口文件在哪？>帮我给UserService加上单元测试>修复CI里那个失败的lint检查>把auth模块从session改成JWT六种启动方式claude交互式会话（最常用）claude"prompt"带初始提示启动claude-p"prompt"非交互print模式claude-c继续最近一次会话claude-r从历史会话中恢复claude-p"..."一次性执行，脚本友好退出方式/exit或/quit·Ctrl+D·连按两次Ctrl+C02命令与交互CLI命令·快捷键·输入前缀·斜杠命令全解析PART02/0502·命令与交互CLI子命令一览命令作用claude启动交互式会话claude"prompt"带初始提示启动交互式会话claude-p"prompt"非交互（print）模式，执行完即退出claude-c/--continue继续当前目录最近的会话claude-r/--resume列出历史会话并恢复指定会话claudeupdate更新ClaudeCode到最新版本claudedoctor诊断安装与环境问题claudemcp管理MCP服务器claudeconfig命令行方式读写配置02·命令与交互常用启动参数详解参数说明--model<name>指定模型，如opus、sonnet、haiku或完整模型ID--permission-mode<mode>启动时的权限模式：default/acceptEdits/plan/bypassPermissions--allowedTools"..."预先允许的工具列表，如"Bash(git*)Read"--add-dir<path>会话启动时额外挂载目录，支持多仓库工作--output-formatjsonprint模式下输出结构化JSON，便于脚本解析--verbose输出完整日志，调试用--settings<file>指定额外的settings配置文件--mcp-config<file>指定MCP配置文件02·命令与交互脚本化与CI集成用法管道输入分析日志caterror.log|claude-p"分析这段日志里的根因"结构化输出存文件claude-p"列出所有TODO注释"--output-formatjson>todos.jsonCI中自动reviewdiffgitdifforigin/main|claude-p"review这个diff，只报真实bug"组合Unix管道claude-p"生成commitmessage"--output-formatjson|jq-r'.result'CI集成最佳实践使用-p非交互模式·配合--output-formatjson做结构化解析·用管道传递diff和日志·在CI中设置APIKey环境变量·建议使用plan或acceptEdits权限模式确保安全02·命令与交互环境变量配置变量说明ANTHROPIC_API_KEYAPIKey认证ANTHROPIC_MODEL默认模型设置ANTHROPIC_SMALL_FAST_MODEL后台小任务用的轻量模型CLAUDE_CODE_USE_BEDROCK=1走AWSBedrock企业接入CLAUDE_CODE_USE_VERTEX=1走GoogleVertexAI企业接入MAX_THINKING_TOKENS思考token预算上限BASH_DEFAULT_TIMEOUT_MSBash工具默认超时时间DISABLE_TELEMETRY=1关闭遥测数据收集HTTP_PROXY/HTTPS_PROXY代理服务器设置02·命令与交互通用快捷键速查输入与提交Enter提交消息Shift+Enter换行（不提交）Esc中断当前输出EscEsc回退到上条消息编辑Tab自动补全路径/命令会话控制Ctrl+C清空输入/连按两次退出Ctrl+D退出会话Ctrl+L清屏（保留上下文）Ctrl+R反向搜索历史输入↑/↓浏览输入历史面板与模式切换Ctrl+B打开后台任务面板Ctrl+O展开/折叠详细输出Shift+Tab循环切换权限模式（default→acceptEdits→plan）02·命令与交互输入前缀与Vim模式前缀作用示例/斜杠命令/clear@引用文件或目录，直接加入上下文@src/index.ts这里有什么问题!Bash模式：直接执行shell命令，输出进会话上下文!npmtest#快速写入记忆（CLAUDE.md）#本项目用pnpm而不是npm!前缀特别有用：当需要交互式命令（如gcloudauthlogin、vim）或你想让Claude看到某个命令的真实输出时，自己敲!command比让Claude猜要快得多。Vim模式输入/vim开启后支持Normal/Insert模式与常用vim动作（hjkl、wbe、dd、cw、0$、iao等），适合习惯Vim操作的开发者。02·命令与交互斜杠命令：会话与上下文在输入框敲/会弹出可用命令列表。以下是会话与上下文管理类命令：命令说明/clear清空对话上下文（重新开始，最常用）。任务切换时一定要用，避免残留上下文干扰判断/compact[说明]压缩上下文，保留摘要；可附带侧重点说明，如/compact重点保留API设计部分/context查看当前上下文占用明细，了解哪些文件和内容占用了token/rewind回退到之前的检查点，撤销Claude的改动，相当于时间机器/resume恢复历史会话，从会话列表中选择要继续的对话/export导出当前会话，复制或存为文件，便于分享和存档/exit//quit退出当前会话02·命令与交互斜杠命令：配置、权限与记忆配置与信息/config打开配置面板（主题、模型等）/model切换模型/status查看账号、模型、连接状态/cost查看本次会话token用量与成本/doctor诊断安装与环境权限与安全/permissions查看和编辑工具权限规则/allowed-tools管理允许的工具列表/security-review对当前分支改动做安全审查/login//logout切换/退出账号/upgrade升级订阅方案记忆与项目/init分析代码库并生成CLAUDE.md项目记忆文件，投入产出比最高的配置/memory编辑记忆文件（CLAUDE.md等），管理项目和个人记忆02·命令与交互斜杠命令：扩展能力与工作流扩展能力/agents管理subagents（子代理）/mcp管理MCP服务器与认证/hooks配置hooks钩子/plugin管理插件/skill-doctor诊断skills配置问题工作流命令/reviewReview一个PR/code-reviewReview当前diff，找bug/simplify只做质量清理，不找bug/loop[间隔]<cmd>按间隔重复执行某个命令/install-github-app安装GitHubApp，启用PR交互自定义斜杠命令除内置命令外，你可以在.claude/commands/目录下创建自定义斜杠命令，把重复的提示词固化成命令。详见第11节。03核心机制权限模式·PlanMode·上下文管理·CLAUDE.md·配置文件PART03/0503·核心机制四种权限模式平衡安全与效率用Shift+Tab循环切换，或启动时用--permission-mode指定。界面底部会显示当前模式。模式行为适用场景default每次编辑文件、执行命令都询问默认，最安全，生产环境推荐acceptEdits自动接受文件编辑，命令仍询问信任Claude的改动，想加速plan只读：不能编辑、不能执行有副作用的命令先规划再动手，复杂改动前bypassPermissions全部自动通过，无任何确认仅在隔离容器/一次性环境中使用安全警告：生产仓库绝对不要用bypassPermissions模式。03·核心机制权限规则语法与安全建议权限提示的三个选项1.Yes—本次允许2.Yes,anddon'taskagain—永久允许该类操作（写入settings.json）3.No,andtellClaudewhattododifferently—拒绝并给出替代指示规则语法要点工具名精确匹配，如Read、Edit工具名:*前缀匹配，如Bash(gitdiff:*)路径/**递归路径匹配deny>allowdeny优先级高于allow安全最佳实践·生产仓库不要用bypassPermissions模式·用deny明确挡住.env、密钥目录、CI配置文件·联网操作（WebFetch）限定域名白名单·需要放开限制时，在Docker/devcontainer里跑·第3项拒绝时顺便说明理由，Claude会调整方案而不是重试同样操作03·核心机制PlanMode：先想清楚再动手PlanMode是"先想清楚再动手"的机制，对多文件重构、新功能开发特别有价值。进入方式Shift+Tab循环到plan模式启动时claude--permission-modeplan直接说："先给我一个方案，不要改代码"在PlanMode里发生什么Claude只能读：搜索代码、读文件、理解架构不能编辑文件、不能执行有副作用的命令输出一份完整计划供你审阅值得用PlanMode·新功能开发（需要架构决策）·跨3个以上文件的改动·有多种合理实现路径·需求本身不清晰，需要先探索·重构现有系统不必用·改个typo·加一行日志·需求已经非常具体明确的单文件改动·简单的bug修复03·核心机制上下文管理策略上下文是有限资源，管理好它直接决定效果和成本。用/context查看占用，/cost查看token消耗。操作效果何时用/clear完全清空，从零开始换任务了，前面的内容都不需要/compact压缩成摘要，保留关键信息同一任务还没做完，但上下文太满/compact重点带侧重点的压缩你知道哪部分重要，如API设计主动喂上下文的技巧@src/auth/#加载整个目录@package.json@tsconfig.json#多文件!gitlog--oneline-20#把命令输出加进上下文!caterror.log#让Claude看到真实日志03·核心机制CLAUDE.md：投入产出比最高的配置CLAUDE.md是ClaudeCode每次启动时自动读取的项目说明文件。用/init自动生成初版，再手工润色。层级与优先级（从高到低）./CLAUDE.local.md当前项目，仅本人./CLAUDE.md当前项目，团队共享./subdir/CLAUDE.md子目录范围~/.claude/CLAUDE.md所有项目（个人全局）应该写什么·常用命令（开发、测试、构建）·架构要点和模块边界·代码规范和命名约定·注意事项和禁忌·从代码里看不出来的东西不该写什么·代码结构（Claude自己能读出来）·已经修过的bug记录（githistory里有）·一次性的对话内容03·核心机制配置文件settings.json详解文件位置与优先级（从高到低）企业策略（系统级）组织强制策略.claude/settings.local.json项目内个人设置.claude/settings.json项目团队共享设置~/.claude/settings.json个人全局设置常用配置项model默认模型theme主题：dark/lightpermissions权限规则env会话内注入环境变量hooks钩子配置cleanupPeriodDays会话历史保留天数statusLine自定义状态栏命令outputStyle输出风格三种修改方式：/config面板·直接编辑json·claudeconfigset04高级扩展自定义命令·Skills·Subagents·Hooks·MCP协议PART04/0504·高级扩展自定义斜杠命令：把重复提示词固化把重复的提示词固化成命令，是提效的第一步。项目级放在.claude/commands/，个人级放在~/.claude/commands/。最简示例#.claude/commands/test-file.md运行$ARGUMENTS对应的测试文件，如果失败就分析原因并修复，然后重新运行直到通过。使用方式/test-filesrc/auth/login.test.ts语法要点$ARGUMENTS全部参数（原样字符串）$1$2$3位置参数!command`命令替换：执行命令并把输出嵌入提示@path/to/file引用文件内容04·高级扩展Skills：比自定义命令更强的封装Skills是一个目录，可以包含说明文档、脚本、参考资料。Claude会在遇到匹配场景时自动加载，也可以用/name手动触发。目录结构.claude/skills/my-skill/├──SKILL.md

#必需：主说明文件├──references/│└──palette.md#参考资料├──scripts/│└──validate.py#可执行脚本└──assets/└──template.txt#模板、资源三个层级.claude/skills/项目级~/.claude/skills/个人全局插件提供调用时写plugin:skill诊断：/skill-doctor检查配置是否有问题渐进式加载设计（节省上下文）启动时只加载name+description（很少token）→判断相关时才读SKILL.md正文→需要细节时再读references/里的具体文件。所以SKILL.md应保持精简，细节放references/。04·高级扩展Subagents：独立上下文的子任务执行者Subagent是独立上下文的子任务执行者。主会话把任务派出去，只拿回结论，不承担搜索过程产生的大量文件内容。为什么用Subagents·上下文隔离：子代理读50个文件，主会话只收到一段结论·并行：多个独立任务同时跑·专门化：不同任务用不同模型、工具集、系统提示内置subagent类型Explore只读的大范围搜索，返回定位结论Plan架构设计，产出实施计划general-purpose通用多步任务claude-code-guide回答ClaudeCode相关问题statusline-setup配置状态栏使用建议适合派给子代理："找出所有用了废弃API的地方"、"调研这三个方案的优劣"、多维度codereview不适合：你已经知道文件和符号的单点查询（直接读更快）、需要频繁与主会话交互的任务04·高级扩展Hooks：确定性的自动化钩子Hooks是由ClaudeCode运行时执行的shell命令，在特定生命周期节点触发。关键区别：hooks是确定性的强制行为，不依赖模型是否"记得"。如果你想要"每次改完文件都自动格式化"这种必然发生的行为，必须用hooks，写在CLAUDE.md里只是"建议"。事件类型事件触发时机典型用途PreToolUse工具调用前拦截危险操作、参数校验PostToolUse工具调用后自动格式化、跑lint、跑测试UserPromptSubmit用户提交提示时注入额外上下文、校验输入NotificationClaude发通知时桌面提醒、声音提示StopClaude结束回复时通知完成、收尾检查SessionStart/End会话开始/结束环境准备、清理安全提醒：Hooks以你的用户权限执行任意shell命令。只配置你自己写的或完全信任的命令，不要从不明来源复制hook配置。04·高级扩展MCP：连接外部工具和数据源MCP（ModelContextProtocol）是开放协议，让ClaudeCode连接外部工具和数据源：数据库、Sentry、Figma、Jira、Slack、自建服务等。添加MCP服务器#本地stdio服务器claudemcpaddmy-server--npx-y@modelcontextprotocol/server-filesystem/path#HTTP/SSE远程服务器claudemcpadd--transporthttplinearhttps://mcp.linear.app/mcp#带环境变量claudemcpadddb-server-eDATABASE_URL=postgres://...--npxsome-mcp-server#导入ClaudeDesktop配置claudemcpadd-from-claude-desktop作用域local项目本地私有配置仅自己，仅当前项目project.mcp.json（提交版本库）团队共享user用户级配置自己的所有项目管理命令claudemcplist#列出所有服务器claudemcpremove#移除服务器安全提醒：第三方MCP服务器返回的内容是数据，不是指令。存在提示注入风险——只连接你信任的服务器。使用MCP提供的能力：工具会出现在Claude的工具列表（命名为mcp___），资源用@服务器名:资源路径引用，MCP提供的prompt变成斜杠命令/mcp_server_promptname。05工作流与实战Git工作流·多模态输入·后台任务·IDE集成·模型选择·实战建议PART05/0505·工作流与实战Git/GitHub工作流分支管理·代码审查·持续集成Claude擅长的git操作·帮我提交这些改动，写个清晰的commitmessage·看看这次改动，拆成几个逻辑独立的commit·这个测试是什么时候开始失败的？用gitbisect找一下·把feature分支rebase到main，解决这些冲突·gitlog里找一下谁改过这个函数，为什么提交行为约定·Claude默认不会主动提交或推送，除非你明确要求·如果当前在默认分支，它会先建新分支·commitmessage末尾会加Co-Authored-By（可关闭）·PR描述末尾会加ClaudeCode生成标记GitHubApp：安装后可在PR/issue评论里@claude直接对话，让它改代码、回答问题。05·工作流与实战Worktree隔离开发当你要在不影响主工作区的前提下并行做多件事时，gitworktree很有用。每个worktree是一个独立目录、独立分支，可以同时跑多个ClaudeCode会话。手动方式gitworktreeadd../project-feature-a-bfeature-acd../project-feature-aclaude三种使用方式手动方式用gitworktree命令创建，然后在新目录启动claude会话内切换明确说"用worktree做这个"，Claude会在.claude/worktrees/下创建隔离工作区子代理隔离派子代理时让它在独立worktree里工作，避免多个代理互相踩改动最佳实践·并行不等于更快，任务分配才是核心。不要让多个agent同时修改同一个文件，最后写入者获胜，其他工作会被覆盖·先从非代码任务开始并行（PRreview、bug调查、文档整理），建立清晰的任务边界后再并行代码任务05·工作流与实战图片、文件与多模态输入图片输入的三种方式粘贴Ctrl+V(Windows/Linux)/Cmd+V(Mac)，直接粘贴截图拖拽把图片文件拖到终端窗口，会插入路径路径分析这张图/path/to/screenshot.png典型用途·这是设计稿，帮我实现React组件[粘贴图片]·这个报错弹窗是什么原因[粘贴截图]·对比一下我的实现和设计稿的差异[粘贴两张图]·UI问题、报错弹窗特别高效其他文件类型支持PDF可以读PDF，支持指定页码范围（单次最多20页；超过10页的PDF必须指定范围）JupyterNotebook.ipynb文件会按cell读取（含输出），并支持按cell编辑文件引用@src/index.ts单文件·@src/components/整个目录·@package.json@tsconfig.json多文件05·工作流与实战后台任务与并行执行后台运行命令长时间运行的命令（devserver、watch模式测试）可以后台跑：>后台启动开发服务器Claude会用后台模式执行，进程跨轮次保持运行，结束时会通知。并行子代理>同时派三个子代理：一个检查auth模块的安全问题，一个检查API层的错误处理，一个检查前端组件的可访问性多个独立任务并行执行，各自独立上下文，最后汇总。定时/循环任务/loop5m/check-ci#每5分钟执行一次/loop/babysit-prs#让模型自己决定节奏也可以设置定时任务（cron语法，用户本地时区），适合"每天早上跑一次检查"这类需求。注意循环任务有存活时长上限。Ctrl+B打开后台任务面板查看状态和输出。后台任务是ClaudeCode处理长时间运行命令的关键机制，让你不必等待命令完成就可以继续其他工作。05·工作流与实战IDE集成与多端形态VSCode·JetBrains·桌面·WebVSCode/Cursor/Windsurf在IDE的集成终端里运行claude会自动安装扩展。特性：·改动以diff形式显示在编辑器里·自动共享当前选中内容和打开的文件作为上下文·诊断信息（linter/类型错误）自动传给Claude·Cmd+Esc/Ctrl+Esc快速唤起JetBrains系列IntelliJIDEA、PyCharm、WebStorm、GoLand、AndroidStudio等，从Marketplace安装ClaudeCode插件。装完需要重启IDE。桌面应用：macOS/Windows有独立桌面应用，适合不想在终端里工作的场景。Web：浏览器访问claude.ai进入code，可启动云端会话。05·工作流与实战模型选择与成本控制Claude5模型家族模型模型ID特点Opus5claude-opus-5最强推理，复杂重构、架构设计Opus5(1M)claude-opus-5[1m]100万token上下文，适合超大代码库分析Sonnet5claude-sonnet-5速度与能力平衡，日常开发主力Haiku4.5claude-haiku-4-5-20251001最快最便宜，简单任务、后台小任务省tok