Claude Code 完全指南

一、安装方式

macOS（推荐）

# 方式1：原生安装（无需 Node.js）
curl -fsSL https://claude.ai/install.sh | bash
# 安装后 ~/.local/bin/claude 加入 PATH
# export PATH="$HOME/.local/bin:$PATH"

# 方式2：Homebrew
brew install --cask claude-code

Windows

# PowerShell
irm https://claude.ai/install.ps1 | iex

# CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# WinGet
winget install Anthropic.ClaudeCode

Linux / WSL2

curl -fsSL https://claude.ai/install.sh | bash

验证安装

claude --version

二、国内使用方案（CC Switch + DeepSeek）

> 国内直连 Anthropic 不稳定，推荐用 CC Switch 接入 DeepSeek API，成本极低。

安装 CC Switch（macOS）

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

或下载 DMG 手动安装：https://github.com/farion1231/cc-switch/releases

配置 DeepSeek Provider

1. 打开 CC Switch 应用
2. 点击「添加 Provider」，填写：

1. 点击「测试连接」→ 成功后点击「启用」
2. CC Switch 会自动写入 ~/.claude/settings.json

DeepSeek 价格参考

完成 Anthropic 登录

首次运行 claude 需要 OAuth 登录（用邮箱注册即可，付费订阅非必需——CC Switch 会拦截请求转到 DeepSeek）：

claude
# 浏览器自动打开，完成邮箱登录
# 登录后终端显示会话启动成功

三、基础命令

启动模式

交互模式斜杠命令

快捷键

四、CLAUDE.md 项目配置（核心）

每次会话自动读取，直接决定输出质量。

存放位置

• 项目级：<项目根目录>/CLAUDE.md（项目技术栈、编码规范）
• 用户级：~/.claude/CLAUDE.md（个人偏好，跨项目生效）

推荐内容模板

## 项目概述
- 技术栈：TypeScript + React + Node.js
- 包管理器：npm
- 测试框架：Vitest

## 编码规范
- 使用 TypeScript 严格模式
- 函数必须有 JSDoc 注释
- 不使用 any 类型

## 常用命令
- 启动：npm run dev
- 测试：npm test
- 构建：npm run build

## 禁止操作
- 不要修改 package.json 中的依赖版本
- 不要提交未通过测试的代码

生成初始配置

claude
> /init    # 自动扫描项目生成初始 CLAUDE.md
# 然后手动补充上述内容

五、核心工作流

工作流1：代码生成

# 简单函数
create a utility function that validates email addresses using regex, 
include JSDoc and edge cases

# 多文件功能（跨层实现）
implement user notification feature with:
1. database table migration
2. API endpoint in src/routes/
3. frontend component in src/components/

# 参考现有模式（引用文件）
@src/routes/users.ts - follow this pattern to implement /api/products

工作流2：Bug 修复

# 粘贴错误信息（保留英文原文）
paste the full error message here

# 自动修复测试
run npm test, find failing tests, and fix them

# 审查上次提交是否引入 Bug
review the changes in my last commit for potential bugs

工作流3：Git 操作

# 智能提交（自动生成语义化 commit message）
claude commit

# 创建 PR（自动汇总变更）
claude
> create a pr

# 处理 PR 审查评论
> /pr-comments

六、进阶玩法

MCP（模型上下文协议）配置

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "args": ["/path/to/allowed/dir"]
    }
  }
}

Hooks（事件触发自动化）

配置方式：交互模式中执行 /hooks

常用事件：

• permission_prompt：Claude 请求权限时触发
• idle_prompt：Claude 等待用户输入时触发

示例（macOS 通知）：

osascript -e 'display notification "Claude needs attention" with title "Claude Code"'

自定义斜杠命令

在 .claude/commands/ 下创建 .md 文件：

# .claude/commands/review-pr.md
Review the current PR diff. Focus on:
1. Security issues
2. Performance problems
3. Code style violations

创建后可通过 /review-pr 调用。

子代理（Subagents）

在 .claude/agents/ 下创建 JSON 配置文件，定义专门代理处理复杂任务。

管理：/agents 查看和配置。

Plan Mode（安全审查模式）

use plan mode to review the authentication architecture

此模式下 Claude 只能读取文件和提问，不能修改文件或执行命令。

并行会话（Git Worktrees）

claude --worktree feature-auth
claude --worktree bugfix-123

每个 worktree 有独立分支和工作目录，互不干扰。

七、权限配置

在 .claude/settings.json 中预配置权限，跳过安全命令审批：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)"
    ]
  }
}

权限审批选项：

• y：仅本次允许
• n：拒绝，Claude 尝试替代方案
• a：当前会话始终允许
• d：永久拒绝该类操作

八、常见问题排查

自动诊断

claude
> /doctor    # 输出自动诊断报告

九、Prompt 技巧

黄金三规则

1. 目标先行：第一句话明确说明要实现什么
2. 边界明确：指定可以修改哪些文件、做哪些操作
3. 验收标准：清晰说明完成的定义

好的 Prompt 示例

# ✅ 好：具体、有边界、有验收标准
Refactor the error handling in src/services/payment.ts:
- Replace all throw statements with Result type
- Maintain backward compatibility
- Add tests for all new error cases
- Run npm test to verify before finishing

# ❌ 差：模糊、无边界
fix the error handling

文件引用技巧

用 @ 前缀引用文件，Claude 自动加载内容作为上下文：

Explain the logic in @src/utils/auth.js
Compare @src/routes/users.ts vs @src/routes/orders.ts error handling