Claude Code 完全指南：从入门到高级实践

一、Claude Code 简介

Claude Code 是 Anthropic 推出的智能编程工具，直接在终端中运行，帮助开发者快速将想法转化为代码。它无需额外的聊天窗口或 IDE 集成，直接在现有工作流中提供 AI 驱动的编程辅助，支持代码生成、调试、文档化等全流程开发任务。

目前国内阿里Qwen3-Coder-Plus、月之暗面kimi-k2-turbo-preview、智谱GLM-4.5都提供了接入支持，只用在系统环境变量ANTHROPIC_BASE_URL改为对应模型提供的URL，ANTHROPIC_AUTH_TOKEN换成对应模型的密钥即可直接用。

相关文档：

二、快速开始

2.1 30 秒极速上手

前提条件：安装 Node.js 18 或更新版本 

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 导航到项目目录
cd your-awesome-project

# 启动交互式会话
claude

完成后即可开始使用！如需深入学习，请继续阅读。

2.2 安装方式详解

2.2.1 NPM 安装（推荐）

适用于已安装 Node.js 的环境： 

npm install -g @anthropic-ai/claude-code

2.2.2 原生安装（测试版）

  • macOS、Linux、WSL： 
    curl -fsSL claude.ai/install.sh | bash
  • Windows PowerShell： 
    irm https://claude.ai/install.ps1 | iex

三、核心功能

3.1 Claude Code 能为你做什么？

  • 从描述构建功能：用自然语言描述需求，Claude 会制定计划、编写代码并验证功能。
  • 调试与修复问题：描述错误或粘贴报错信息，Claude 会分析代码库、定位问题并实施修复。
  • 导航代码库：支持查询项目架构、技术栈、文件结构等，通过 MCP 可接入 Google Drive、Figma 等外部数据源。
  • 自动化繁琐任务：修复 lint 问题、解决合并冲突、生成发布说明，支持本地命令或 CI 自动化执行。

3.2 开发者为何选择 Claude Code？

  • 终端原生集成：无需切换工具，直接在终端中与现有工作流结合。
  • 主动行动能力：可直接编辑文件、运行命令、创建提交，通过 MCP 扩展至 Jira、Slack 等工具。
  • Unix 哲学兼容：支持管道与脚本化，例如： 
    # 实时监控日志并通知异常
tail -f app.log | claude -p "若发现异常，通过 Slack 通知我"
  • 企业级保障：基于 Anthropic API 构建，支持 AWS/GCP 托管，内置 安全性、隐私保护 与合规能力。

四、管理 Claude 的内存（记忆）

了解如何使用不同的内存位置和最佳实践来管理 Claude Code 跨会话的内存。

Claude Code 可以跨会话记住您的偏好设置，比如样式指南和工作流程中的常用命令，确保在不同会话中保持一致的交互体验。

4.1 确定内存（记忆）类型

Claude Code 提供三种内存位置，每种都有不同的用途和适用场景：

内存类型 位置 用途 使用案例示例
项目内存 ./CLAUDE.md 项目的团队共享指令 项目架构、编码标准、常见工作流程
用户内存 ~/.claude/CLAUDE.md 所有项目的个人偏好设置 代码样式偏好、个人工具快捷方式
项目内存（本地） ./CLAUDE.local.md 个人项目特定偏好设置 （已弃用，见下文） 您的沙盒 URL、首选测试数据

说明：所有内存文件在启动 Claude Code 时都会自动加载到上下文中，作为对话的基础参考。

4.2 CLAUDE.md 导入机制

CLAUDE.md 文件支持通过 @path/to/import 语法导入其他文件，扩展内存内容的灵活性。

4.2.1 基本导入示例

# 项目基础参考  
查看 @README 了解项目概述，查看 @package.json 了解可用的 npm 命令。  

# 工作流程规范  
- git 工作流程参考 @docs/git-instructions.md  
- 部署流程参考 @docs/deployment-guide.md

4.2.2 个人与团队内存分离

通过导入用户主目录文件，可在团队共享内存中嵌入个人偏好，且不影响代码库提交： 

# 个人偏好设置  
- 代码风格参考 @~/.claude/my-code-style.md  
- 常用工具配置参考 @~/.claude/tool-config.md

4.2.3 导入规则

  • 支持相对路径和绝对路径。
  • 导入不会在 markdown 代码段（如 `@anthropic-ai/claude-code`）中生效。
  • 支持递归导入，最大深度为 5 层。
  • 运行 /memory 命令可查看当前加载的所有内存文件。

4.3 Claude 内存查找逻辑

Claude Code 会递归读取内存文件，确保不同层级的配置都能被加载：

  1. 从当前工作目录开始，向上递归至根目录（不包含根目录），读取所有 CLAUDE.md 或 CLAUDE.local.md 文件。
  2. 对于嵌套在当前目录子树中的 CLAUDE.md，不会在启动时自动加载，仅当 Claude 读取该子树中的文件时才会包含。

示例：在 foo/bar/ 目录运行 Claude 时，会加载 foo/CLAUDE.md 和 foo/bar/CLAUDE.md 中的内容。

4.4 快速添加与编辑内存

4.4.1 使用 # 快捷方式添加内存

在输入开头使用 # 字符可快速添加内存内容，系统会提示选择存储位置： 

> # 始终使用 2 空格缩进和 camelCase 命名规范  
# 请选择存储位置：  
# 1. 项目内存（./CLAUDE.md）  
# 2. 用户内存（~/.claude/CLAUDE.md）

4.4.2 使用 /memory 命令编辑内存

在会话中运行 /memory 命令，可在系统编辑器中直接打开内存文件进行批量编辑： 

> /memory  
# 打开默认编辑器编辑当前加载的内存文件

4.5 设置项目内存最佳实践

使用以下命令为项目初始化 CLAUDE.md 框架： 

> /init

推荐内存内容

  • 常用命令：记录构建、测试、部署等高频命令，避免重复搜索。
  • 编码规范：明确缩进、命名、注释等风格要求（如 "使用 ESLint 规则 prettier 格式化代码"）。
  • 架构模式：记录项目核心模块交互、数据流向等关键设计。
  • 团队约定：如分支命名规则（feature/xxx、bugfix/xxx）、PR 审查流程等。

维护建议

  • 定期更新：随着项目迭代，及时更新内存中的架构和流程信息。
  • 结构化组织：使用 markdown 标题和列表分组相关内容，提高可读性。
  • 具体明确：避免模糊描述，例如用 "使用 npm run test:unit 执行单元测试" 替代 "运行测试命令"。

五、基础使用流程

5.1 开始前准备

  • 打开终端或命令提示符
  • 准备一个代码项目目录

5.2 启动首个会话

  1. 导航到项目目录并启动 Claude： 
    cd /path/to/your/project
claude
  2. 首次启动将显示交互式提示符： 
    ✻ 欢迎使用 Claude Code！
> 尝试 "create a util logging.py that..."

提示：凭据安全存储在本地，详情见 凭据管理。

5.3 核心操作示例

5.3.1 探索代码库

# 询问项目功能
> what does this project do?

# 查询技术栈
> what technologies does this project use?

# 了解目录结构
> explain the folder structure

5.3.2 代码修改与调试

# 添加功能
> add a hello world function to the main file

# 修复 bug
> there's a bug where users can submit empty forms - fix it

5.3.3 Git 协作

# 查看更改文件
> what files have I changed?

# 提交更改
> commit my changes with a descriptive message

# 解决合并冲突
> help me resolve merge conflicts

5.4 基本命令速查表

命令 功能 示例
claude 启动交互式会话 claude
claude "task" 带初始提示启动会话 claude "fix the build error"
claude -p "query" 单次查询后退出 claude -p "explain this function"
claude -c 继续最近对话 claude -c
claude -r 恢复历史对话 claude -r
claude commit 创建 Git 提交 claude commit
/clear 清除对话历史 > /clear
/help 显示帮助命令 > /help
/memory 编辑内存文件 > /memory
exit 或 Ctrl+C 退出会话 > exit

完整命令列表见 CLI 参考。

六、高级工作流程

6.1 代码库探索与导航

6.1.1 快速概览项目

  1. 导航到项目目录并启动 Claude： 
    cd /path/to/project && claude
  2. 逐步深入查询： 
    > give me an overview of this codebase  # 高层次概览
> explain the main architecture patterns  # 架构分析
> how is authentication handled?  # 特定功能细节

6.1.2 定位关键代码

# 查找认证相关文件
> find the files that handle user authentication

# 分析组件交互
> how do these authentication files work together?

# 追踪执行流程
> trace the login process from front-end to database

6.2 错误修复与代码重构

6.2.1 高效调试

  1. 分享错误信息： 
    > I'm seeing an error when I run npm test
  2. 获取修复建议并应用： 
    > suggest ways to fix the @ts-ignore in user.ts
> update user.ts to add the null check you suggested

6.2.2 代码重构

  1. 识别遗留代码： 
    > find deprecated API usage in our codebase
  2. 按建议重构并验证： 
    > refactor utils.js to use ES2024 features
> run tests for the refactored code

6.3 测试与文档自动化

6.3.1 测试生成与验证

# 识别未测试代码
> find functions in NotificationsService.swift not covered by tests

# 生成测试用例
> add test cases for edge conditions in the notification service

# 运行并修复测试
> run the new tests and fix any failures

6.3.2 文档完善

# 查找未文档化代码
> find functions without JSDoc comments in auth.js

# 生成文档
> add JSDoc comments to these functions

# 验证文档规范
> check if the documentation follows project standards

6.4 高级功能：子代理与 MCP

6.4.1 子代理使用

子代理是专门处理特定任务的 AI 模块，支持自动或手动调用： 

# 查看可用子代理
> /agents

# 自动委托任务
> review my code changes for security issues

# 指定子代理
> use the debugger subagent to investigate login issues

6.4.2 MCP 外部数据集成

通过 MCP 接入外部工具数据： 

# 引用 GitHub 数据
> Show me issues from @github:repos/owner/repo/issues

# 读取设计文档
> Analyze the design in @drive:12345-design.docx

6.5 终端自动化与脚本集成

6.5.1 Unix 风格管道操作

# 分析日志并输出结果
cat build-error.txt | claude -p "explain the root cause" > output.txt

# 实时监控并通知异常
tail -f app.log | claude -p "notify via Slack on errors"

6.5.2 输出格式控制

支持文本、JSON 或流式 JSON 输出，适用于脚本集成： 

# JSON 格式输出分析结果
cat code.py | claude -p "analyze bugs" --output-format json > analysis.json

6.6 自定义斜杠命令

通过命令文件创建项目或个人专属命令，提升效率。

6.6.1 项目级命令

  1. 创建命令目录与文件： 
    mkdir -p .claude/commands
echo "Analyze code performance and suggest optimizations" > .claude/commands/optimize.md
  2. 在会话中使用： 
    > /optimize

6.6.2 带参数的命令

  1. 创建含 $ARGUMENTS 占位符的命令文件： 
    echo "Fix issue #$ARGUMENTS and add tests" > .claude/commands/fix-issue.md
  2. 使用时传入参数： 
    > /fix-issue 123  # 替换 $ARGUMENTS 为 123

七、钩子配置（高级扩展）

钩子是 Claude Code 的扩展机制，可在特定事件触发时执行自定义命令，支持工作流自动化。

7.1 配置方式

在设置文件中定义钩子（支持用户级 ~/.claude/settings.json 或项目级 .claude/settings.json）： 

{
  "hooks": {
    "PreToolUse": [  // 工具调用前触发
      {
        "matcher": "Bash",  // 匹配 Bash 工具
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bash 工具调用前执行' >> hook.log"
          }
        ]
      }
    ]
  }
}

7.2 常用钩子事件

事件名称 触发时机 用途示例
PreToolUse 工具调用前 验证命令安全性、自动批准可信操作
PostToolUse 工具调用后 代码格式化、测试自动执行
UserPromptSubmit 用户提交提示后 添加上下文、过滤敏感内容
SessionStart 会话启动或恢复时 加载项目环境信息

7.3 钩子输入与输出

钩子通过 stdin 接收 JSON 格式的事件数据（如工具名称、输入参数），通过 stdout 或退出代码返回结果：

  • 退出代码 0：成功执行，可返回附加上下文。
  • 退出代码 2：阻止当前操作（如禁止危险命令）。

八、CLI 参考

8.1 核心命令

命令 描述 示例
claude 启动交互式会话 claude
claude "query" 带初始提示启动会话 claude "explain this project"
claude -p "query" 单次查询后退出 claude -p "fix this error"
claude -c 继续最近对话 claude -c
claude -r "<session-id>" 恢复指定会话 claude -r "abc123"
claude update 更新到最新版本 claude update
claude mcp 配置 MCP 服务器 参考 MCP 文档

8.2 常用标志

标志 描述 示例
--print, -p 非交互模式查询 claude -p "explain"
--output-format 指定输出格式（text/json/stream-json） claude -p "query" --output-format json
--continue, -c 继续最近对话 claude -c
--resume, -r 恢复历史会话 claude -r "abc123"
--model 指定模型（如 claude-sonnet-4-20250514） claude --model sonnet

九、获取帮助与资源

通过以上内容，你可以全面掌握 Claude Code 的安装、内存管理、基础使用与高级技巧，将其无缝融入开发工作流，提升编程效率。

京ICP备13031296号-4