Claude Code 入门教程

初级阶段的核心是建立信任感——相信 Claude 能做的比你想象的多，然后慢慢把更多动作交出去。从安装、对话、调试，到提交代码、开 PR，这些单独看都不复杂，但串联起来会重塑你的日常开发节奏。这个阶段不需要追求技巧，最重要的一件事是：养成开口的习惯，遇到任何重复性的、机械性的操作，先问一句"Claude 能帮我做吗"，答案往往是肯定的

安装与配置

使用 brew 安装, 完整的安装方式查看 , 由于 mac 可以统一管理, 所以推荐使用 brew, 这里不推荐使用 npm 的方式安装

brew install --cask claude-code

npm 安装已弃用。原生安装程序更快，不需要依赖项, 且可以自动更新

配置国内模型

模型和请求地址配置 : ~/.claude/settings.json

• Claude Code--火山
• Claude Code - MiniMax

以下是火山配置模板, 不同的国内兼容平台配置地址和密钥不同, 其他均一致

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "<ARK_API_KEY>",
        "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding",
        "ANTHROPIC_MODEL": "<Model_Name>"
    }
}

编辑或新增 .claude.json 文件, MacOS & Linux 为 ~/.claude.json , 用来关闭使用 claude code 时候的登录凭证

{  
    "hasCompletedOnboarding": true
}

多模型切换

多个服务商切换

cc-switch 是一个便捷的工具，可以快速切换 Claude Code 的 API 配置, 不适合同时使用多模型, 其原理是通过工具的方式修改 claude 的配置文件, 从而使 claude 加载不同的配置

brew tap farion1231/ccswitch
brew install --cask cc-switch
brew upgrade --cask cc-switch

多服务商同时存在

采用多个客户端的方式, 但是其原理是使用 claude , 在运行过程中配置不同的环境变量来区分模型

例如可以把脚本命名成 claude-doubao

#!/usr/bin/env bash
# Wrapper for Claude Code CLI using Doubao API

CLAUDE_BIN="/opt/homebrew/bin/claude"

# Inject API credentials
export ANTHROPIC_AUTH_TOKEN="62162766-****-0b4be5c580de"
# 订阅模式
export ANTHROPIC_BASE_URL="https://ark.cn-beijing.volces.com/api/coding"
export ANTHROPIC_MODEL="ark-code-latest"
# 直接接口调用模式
# export ANTHROPIC_BASE_URL="https://ark.cn-beijing.volces.com/api/compatible"
# export ANTHROPIC_MODEL="ep-20260127181733-p4xgl"
export API_TIMEOUT_MS=3000000

# Keep a separate config dir (optional)
export CLAUDE_CONFIG_DIR="$HOME/.claude-doubao"

exec "$CLAUDE_BIN" "$@"

假定这个目录是 ~/program, 将这个目录加入 PATH, 可以全局访问

export PATH="$HOME/program:$PATH"

这样可以使多个客户端同时存在, 方便在速度和费用中间做权衡

登录

安装 Claude Code 后，在终端中运行 claude。首次启动时，Claude Code 会打开浏览器窗口供您登录。如果浏览器没有自动打开，请按 c 将登录 URL 复制到剪贴板，然后将其粘贴到浏览器中

claude

要登出并重新身份验证，请在 Claude Code 提示符处输入 /logout。如果您在登录时遇到问题，请参阅 身份验证故障排除

平台和集成

• Remote Control : 使用 Remote Control 从任何设备继续本地会话

claude remote-control

• 桌面端
• Chrome 插件
• Vs Code
• Jetbrains IDE

基本使用 (BY )

描述需求和Bug

用自然语言描述需求，让 Claude 生成代码

Claude Code 最核心的能力之一，就是把你脑子里的想法直接变成可运行的代码，而不需要你去记忆 API 签名或查文档。

使用时，直接在终端用中文或英文描述你要做什么就行。比如"帮我写一个 Spring Boot 接口，接收用户 ID，查询该用户最近 30 天的订单列表，按金额倒序返回"——Claude 会读取你当前项目的代码结构、已有的 Entity 和 Mapper，然后生成符合你项目风格的代码，而不是一段脱离上下文的模板。

几个让描述更有效的技巧：说清楚输入输出（接收什么、返回什么）；提到边界条件（比如"用户不存在时返回 404"）；指定技术约束（"用 MyBatis Plus，不要写 XML"）。描述越具体，生成质量越高，返工越少。

Claude 也能跨文件完成任务。你说"在现有的推荐系统里加一个基于浏览历史的冷启动策略"，它会主动去找相关的 Service、Repository、配置文件，理解现有逻辑后再动手，而不是凭空生成一段孤立的代码。

粘贴错误信息，让 Claude 定位并修复 bug

遇到报错时，最快的做法是把完整的错误栈直接粘贴进对话，加一句简短的背景说明，比如"调用推荐接口时出现这个错误，请帮我排查"。

Claude 会沿着堆栈追踪真正的出错位置，而不是只看最表层的异常。它会主动去读相关的类和方法，判断是空指针、类型不匹配、事务边界问题还是配置缺失，然后给出针对性的修复，同时解释为什么会出现这个问题。

几点使用建议：不要截图，要文本——截图无法被分析；附上触发路径，比如"执行某个测试用例时触发的"，能帮助 Claude 快速收窄范围；如果是偶发性 bug，描述复现条件，比如"并发量高时才出现"，Claude 会着重分析线程安全或缓存一致性问题。

对于那些没有明显报错但结果不对的隐性 bug，你也可以描述现象："接口返回的推荐列表有重复 ID，但我已经做了去重"，Claude 会推断可能的原因并逐一验证。这种"症状式调试"往往比自己盲目加日志高效很多。

理解 Claude 如何读取整个代码库上下文

这是很多人用了 Claude Code 一段时间后才真正想清楚的问题——它到底是怎么"理解"你的项目的？弄清楚这个机制，能帮你更有意识地组织项目结构，写出更好的 CLAUDE.md，也能解释为什么有时候它"突然变笨了"。

它不是一次性读完所有文件

很多人以为 Claude Code 启动时会扫描整个项目，把所有代码全部加载进来。实际上并非如此。

Claude Code 采用的是按需读取的策略。每次对话开始时，它会先读取少量关键文件建立初始印象——通常包括根目录的 CLAUDE.md、package.json / pom.xml / build.gradle 等构建文件、.gitignore，以及你当前所在目录的结构。这些文件告诉它：这是个什么类型的项目、用了哪些技术栈、有哪些主要模块。

真正的文件读取发生在执行任务的过程中。当你说"帮我给 UserService 加一个方法"，它会去找 UserService.java，读取后发现里面依赖了 UserRepository，于是继续读 UserRepository，再顺着找相关的 Entity 和 DTO。这个过程是链式的、惰性的，只读任务真正需要的部分。

上下文窗口是核心约束

Claude Code 底层是语言模型，所有"理解"都发生在一个有限的上下文窗口里。目前 Claude Sonnet 4.6 支持最高 100 万 token 的上下文，听起来很大，但一个中等规模的 Spring Boot 项目轻松就有几十万行代码，全部塞进去既不现实也没必要。

这意味着：Claude 在任意时刻能"看到"的代码是有限的。它会做取舍——优先保留你正在讨论的文件、最近编辑过的文件、以及与当前任务强相关的文件。那些离任务较远的模块，即使存在于项目里，Claude 也可能没有读取。

当你在一次很长的对话里不断切换话题，上下文会越来越拥挤。早期加载的文件内容可能被"挤出"窗口，导致 Claude 对之前讨论过的代码"失忆"。这就是为什么 /compact 和 /clear 命令很重要——适时压缩或重置上下文，比死撑一个超长对话效果好得多。

@ 引用是你的主动控制手段

既然 Claude 的读取是按需惰性的，你就可以主动告诉它该去看哪里。@ 引用就是这个控制手段。

@src/service/RecommendService.java 这个方法的性能有问题，帮我分析

@src/config/RedisConfig.java @src/service/CacheService.java 
这两个文件配合起来看，Redis 连接池配置是否合理？

用 @ 显式指定文件，比依赖 Claude 自行探索更精准、更节省 token，也更不容易产生幻觉——因为它看到的是你指定的真实代码，而不是靠推断"猜"出来的结构。

CLAUDE.md 是项目的"地图"

如果说上下文窗口是 Claude 的短期记忆，CLAUDE.md 就是它每次启动都会读取的长期记忆入口。

在 CLAUDE.md 里描述清楚项目结构、模块职责、关键约定，Claude 就不需要每次从零探索。比如你写上"推荐系统的核心逻辑在 recommend-core 模块，数据层全部用 MyBatis Plus，禁止使用原生 JDBC"，Claude 在处理相关任务时就会直接聚焦到正确的位置，而不是在整个项目里漫无目的地搜索。

一个好的 CLAUDE.md 本质上是在替 Claude 压缩认知成本，让它把有限的上下文预算花在真正重要的地方。

为什么有时候它"不知道"某个文件的存在

这是初学者最常困惑的现象。你明明有一个 OrderStatisticsService，但 Claude 在生成代码时完全没有引用它，而是重新写了一遍类似的逻辑。

原因通常有三个：一是那个文件从未出现在当前对话的上下文里；二是项目结构比较深，Claude 的自动探索没有触及那个路径；三是 CLAUDE.md 里没有提到这个模块的存在。

解决方式很直接——用 @ 手动引入那个文件，或者在 CLAUDE.md 里把重要的工具类和服务层做个索引式的说明。Claude Code 不是全知的，它的"智能"很大程度上依赖你给它的信息质量。

使用 /help 查看内置命令列表

/help 是进入 Claude Code 后第一个值得运行的命令。它输出的不只是一张命令表，更是整个工具能力边界的索引。花几分钟认真看一遍，比摸索几周更高效。

运行方式

在任意对话状态下，直接输入：

/help

不需要加任何参数。Claude Code 会立即输出当前版本支持的所有内置命令，包括命令名、简短描述和基本用法。如果你想查某个具体命令的详细说明，可以加上命令名：

/help compact
/help memory

命令的几个分类

/help 输出的命令大致可以归为以下几类，理解分类比死记命令名更有用：

会话管理类

控制当前对话的状态和生命周期

/clear 清空当前上下文重新开始

/compact 在保留摘要的前提下压缩对话历史，释放上下文空间

/resume 恢复上一次的会话

/exit 退出 Claude Code。这类命令在长时间工作时频繁用到，值得最先记住。

记忆与上下文类

管理 Claude 的跨会话记忆

/memory 查看和编辑 Claude 当前记住的项目信息；配合 CLAUDE.md 使用，可以精细控制哪些内容需要持久化，哪些只是临时上下文

工具与模式类

切换 Claude Code 的工作行为

比如控制是否允许自动执行 bash 命令、是否进入只读模式等。

对于在生产环境或敏感代码库里操作的场景，这类命令能提供额外的安全边界。

反馈与调试类

/bug 直接向 Anthropic 提交问题报告，会自动附带当前会话的上下文，比去 GitHub 手动开 issue 方便得多。遇到 Claude 行为异常时，这是最快的反馈路径

自定义命令类

这是很多人没注意到的部分

/help 里除了内置命令，也会列出你在项目里自定义的 slash 命令。

自定义命令存放在 .claude/commands/ 目录下，每个 .md 文件对应一个命令。团队协作时，把常用的工作流封装成自定义命令放进仓库，所有人共享同一套操作规范，是非常实用的做法。

一个容易忽略的细节

/help 的输出内容会随版本更新而变化。Claude Code 迭代非常快，平均每周都有新功能或命令加入。养成偶尔重新跑一遍 /help 的习惯，是跟上工具演进的最低成本方式——比订阅更新日志更直接，因为你看到的就是当前安装版本的真实状态，不存在文档滞后的问题。

如果你用 brew 或 winget 安装的，记得定期升级：

brew upgrade claude-code
# 或
winget upgrade Anthropic.ClaudeCode

升完之后跑一遍 /help，对比一下有没有新命令出现，是快速感知版本变化的好习惯

和文档的关系

/help 给的是命令的骨架——名称和一句话描述。如果需要某个命令的完整参数说明和使用示例，官方文档 code.claude.com/docs 会更详细。两者结合用：/help 用来快速回忆"有没有这个命令"，文档用来搞清楚"这个命令怎么用得最好"。不需要把所有命令背下来，知道去哪里找比记忆本身更重要

Git 工作流(BY )

让 Claude 自动暂存更改并生成 commit 消息

手写 commit 消息是开发里最容易敷衍了事的环节。"fix bug"、"update"、"temp"——这类消息在很多项目的 git log 里比比皆是。Claude Code 在这件事上能真正帮到你，不只是省事，而是能生成比大多数人手写更准确、更有信息量的消息。

最基本的用法

完成一段修改后，直接告诉 Claude：

帮我提交这些更改

或者更明确一些：

把当前所有修改暂存并生成一个合适的 commit 消息提交

Claude 会执行以下步骤：先运行 git diff 和 git status 读取当前的变更内容，理解改了哪些文件、改动的性质是什么，然后运行 git add 暂存，最后用 git commit -m 提交，消息由它根据实际改动内容生成。

整个过程你可以在终端里看到每一步的执行，不是黑盒操作。

生成消息的质量

Claude 生成的 commit 消息通常遵循业界主流的 Conventional Commits 规范，格式类似：

feat(recommend): add cold-start strategy based on browse history

- Introduce BrowseHistoryStrategy implementing RecommendStrategy
- Fall back to popularity-based ranking when history is empty
- Add unit tests for edge cases with new users

它能做到这个质量，是因为它真的读了 diff，而不是靠猜。如果你改的是一个 SQL 查询优化，它会写 perf；如果是修了一个空指针，它会写 fix；如果是加了新接口，它会写 feat。类型前缀的判断基于实际变更内容，不是随机选的。

让消息更符合你的规范

不同团队对 commit 消息的要求不一样。你可以在指令里直接说明：

提交这些更改，消息用中文，格式是"模块名: 改动描述"

提交，消息要包含 Jira ticket 号 PROJ-1234

按文件模块拆成多个 commit 分别提交，不要全部混在一个 commit 里

最后这个场景尤其有用——当你一口气改了多个不相关的模块，Claude 会分析变更内容，判断哪些属于同一逻辑单元，拆分成独立的 commit，每个消息单独描述。这是手动操作最繁琐、也最容易偷懒跳过的步骤，交给 Claude 反而做得更彻底。

如果你希望整个项目始终保持一致的 commit 风格，最好的做法是把规范写进 CLAUDE.md：

## Git 规范
- commit 消息使用 Conventional Commits 格式
- type 范围：feat / fix / perf / refactor / test / docs / chore
- scope 使用模块名，如 recommend / order / user
- 消息用英文，正文可选，超过 3 个文件改动时必须写正文

写进去之后，每次让 Claude 提交，它都会自动遵守，不需要每次重复说明。

只生成消息，不自动提交

如果你想保持对提交的最终控制权，可以让 Claude 只生成消息，由你决定要不要用：

帮我看一下当前的改动，给我一个合适的 commit 消息，我自己来提交

Claude 会输出建议的消息文本，你复制进去用，或者根据它的版本微调。这种方式在改动比较敏感、或者你习惯亲手执行 git 操作的场景下更合适。

一个值得养成的习惯

不要等改动堆积很多再一次性提交。每完成一个清晰的逻辑单元——一个功能点、一个 bug 修复、一次重构——就立刻让 Claude 提交一次。小步提交让 git log 变成真正可读的开发历史，也让 code review 和问题回溯容易得多。

Claude Code 把提交这件事的摩擦降到接近零，没有理由再用"太麻烦"当借口攒一堆乱糟糟的 diff 最后混在一个 commit 里交出去。

让 Claude 创建分支、开 Pull Request

分支管理和 PR 是团队协作的日常动作，但也是最容易产生低质量输出的环节——分支名随手一起、PR 描述只写"fix"、reviewer 看了完全不知道改了什么。Claude Code 能把这些动作做得更规范，同时几乎不增加你的操作成本。

创建分支

最直接的方式：

帮我基于当前分支创建一个新分支，用来开发用户推荐功能

Claude 会根据你的描述生成一个符合规范的分支名，比如 feat/user-recommendation，然后执行 git checkout -b 完成创建并切换。

如果你的团队有固定的分支命名规范，直接说明：

创建一个新分支，命名格式是 feature/PROJ-1234-简短描述

或者写进 CLAUDE.md 一劳永逸：

## 分支规范
- 新功能：feat/模块名-简短描述
- bug 修复：fix/问题描述
- 分支名全小写，单词用连字符分隔
- 必须包含对应的 Jira ticket 号，如 feat/recommend-PROJ-1234

此后每次让 Claude 建分支，它都会自动套用这套规则，不需要重复提醒。

开 Pull Request

完成功能开发、提交好 commit 之后：

帮我把这个分支推送到远程，然后开一个 Pull Request

Claude 会依次执行 git push，然后通过 GitHub CLI（gh pr create）或 GitLab CLI 创建 PR。

PR 的标题和描述是它真正能帮到你的地方。它会回顾这个分支上所有的 commit、读取改动的文件和内容，生成一份有实质信息量的描述，通常包含：

• 这次改动的背景和目的
• 具体做了什么，改了哪些模块
• 如何验证，比如相关测试或手动测试步骤
• 已知的限制或后续计划（如果有）

对于 reviewer 来说，这种描述和"update code"的差距是天壤之别。

控制 PR 描述的格式

很多团队有固定的 PR 模板，放在 .github/pull_request_template.md 里。Claude Code 会自动检测并遵守这个模板，按照模板里的每个 section 填写内容，而不是自由发挥。

如果没有模板，但你有格式偏好，可以直接说：

PR 描述要包含：改动背景、技术方案、测试说明、是否需要数据库迁移

或者在 CLAUDE.md 里定义标准结构：

## PR 规范
描述必须包含以下部分：
- ## 背景：为什么要做这个改动
- ## 方案：技术实现思路
- ## 测试：验证方式
- ## 风险：可能的影响范围
- ## 相关 ticket：Jira 链接

指定 reviewer 和标签

开 PR，指定 @张三 @李四 作为 reviewer，加上 labels: backend, needs-review

Claude 会在创建 PR 时带上这些参数。如果你们团队的 reviewer 分配有固定规律，比如后端改动固定 review 某几个人，同样可以写进 CLAUDE.md，让 Claude 自动判断该指定谁。

从 issue 到分支到 PR 的完整链路

Claude Code 能处理更完整的工作流。比如你在 GitHub 上有一个 issue，可以这样说：

基于 issue #42 创建分支，完成修复后开 PR 关联这个 issue

Claude 会读取 issue 的标题和描述，用 issue 内容作为分支名和 PR 描述的依据，并在 PR 描述里自动加上 Closes #42，合并后 issue 自动关闭。整个从问题到解决的链路，在 git 历史和 issue tracker 里都有清晰的关联记录。

前提条件

Claude Code 创建 PR 依赖命令行工具的存在。GitHub 需要安装并登录 gh（GitHub CLI）；GitLab 需要 glab。如果这两个工具没有配置，Claude 会告诉你缺少什么，并给出安装指引，不会静默失败。

两个工具的安装都很简单：

# GitHub CLI
brew install gh && gh auth login

# GitLab CLI
brew install glab && glab auth login

配置一次，之后所有项目都能用，不需要重复设置