最近在深度使用 Claude Code，发现真的很香！即整理了一份全面的指南，从零开始逐步了解 Claude Code 的核心功能、高级特性和最佳实践。这篇博客实际上更像是一本工具书，让我自己在使用时也能随时参考其内容，更好的使用这个强大的 AI 工具。

一、Claude Code 简介

1.1 什么是 Claude Code?

Claude Code(CC)是由 Anthropic 开发的系统级 AI Agent,它不仅是一个代码编写工具,更是一个可以通过自然语言指令完成各种电脑任务的智能助手。

核心特性:

1.2 Claude Code vs 传统工具

核心差异:

• 传统工具: 单一功能,需要人工操作多个工具完成复杂任务(代码编辑器、Chat AI、Coding 助手等各干各的)。
• Claude Code: 系统级 AI Agent,通过自然语言指令即可完成全流程任务(代码编写、对话问答、数据分析、文件管理、爬虫自动化、Office 处理等一体)。

二、安装与配置

2.1 前置准备

必需工具:

验证安装:

# 检查 Node.js 版本
node -v

# 检查 Git 版本
git --version

2.2 安装 Claude Code

全局安装(推荐):

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

验证安装:

claude --version

2.3 配置模型

Claude Code 支持多种模型配置方式,你可以根据自己的需求选择合适的模型。

方式一:手动配置 (通用方式)

手动配置适用于所有兼容 Anthropic API 的模型。

Windows:

setx ANTHROPIC_BASE_URL "模型API地址"
setx ANTHROPIC_AUTH_TOKEN "你的API密钥"
setx ANTHROPIC_MODEL "模型名称"

macOS/Linux:

export ANTHROPIC_BASE_URL=模型API地址
export ANTHROPIC_AUTH_TOKEN=你的API密钥
export ANTHROPIC_MODEL=模型名称

# 永久配置(添加到 ~/.bashrc 或 ~/.zshrc)
echo 'export ANTHROPIC_BASE_URL=模型API地址' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=你的API密钥' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL=模型名称' >> ~/.bashrc
source ~/.bashrc

常用国内模型配置示例:

配置示例(以智谱GLM为例):

export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
export ANTHROPIC_AUTH_TOKEN=your_glm_api_key
export ANTHROPIC_MODEL=GLM-4.7

注意: 配置环境变量后需要重启终端或运行 source ~/.bashrc 使配置生效。

方式二:使用自动化助手 (仅适用于智谱GLM)

如果选择使用智谱GLM系列模型,还可以使用自动化配置助手:

npx @z_ai/coding-helper

按照交互式提示完成配置: 选择界面语言、设置 Coding 套餐、配置 API 密钥、选择编码工具。这种方式可以自动完成智谱GLM模型的配置,适合不想手动设置环境变量的用户。

国内模型对比

2.4 启动 Claude Code

基本启动:

claude

危险模式(跳过权限确认,不推荐使用):

claude --dangerously-skip-permissions

Headless 模式(非交互式):

git diff | claude -p "解释这些更改"

三、核心概念详解

了解了 Claude Code 的安装配置后，深入了解一下它的一些核心概念。这些概念是充分发挥 Claude Code 能力的基础。

3.1 Skills(技能包)

什么是 Skills?

Skills 是预封装的工作流,就像游戏中的”技能包”,用完即走,不占用上下文。它是别人已经编写好的、可直接使用的功能模块。

官方 Skills 库: https://github.com/anthropics/skills (32k+ Stars)

Skills 的类型

常用官方 Skills

# 前端设计技能
npx skills-installer install @anthropics/claude-code/frontend-design --client claude-code

# 文档协同技能
npx skills-installer install @anthropics/claude-code/doc-coauthoring --client claude-code

# Canvas 设计技能
npx skills-installer install @anthropics/claude-code/canvas-design --client claude-code

# PDF 处理技能
npx skills-installer install @anthropics/claude-code/pdf --client claude-code

# 算法艺术生成
npx skills-installer install @anthropics/claude-code/algorithmic-art --client claude-code

如何使用 Skills

查看可用 Skills:

claude /skills

调用 Skill:

# 在 Claude Code 对话中
使用 frontend-design skill 优化 https://example.com

使用 pdf skill 提取 report.pdf 中的表格数据

如何编写自己的 Skills

Skill 目录结构:

my-skill/
├── skill.json          # Skill 元数据
├── skill.md            # Skill 文档
├── api/                # API 定义(可选)
└── tools/              # 自定义工具(可选)

skill.json 示例:

{
  "name": "my-custom-skill",
  "description": "我的自定义技能",
  "version": "1.0.0",
  "author": "Your Name",
  "categories": ["automation"],
  "license": "MIT",
  "skill": {
    "file": "skill.md",
    "description": "这个技能用于..."
  }
}

skill.md 示例:

# My Custom Skill

这个技能帮助用户快速完成[特定任务]。

## 使用场景

- 场景1:描述...
- 场景2:描述...

## 使用方式

用户只需要告诉你要完成什么,这个技能就会自动:

1. 分析需求
2. 执行步骤
3. 返回结果

## 注意事项

- 注意事项1
- 注意事项2

安装本地 Skill:

# 将技能复制到 Claude Code 配置目录
cp -r my-skill ~/.claude/skills/

# 或使用安装命令
npx skills-installer install ./my-skill --client claude-code

3.2 Hooks(钩子)

什么是 Hooks?

Hooks 是在特定事件触发时自动执行的脚本,用于自定义工作流、拦截危险操作、自动格式化代码等。

Hook 事件类型

Hook 配置方式

方式一:通过 /hooks 命令

# 在 Claude Code 中
/hooks

方式二:通过配置文件

在 ~/.claude/settings.json 或项目 .claude/settings.json 中配置:

{
  "hooks": {
    "user-prompt-submit-hook": {
      "command": "npm run validate-prompt",
      "enabled": true
    },
    "tool-use-hook": {
      "command": "~/.claude/hooks/check-permission.sh",
      "enabled": true,
      "blocking": true
    },
    "after-tool-use-hook": {
      "command": "echo 'Tool used: {{toolName}}' >> ~/.claude/hooks.log",
      "enabled": true
    }
  }
}

Hook 实战示例

拦截危险命令:

#!/bin/bash
TOOL_NAME=$(jq -r '.toolName' <<< "$CLAUDE_HOOK_INPUT")
DANGEROUS_TOOLS=("rm" "delete" "format" "shutdown")

if [[ " ${DANGEROUS_TOOLS[@]} " =~ " ${TOOL_NAME} " ]]; then
  echo "⚠️  警告:即将执行危险操作 - $TOOL_NAME"
  echo "请确认是否继续? (yes/no)"
  read -r confirmation
  if [[ "$confirmation" != "yes" ]]; then
    exit 1
  fi
fi

自动格式化代码(来自创始人实战 - 消灭 CI 格式报错):

{
  "hooks": {
    "after-tool-use-hook": {
      "command": "bun run format || true",
      "enabled": true,
      "blocking": false
    }
  }
}

工作原理: 每次 Claude 使用 Write/Edit 工具后自动触发格式化; || true 确保失败不阻塞。效果: CI 无格式报错、代码风格一致、无需手动格式化。

3.3 Plugins(插件)

什么是 Plugins?

Plugins 是打包在一起的扩展集合,可以包含: 5 个 Skills、10 个斜杠命令、3 个 MCP 服务器配置、2 个 SubAgent 定义、若干 Hooks。

Plugins vs Skills:

哪里获取已有 Plugins?

添加插件市场:

claude /plugin marketplace add anthropics/skills
claude /plugin marketplace add ~/my-marketplace
claude /plugin   # 选择 "Browse Plugins" 查看列表

安装 Plugin: claude plugin install <plugin-name> 从本地安装: claude plugin install ./my-plugin 从 GitHub: claude plugin install github:user/repo 卸载: claude plugin uninstall <plugin-name>

创建自定义 Plugin 目录结构:

my-plugin/
├── plugin.json
├── skills/
├── commands/
├── mcp/
├── agents/
└── hooks/

plugin.json 示例:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "author": "Your Name",
  "skills": ["skills/skill1", "skills/skill2"],
  "commands": [{ "name": "/my-command", "description": "我的自定义命令", "file": "commands/my-command.md" }],
  "mcpServers": [{ "name": "my-mcp", "config": "mcp/mcp-config.json" }],
  "agents": [{ "name": "my-agent", "config": "agents/agent1.json" }]
}

3.4 MCP Servers(模型上下文协议服务器)

什么是 MCP?

MCP (Model Context Protocol) 是 AI 的扩展接口标准,通过添加 MCP 服务器可以扩展 Claude Code 获取外部工具、资源、服务的能力。

常用 MCP 服务器

MCP 安装方式

方式一:命令行安装

claude mcp add chrome-devtools npx chrome-devtools-mcp@latest

方式二:配置文件 编辑 ~/.claude/mcp.json:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "disabled": false
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your_github_token_here" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/db" }
    }
  }
}

验证: claude mcp list、claude mcp test chrome-devtools，或在对话中输入 /mcp。

Chrome DevTools MCP 使用示例: 用 Chrome 打开指定 URL 后，在对话中说「通过 chrome devtools mcp 截取截图、提取链接、分析页面结构、获取性能数据」等。内置工具包括 chrome_navigate、chrome_screenshot、chrome_click、chrome_fill、chrome_evaluate 等 26 个。

3.5 Subagents(子代理)

什么是 Subagents?

Subagents 是可以并行处理任务的独立 AI 代理,每个子代理拥有独立的 200K 上下文窗口。核心理念: 把常用工作流看作自动化运行的”子智能体”,各司其职、并行处理。

Subagent 配置

方式一: 在 Claude Code 中输入 /agents。 方式二: 在 ~/.claude/agents.json 或项目 .claude/agents.json 中配置:

{
  "agents": {
    "code-reviewer": {
      "description": "专门负责代码审查的子代理",
      "model": "claude-opus-4-5",
      "instructions": "你是一个专业的代码审查专家,专注于检查代码质量、安全漏洞和性能问题。",
      "tools": ["read", "search", "git"],
      "permissions": { "allowWrite": false }
    },
    "test-writer": {
      "description": "专门负责编写测试的子代理",
      "model": "claude-sonnet-4-5",
      "instructions": "你是一个测试工程师,专注于编写全面的单元测试和集成测试。",
      "tools": ["read", "write", "bash"]
    },
    "doc-generator": {
      "description": "专门负责生成文档的子代理",
      "model": "claude-sonnet-4-5",
      "instructions": "你是一个技术文档专家,专注于生成清晰、准确的技术文档。",
      "tools": ["read", "write"]
    }
  }
}

使用示例

在对话中说: 「我需要完成用户认证功能,请帮我: 1. 使用 code-reviewer agent 审查现有认证代码 2. 使用 test-writer agent 编写测试用例 3. 使用 doc-generator agent 更新 API 文档。这三个任务并行执行。」Claude Code 会自动创建三个子代理、分配上下文、并行执行并汇总结果。

实战子代理案例(创始人 Boris Cherny)

• code-simplifier: 在 .claude/agents/code-simplifier.md 中定义「代码精简专家」: 分析复杂度、识别可简化逻辑、提供优化建议但保持功能不变。
• verify-app: 在 .claude/agents/verify-app.md 中定义「端到端测试专家」: 运行完整测试、检查关键路径、验证边界、确保体验「感觉对劲」,有问题则给出修复步骤。 使用方式: 「使用 code-simplifier agent 优化刚才写的代码」「使用 verify-app agent 验证应用是否正常工作」。

3.6 CLAUDE.md(项目记忆文件)

什么是 CLAUDE.md?

CLAUDE.md 是 Claude Code 的”项目记忆文件”,记录项目结构、构建命令、代码规范、架构决策等信息,让 Claude Code 快速理解项目上下文。

CLAUDE.md 的作用

CLAUDE.md 最佳位置与优先级

• 项目根目录 _CLAUDE.md → 全局项目配置
• src/.claude/CLAUDE.md → 模块级配置
• .claude/rules/auth.md 等 → 特定规则
• home/.claude/CLAUDE.md → 用户级配置

优先级: 特定规则 > 模块配置 > 项目配置 > 用户配置。

生成 CLAUDE.md 的方式

• 方式一: 在项目根目录执行 claude /init，自动扫描并生成构建/测试命令、目录结构、代码规范等。
• 方式二: 手动 touch CLAUDE.md，然后让 Claude「请根据当前项目结构生成 CLAUDE.md 文件」。
• 方式三: 在 .claude/rules/ 下创建 auth.md、database.md、api.md、testing.md 等模块化规则。
• 方式四 Memory Updates: 直接说「Update CLAUDE.md: always use bun instead of npm」「Update CLAUDE.md: 不要使用 enum,改用 string union」,Claude 会自动把新知识写入记忆文件。

CLAUDE.md 的 AI 进化机制(创始人实战)

• 核心理念: 让 Claude 在 Code Review 中自我迭代,越用越聪明。
• 流程: 1) 在 PR 中发现问题时 @claude 修复; 2) 说「请把这次的教训写入 CLAUDE.md: 不要使用 enum,改用 string union」; 3) Claude 在 CLAUDE.md 中添加「代码规范更新」; 4) 将 CLAUDE.md 签入 Git,团队共享。
• 价值: 集体智慧、持续进化、知识沉淀、团队协作。

四、高级功能

实际上 CC 还有一些高级功能，这些功能将帮助更高效地完成复杂任务。

4.1 Plan 模式(规划模式)

什么是 Plan 模式?

Plan 模式是一种”先规划、后执行”的工作模式,Claude 会先分析项目架构、依赖关系并起草实现方案,确认后才开始编写代码。

Anthropic 开发者关系负责人 Ado Kukic 有 90% 的时间都在使用这个模式。

核心价值: 在这个模式下,Claude 会阅读代码、分析架构、起草计划,但绝不修改代码。直到你批准计划,它才会动手。你是架构师,它是执行者。

进入 Plan 模式

快捷键:

# 按两次 Shift+Tab
Shift+Tab, Shift+Tab

命令方式:

/plan

Plan 模式工作流程

1. 探索阶段

• 读取相关文件
• 分析代码结构
• 理解依赖关系

2. 规划阶段

• 设计实现方案
• 列出具体步骤
• 识别潜在风险

3. 确认阶段

• 展示完整计划
• 等待用户反馈
• 根据反馈调整

4. 执行阶段

• 按计划实施
• 实时反馈进度
• 处理异常情况

Plan 模式最佳实践

适合场景:

• ✅ 复杂功能开发(多文件、多步骤)
• ✅ 架构重构
• ✅ 性能优化
• ✅ 代码迁移
• ✅ 不熟悉的项目

不适合场景:

• ❌ 简单 bug 修复
• ❌ 单行代码修改
• ❌ 文档查询
• ❌ 快速原型验证

使用技巧:

# 启用 Plan 模式
Shift+Tab × 2

# 明确任务需求
请帮我实现用户认证功能,包括:
1. 用户注册
2. 用户登录
3. JWT token 验证
4. 密码加密存储

# Claude 会先探索并规划,确认后开始执行? (yes/no)
# 确认后开始实施
yes

4.2 Sandbox 模式(沙箱模式)

什么是 Sandbox 模式?

Sandbox 模式通过定义允许的操作范围,拦截危险操作,提高安全性。

配置 Sandbox 模式

方式一:通过 /permissions 命令

claude /permissions

方式二:配置文件

编辑 ~/.claude/settings.json:

{
  "permissions": {
    "allow": {
      "bash": ["npm install", "npm test", "npm run build", "git *", "node -v", "npm -v"],
      "write": ["src/**/*", "tests/**/*", "*.md"],
      "read": ["**/*"]
    },
    "deny": {
      "bash": ["rm -rf *", "format *", "shutdown", "reboot"],
      "write": ["node_modules/**/*", ".git/**/*", "/etc/*", "/usr/*"]
    }
  }
}

最小权限原则: 只开放必要命令与路径。

4.3 Headless 模式(无头模式)

什么是 Headless 模式?

Headless 模式是非交互式运行方式,输出结果直接流向标准输出,可集成到 Shell 脚本或 CI/CD 流程中。

使用场景:

基本用法:

# 从管道输入
git diff | claude -p "解释这些更改"

# 从文件输入
cat file.txt | claude -p "总结这个文件"

# 直接指定
claude -p "检查代码质量" < src/main.js

CI/CD 集成示例:

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Code Review
        run: |
          git diff origin/main...HEAD | claude -p "审查这个 PR 的代码变更" > review.txt
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

4.4 Vim 模式

启用 Vim 模式:

/vim

Vim 常用快捷键:

4.5 Slash Commands(自定义命令)

什么是 Slash Commands?

Slash Commands 是将高频工作流封装成可复用的斜杠命令,将复杂的”人机对话”变成简单的”命令行指令”。

来自 Claude Code 创始人的实战经验: 为了避免重复输入相同的 Prompt,将高频工作流封装成了 Slash Commands。

创建自定义命令

方式一:通过 /commands 命令 — 选择 “Create new command”。

方式二:手动创建 — 在 .claude/commands/ 目录创建 Markdown 文件,如 commit-push-pr.md、daily-standup.md、deploy-staging.md。

示例 1:自动提交并创建 PR

你是一个发布助手。请执行以下步骤:

1. 检查 Git 状态
   !git status

2. 运行测试套件
   !npm test

3. 如果测试通过:
   - 添加所有更改
   - 生成符合 Conventional Commits 的提交消息
   - 推送到远程
   - 创建 Pull Request

4. 如果测试失败:
   - 分析失败原因
   - 提供修复建议

使用: 在对话中输入 /commit-push-pr。

示例 2:生成每日站会日报

请生成今日站会报告,包括:
1. 昨天完成了什么 !git log --since="yesterday" --oneline
2. 今天计划做什么 (读取 CLAUDE.md 中的当前任务)
3. 遇到的阻碍 (读取最近的 TODO 注释)
请以清晰的 Markdown 格式输出。

使用: /daily-standup

完整的部署工作流 可类似地在 deploy-production.md 中定义前置检查、构建、部署、验证、回滚准备、部署后检查等步骤,每步可含 !command 与说明。

价值: 一键执行复杂流程、减少人为错误、团队共享最佳实践、可签入 Git 版本控制。

4.6 Extended Thinking(扩展思考模式)

ultrathink 深度思考模式

当你需要设计复杂的缓存层或重构架构时,在提示词中加上 ultrathink。

# 标准模式
设计一个 Redis 缓存层

# ultrathink 模式
ultrathink: 设计一个高可用的 Redis 缓存层,考虑:
- 缓存穿透、缓存击穿、缓存雪崩
- 分布式锁
- 缓存更新策略
- 降级方案

效果:

• Claude 会分配高达 32k 的 Token 进行内部推理
• 虽然反应慢一点,但逻辑准确率大幅提升
• 适合架构设计、复杂重构等关键任务

Extended Thinking API

通过 API 调用时,开启 Extended Thinking 可以看到 Claude 的逐步推理过程(Thinking Blocks)。

价值: 透明化思考过程、便于调试复杂逻辑、理解 Claude 的决策路径、教学和学习工具。

五、实用技巧与快捷操作

了解了 Claude Code 的高级功能后，分享一些实用的技巧和快捷操作，可以更高效地使用这个工具。

5.1 基础操作技巧

项目初始化(/init)

# 自动生成 CLAUDE.md
/init

# 或手动指定
claude /init "这是一个 Node.js + React 项目"

快速引用上下文(@提及)

# 引用单个文件
@src/auth.ts

# 引用整个目录
@src/components/

# 引用多个文件
@src/auth.ts @src/user.ts @src/database.ts

# 引用 MCP 服务器
@mcp:github

# 模糊匹配
@auth  # 自动匹配 auth.ts, auth.controller.ts 等

即时执行 Bash 命令(!前缀)

# 查看状态
!git status

# 运行测试
!npm test

# 查看进程
!ps aux | grep node

# 组合使用
!git diff && echo "=== Changes Summary ==="

回退操作(双击 ESC)

ESC ESC

选项: 仅回退对话 / 仅回退代码 / 同时回退对话和代码。注意: 已执行的 Bash 命令无法回退。

5.2 效率提升技巧

反向搜索历史提示词(Ctrl+R)

Ctrl+R 开始搜索,再按循环匹配项,Enter 运行,Tab 编辑后运行。

提示词暂存(Ctrl+S)

Ctrl+S 暂存当前提示词,处理完其他事务后恢复暂存内容继续工作。类似 Git stash,但用于提示词。

智能提示补全(Prompt Suggestions)

Claude 能预测你接下来想问什么: 当看到灰色建议文字时,Tab 接受建议并编辑,Enter 直接运行建议。

会话管理高级技巧

Continue & Resume - 无缝续关

claude --continue   # 瞬间恢复上一次对话
claude --resume     # 显示历史会话列表供选择
# 上下文完美保留,工作流永不丢失

Named Sessions - 会话命名

/rename api-migration   # 给当前会话命名
/resume api-migration   # 按名称恢复会话
# 为不同任务创建独立会话

Claude Code Remote - 跨设备传送

claude --teleport session_id   # 把云端会话"拉"到本地
# 在终端和网页间同步上下文,甚至用手机版 Claude App 查看进度

自定义状态栏(/statusline)、可视化上下文(/context)、使用统计(/stats、/usage)

可显示 Git 分支、当前模型、Token 用量、上下文占比、任务进度等; /context 查看 token 与各文件占用; /stats、/usage 查看使用习惯与费率。

5.3 文件夹管理技巧

为每个任务创建独立文件夹; 支持拖拽单个文件、整个文件夹或多个文件到 Claude Code,再描述任务。

5.4 粘贴技巧

注意: CC 中不能用 Ctrl+V 粘贴文本、不能用 Ctrl+A 全选; 图片必须在打开状态复制,预览状态无法粘贴。

5.5 常用斜杠命令速查

六、最佳实践

继续。提供并建立一些最佳实践以提升团队协作和开发效率。

6.1 项目组织最佳实践

目录结构规范

project/
├── .claude/                    # Claude Code 配置
│   ├── settings.json           # 项目级设置
│   ├── agents.json             # 子代理配置
│   ├── rules/                  # 模块化规则
│   │   ├── auth.md
│   │   ├── database.md
│   │   └── api.md
│   └── mcp.json                # MCP 配置
├── src/                        # 源代码
├── tests/                      # 测试代码
├── docs/                       # 文档
├── CLAUDE.md                   # 项目主配置
└── README.md                   # 项目说明

CLAUDE.md 层级配置

优先级: 用户级 home/.claude/CLAUDE.md → 项目级 CLAUDE.md → 模块级 src/.claude/CLAUDE.md → 特定规则 .claude/rules → 合并为最终配置。

6.2 工作流最佳实践

探索-规划-编码-提交工作流

这是一个完整的开发工作流程,需要配合特定的 Skills 和 MCP 使用。

前置准备 - 安装必要工具:

# 1. 安装代码分析 MCP(可选,用于深度分析)
claude mcp add github npx -y @modelcontextprotocol/server-github

# 2. 安装 commit skill(用于生成规范的 commit 消息)
npx skills-installer install @anthropics/claude-code/commit --client claude-code

# 3. 安装 Chrome DevTools MCP(用于浏览器测试,可选)
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest

第 1 步:探索阶段 - 理解项目

# 启动 Claude Code
claude

# 探索项目架构
请帮我分析这个项目的架构,重点关注:
1. 整体项目结构
2. 认证模块的实现
3. 依赖关系
4. 技术栈

# 使用 @ 引用特定目录
@src/

# 如果有 GitHub 仓库,使用 GitHub MCP
请使用 github MCP 查看最近的 commit 历史和 issue

第 2 步:规划阶段 - 使用 Plan 模式

# 进入 Plan 模式(按两次 Shift+Tab)
Shift+Tab, Shift+Tab

# 或使用命令
/plan

# 明确任务需求
我需要添加 OAuth2.0 认证支持,请规划实现方案,包括:
1. 需要创建哪些新文件
2. 需要修改哪些现有文件
3. 需要安装哪些依赖
4. 实现步骤顺序
5. 潜在的风险点

# Claude 会生成详细计划,等待你的确认
# 确认后开始实施
yes

第 3 步:编码阶段 - 实施计划

# 让 Claude 按照计划实施
按照上面的计划开始实施

# 如果遇到问题,可以要求暂停
暂停,让我先检查一下这一步

# 继续实施
继续下一步

# 运行测试
!npm test

# 修复失败的测试
测试失败了,请帮我修复

第 4 步:提交阶段 - 使用 commit skill

# 使用 commit skill 生成规范的 commit 消息
使用 commit skill 为这些更改创建一个规范的 commit 消息

# 或手动指导 commit
请帮我创建 git commit,包含这些更改
commit 消息格式: feat(auth): 添加 OAuth2.0 认证支持

测试驱动开发(TDD)工作流

前置准备: 安装 test-writer skill 或配置 test-writer 子代理。

TDD 工作流程: 第 1 步先写测试(使用 test-writer 为用户登录等功能编写测试); 第 2 步运行测试(预期失败); 第 3 步实现最小可行代码使测试通过; 第 4 步重构; 第 5 步重复循环。

代码审查工作流

前置准备: 使用 /agents 创建或手动配置 code-reviewer、security-reviewer、performance-reviewer 等子代理(只读权限)。

使用方式: 使用 code-reviewer agent 审查指定文件的代码质量、安全、性能; 使用 security-reviewer 审查安全问题; 使用 performance-reviewer 审查性能; 综合三个 agent 的审查结果生成报告(严重程度、修复建议、优先级),按优先级修复后重新审查。

6.3 团队协作最佳实践

共享 CLAUDE.md

在项目根目录创建 CLAUDE.md,团队共同维护、定期更新、版本控制。示例: 团队约定(代码审查至少 1 人 approve、所有 PR 通过 CI、文档与代码同步)、分工信息、沟通渠道(Slack、JIRA 等)。

GitHub 集成

安装 GitHub App: /install-github-app

使用 PR 评论: 在 PR 中 @.claude 请审查这个 PR 的代码变更; 自动添加问题到 CLAUDE.md 可用 /pr-comments。

6.4 性能优化最佳实践

极致的并行处理(Parallelism)

来自 Claude Code 创始人 Boris Cherny 的核心理念: 不要让 AI 等你,也不要让你等 AI。

• 终端里的”多线程”: 同时运行多个 Claude 实例,配置系统通知,当某个 Claude 完成任务需要输入时弹窗提醒。在 ~/.claude/settings.json 中配置 notifications.enabled、notifications.sound、notifications.position。
• 本地与云端: 本地终端多实例 + 网页端多会话,利用 & 将任务转到网页端,用 claude --teleport session_id 拉回本地。
• 跨设备同步: 办公室终端+网页、休息时手机 App 查看、回家后 teleport 继续,工作流不中断。

效果对比:

上下文管理

长对话定期 /compact "保留以下要点: ..."; 新任务先 /clear; 用 /context 监控; 定期 /export 备份。

Token 优化

模型选择策略

创始人见解: 只用最强的模型 Opus 4.5 + Thinking。理由: 不需要频繁纠正、工具使用能力更强、一次做对,从总耗时看聪明模型反而更快。

国外模型: 快速查询/格式化 Haiku 4.5; 日常开发 Sonnet 4.5; 架构设计/复杂重构 Opus 4.5 + Thinking。

国内模型建议:

模型切换: /model 选择; 或临时 export ANTHROPIC_MODEL=kimi-k2 后启动; 或建 alias 如 alias cc-glm='ANTHROPIC_MODEL=GLM-4.7 claude'。

混合使用: 日常用国产模型,复杂任务时临时切换到 Opus 4.5,完成后切回。

6.5 安全最佳实践

Sandbox 配置

{
  "permissions": {
    "allow": {
      "bash": ["npm run *", "git *"],
      "write": ["src/**/*", "tests/**/*"],
      "read": ["**/*.ts", "**/*.js", "**/*.json"]
    },
    "deny": {
      "bash": ["rm -rf *", "format *", "shutdown"],
      "write": ["node_modules/**/*", ".git/**/*", "/etc/*", "/usr/*"]
    }
  }
}

Hooks 安全检查

在 ~/.claude/hooks/security-check.sh 等脚本中检查敏感操作: 若为 Bash 工具则读取命令,与危险命令黑名单(如 rm -rf、format、shutdown、reboot、chmod 000)匹配,匹配则输出拦截信息并 exit 1。

敏感信息保护

在 CLAUDE.md 或团队规范中明确: 禁止在代码中硬编码密钥、禁止在 CLAUDE.md 中记录密码、禁止在 Git 提交中包含凭证; 推荐使用环境变量、.env(不提交)、密钥管理服务、.gitignore 排除敏感文件。

6.6 验证闭环(Feedback Loop)

来自 Claude Code 创始人的最重要的一条技巧: 永远给 Claude 一种验证自己工作的方法。

核心原理

如果 Claude 能看到自己代码的运行结果(报错信息、测试通过与否),它的代码质量会提升 2-3 倍。

实践方法

1. 简单任务: 编写代码后让 Claude 运行测试 !npm test,根据结果修复,直到通过。
2. 复杂 UI: 使用 Claude Chrome 扩展或浏览器自动化: 打开页面、输入、点击、检查跳转与控制台,直到体验”感觉对劲”。
3. 端到端: 使用 verify-app agent 验证注册、登录、权限、数据持久化等,运行 !npm run test:e2e,发现问题则分析根因、修复、重新验证。

效果对比

最佳实践建议

✅ 推荐: 总是让 Claude 验证自己的工作,如「请实现功能 X,然后: 1. 运行测试验证 2. 检查代码格式 3. 验证边界情况 4. 确认无回归问题」。

❌ 避免: 不要让 Claude”盲写”,实现功能后没有验证步骤。

七、实战案例

简单几个案例看看如何运用到实际工作中。

7.1 案例1:批量文件重命名

需求: 将文件夹中所有文件名改为规范的英文名称。

实现: 拖拽文件夹到 Claude Code,说「请将文件夹中的所有文件名改成规范的英文名称,只改名字不改序号」。Claude Code 会自动: 读取文件夹内容、分析文件名、批量重命名、报告结果。

7.2 案例2:自动化数据抓取

需求: 抓取公众号多页文章数据并导出 Excel。

实现: 使用 Chrome DevTools MCP。用 Chrome 打开公众号链接,然后通过 chrome devtools mcp 完成: 获取第 1、2、3 页每篇文章的详细数据(标题、阅读量、点赞量、发布时间等),保存到 Excel 表格中。Claude Code 会自动: 启动 Chrome、导航到页面、翻页抓取数据、生成 Excel 报告。

效果对比: 人工约 30 分钟、准确率约 90%; Claude Code + MCP 约 5 分钟、准确率约 99%。

7.3 案例3:代码质量审查

需求: 审查 PR 的代码变更。

实现: 使用 code-reviewer subagent。在对话中说「使用 code-reviewer agent 审查这个 PR: 代码质量、安全漏洞、性能问题、最佳实践」并 @src/ @tests/。Claude Code 会自动: 读取相关文件、应用审查标准、生成详细报告、提供修复建议。

7.4 案例4:自动化测试生成

需求: 为新功能编写测试。

实现: 使用 test-writer subagent。说「使用 test-writer agent 为用户认证功能编写测试: 单元测试、集成测试、E2E 测试、边界情况测试」并 @ 相关源码文件。Claude Code 会自动: 分析代码逻辑、识别测试场景、编写测试用例、运行测试验证。

7.5 案例5:CI /CD 集成

需求: 在 PR 创建时自动审查代码。

实现: 在 .github/workflows/claude-review.yml 中配置: checkout、Setup Node.js、Install Claude Code、Run Code Review(将 git diff origin/main...HEAD | claude -p "审查这个 PR 的代码变更" 输出到 review.txt)、用 actions/github-script 将 review 内容作为 PR 评论发布。

八、常见问题与解决方案

在使用 Claude Code 的过程中,可能会遇到一些常见问题。本节收集最常见的问题及解决方案,帮助快速排除故障。

8.1 安装问题

Q1: npm install 失败

问题: 出现 npm ERR! code EACCES、npm ERR! syscall access 等。

解决方案:

# 方式 1: 使用 sudo (macOS/Linux)
sudo npm install -g @anthropic-ai/claude-code

# 方式 2: 修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code

# 方式 3: 使用 nvm (推荐)
nvm install --lts
npm install -g @anthropic-ai/claude-code

Q2: claude 命令未找到

问题: bash: claude: command not found

解决方案:

# 检查 npm 全局路径
npm config get prefix

# 添加到 PATH
export PATH=$(npm config get prefix)/bin:$PATH

# 永久配置
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

8.2 配置问题

Q3: 模型配置不生效

问题: 配置后仍显示默认模型。

解决方案: 验证环境变量(echo $ANTHROPIC_BASE_URL、$ANTHROPIC_AUTH_TOKEN、$ANTHROPIC_MODEL); 重新启动终端(配置后必须重启终端才能生效); 使用 claude /status 检查; 或临时在会话内 /model 选择自定义模型。

Q4: MCP 服务器无法连接

问题: Error: MCP server 'chrome-devtools' failed to start 等。

解决方案: 在 Claude Code 中 /mcp 检查状态; 命令行 claude mcp test chrome-devtools; 重装 MCP; 检查网络与 npx chrome-devtools-mcp@latest --version; 查看 claude /doctor 日志。

8.3 使用问题

Q5: 上下文超出限制

问题: Context exceeded: Request too large。

解决方案: 用 /context 查看使用; 用 /compact "保留项目背景和当前任务" 或 /clear; 减少文件引用(不要用 @src/ 引用整个目录,改用精确引用); 用 Subagents 分担上下文。

Q6: 代码生成质量差

问题: 生成的代码不符合项目规范。

解决方案: 完善 CLAUDE.md 中的代码规范; 使用 Plan 模式让 Claude 先理解项目再编写; 提供符合规范的示例文件并说「请参照这个风格编写」; 明确要求(TypeScript 严格模式、命名规范、错误处理、注释等)。

8.4 性能问题

Q7: 响应速度慢

解决方案: 检查网络(如 ping api.anthropic.com); 切换更快的模型(如 Haiku 4.5 或国产模型); 优化提示词; 减少上下文(若接近 100% 则 /compact); 若有本地模型可设置 ANTHROPIC_BASE_URL。

Q8: Token 消耗过快

解决方案: 用 /cost 监控; 定期 /compact "保留关键信息"; 新任务先 /clear; 使用更便宜的模型; 优化工作流、一次性明确需求避免反复修改。

8.5 调试技巧

启用调试模式: 设置 CLAUDE_DEBUG=true、CLAUDE_LOG_LEVEL=debug 后启动 Claude Code,查看 tail -f ~/.claude/logs/claude.log。

使用 /doctor 诊断: 在 Claude Code 中输入 /doctor,可检查安装版本、配置文件、API 连接、MCP 服务器、权限设置、环境变量。

九、高级集成与扩展

Claude Code 的真正强大之处在于可扩展性。通过 LSP 集成和 Agent SDK,甚至可以构建自己的智能开发环境。

9.1 LSP 集成

什么是 LSP?

LSP (Language Server Protocol) 是语言服务器协议。通过集成 LSP,Claude Code 的代码理解能力达到 IDE 级别。

LSP 的强大能力

Claude Code 可以: 看到实时报错和警告、跳转到定义、查看类型信息、理解符号引用、分析代码结构。

效果对比:

实战: 问「这个函数的返回类型是什么」「这个函数在哪里被调用」「这里有个类型错误怎么修复」时,Claude 会使用 LSP 查看准确类型定义、查找引用、根据实时报错给出建议。

配置 LSP

Claude Code 会自动检测项目中的 LSP 服务器(TypeScript 用 tsserver、Python 用 pylsp、Go 用 gopls 等)。也可在 ~/.claude/settings.json 的 lsp 下手动配置各语言的 command、args。

9.2 Claude Agent SDK

什么是 Agent SDK?

Claude Agent SDK 将 Claude Code 的核心能力(Agent Loop、工具管理、上下文管理)作为 SDK 开放。可以用几十行代码构建一个像 Claude Code 一样强大的自定义智能体。

核心能力示例

创建 Agent、注册 Tool(如 readFile、writeFile)、设置 Context(maxSize: 200_000、compression: ‘auto’),然后 agent.run('创建一个用户认证系统')。自动处理: 思考、工具调用、结果观察、迭代优化。

使用场景

附录

A. 快速参考卡

核心命令: claude 启动; claude -p "prompt" Headless; claude --version 查看版本。斜杠: /clear、/compact、/context、/cost、/model、/mcp、/skills、/hooks、/agents、/status、/doctor。快捷键: Ctrl+R 搜索历史、Ctrl+S 暂存、Ctrl+C 中止、Shift+Tab×2 Plan、ESC×2 回退、Alt+V 粘贴图片。文件: @file.ts、@src/、!command。

B. 配置文件清单

C. 推荐资源

• Claude Code 官网: https://code.claude.com
• 文档: https://code.claude.com/docs
• GitHub: https://github.com/anthropics/claude-code
• Skills 库: https://github.com/anthropics/skills
• MCP 服务器: https://github.com/modelcontextprotocol

总结

Claude Code 是强大的系统级 AI Agent,用好能显著提升效率。

核心能力清单

• ✅ Skills: 预封装的工作流,快速复用专业能力
• ✅ Hooks: 事件驱动的自动化,打造个性化工作流
• ✅ Plugins: 完整解决方案,一键安装多功能套件
• ✅ MCP Servers: 外部服务集成,无限扩展能力边界
• ✅ Subagents: 并行处理复杂任务,提升团队协作效率
• ✅ CLAUDE.md: 项目记忆系统,让 AI 理解项目,并支持自我进化
• ✅ Plan 模式: 先规划后执行,减少返工提高质量(90% 时间都在用)
• ✅ Slash Commands: 复杂工作流一键执行,团队共享最佳实践
• ✅ Extended Thinking: ultrathink 深度思考模式,解决复杂问题
• ✅ Sandbox 模式: 安全防护机制,保护工作环境
• ✅ Headless 模式: CI/CD 集成,实现自动化工作流
• ✅ LSP 集成: IDE 级代码理解,实时错误检测
• ✅ Agent SDK: 构建自定义智能体,几十行代码创造强大工具

顶级开发者的秘诀

来自 Claude Code 创始人和 Anthropic 团队的实战经验:

1. 并行处理是效率倍增的关键 — 同时运行多终端实例与网页会话,利用系统通知与多设备协作,效率提升可达 1900%+。
2. AI 进化机制让工具越用越聪明 — 在 PR 评论中直接 @claude 反馈,自动将教训写入 CLAUDE.md,整个团队的 AI 助手持续进化。
3. 验证闭环是质量保证的基石 — 永远给 Claude 验证自己工作的方法,代码质量提升 2-3 倍,返工率降低到 5%。
4. 选择合适的工具 — 简单任务用 Haiku 或国产模型,日常开发用 Sonnet,复杂任务用 Opus + Thinking(创始人首选); 聪明的大模型比”快但笨”的小模型更快。
5. 先规划后执行 — 90% 的时间使用 Plan 模式,你是架构师,Claude 是执行者,一次做对比反复修改更省时间。

设计哲学

通过 Plan Mode 尊重人的决策权; 通过 Hooks 和 Sandbox 给人控制权; 通过 Subagents 和 Automation 分担执行; 通过 LSP 和 Agent SDK 提供扩展可能。用得最好的开发者,懂得何时使用计划模式、何时开启深度思考、如何设置安全边界。

正如 Ado Kukic 所说:“用得最好的开发者,不是那些把所有事情都丢给 AI 的人,而是那些懂得何时使用计划模式、何时开启深度思考、如何设置安全边界的人。”

Claude Code 不仅仅是一个工具,它是一个可编程、可扩展、可进化的智能开发环境。你的创造力决定了它的上限。

全文整理自博客园《Claude Code 完全指南：使用方式、技巧与最佳实践》,完整版请阅读原文: https://www.cnblogs.com/knqiufan/p/19449849。