Claude Code 使用最佳实践与技巧

在 AI 辅助编程工具快速发展的今天，开发者面临一个共同的挑战：如何从”能用”到”用好”？Claude Code 作为 Anthropic 推出的终端优先的自主 AI 编程代理，凭借其强大的推理能力和 200k+ token 的上下文窗口，已经成为处理复杂代码任务的利器。但工具再强大，也需要正确的使用方式才能发挥最大价值。

本文将系统性地介绍 Claude Code 的最佳实践与高级技巧，帮助你从基础使用提升到专家级别，真正释放 AI 辅助编程的生产力。

Claude Code 核心理解

什么是 Claude Code

Claude Code 是 Anthropic 开发的自主编程代理（Agentic Coding Tool），而非传统的代码补全工具。它的核心特点包括：

终端优先：通过 claude 命令在终端中交互，也支持 Web、桌面应用、IDE 插件等多种形式
自主执行：能够独立规划任务、执行多文件操作、运行命令、验证结果
大上下文：支持 200k+ token 的上下文窗口，适合处理大型代码库
多模态能力：不仅限于编程，还能处理文档编写、构建运行、文件搜索、主题研究等任何可从命令行执行的任务

Claude Code vs Cursor：选择指南

理解两者的差异有助于选择合适的工具：

维度	Claude Code	Cursor
核心定位	终端自主代理	AI 增强 IDE
工作方式	探索式、并行执行	聚焦式、精准控制
最佳场景	复杂重构、架构决策、多文件任务	快速原型、MVP 开发、实时补全
上下文窗口	200k+ tokens	相对较小
学习曲线	需要理解 Agent 工作方式	熟悉 VS Code 即可上手
定价	Pro 订阅 $17-20/月，无免费版	有免费 Hobby 计划

选择建议：

需要处理大型代码库的复杂重构 → Claude Code
快速迭代和原型开发 → Cursor
深度代码审查和理解 → Cursor
并行处理多个独立任务 → Claude Code

两者并非互斥，很多团队同时使用两者，根据任务特点灵活选择。

环境配置与初始化

快速安装

# macOS - Homebrew
brew install anthropics/claude/claude

# macOS/Linux - 原生安装
curl -fsSL https://code.claude.com/install.sh | sh

# Windows - WinGet
winget install Anthropic.Claude

安装后运行 claude 命令即可开始使用，首次运行需要登录 Claude 账号（需要 Pro、Max、Teams 或 Enterprise 订阅）。

创建 CLAUDE.md：项目上下文的关键

CLAUDE.md 是 Claude Code 最重要的配置文件，它为 Claude 提供持久化的项目上下文。这个文件应该放在项目根目录或父目录（适用于 monorepo）。

CLAUDE.md 应该包含什么

# CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

## Project Overview
[项目简介、技术栈、架构概述]

## Common Commands
```bash
# Development
npm run dev          # Start dev server
npm run test         # Run tests
npm run build        # Production build

Code Style Guidelines

Use TypeScript strict mode
Follow ESLint rules in .eslintrc.js
Prefer functional components with hooks
Write tests for all business logic

Testing Instructions

Unit tests: npm run test:unit
E2E tests: npm run test:e2e
Coverage threshold: 80%

Repository Etiquette

Create feature branches from main
Squash commits before merging
Update CHANGELOG.md for user-facing changes

Developer Environment Setup

Node.js 18+
PostgreSQL 14+
Redis for caching


#### CLAUDE.md 最佳实践

1. **保持更新**：随着项目演进及时更新 CLAUDE.md
2. **团队共识**：CLAUDE.md 应该反映团队的开发规范，纳入代码审查流程
3. **分层配置**：Monorepo 可以在根目录放通用配置，子项目放特定配置
4. **避免过度详细**：聚焦高频操作和容易出错的地方，不要写成完整文档

### 环境优化配置

#### 跳过权限提示（谨慎使用）

```bash
# 开发环境快速迭代时可以跳过权限确认
claude --dangerously-skip-permissions

# 或设置别名
alias cc='claude --dangerously-skip-permissions'

⚠️ 警告：此选项会让 Claude 直接执行文件修改、命令运行等操作，仅在信任的项目中使用。

企业代理配置

# 设置 HTTP 代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 或在 Claude 配置中设置
claude config set proxy http://proxy.company.com:8080

核心工作流程与最佳实践

黄金法则：探索 → 规划 → 编码

不要直接让 Claude 开始编码，这是最常见的误区。正确的流程是：

1. 探索阶段（Exploration）

# 让 Claude 先理解代码库
claude "分析这个项目的认证流程实现"

# 探索特定功能
claude "找出所有使用 Redis 缓存的地方"

# 理解依赖关系
claude "这个 UserService 被哪些模块依赖？"

2. 规划阶段（Planning）

# 让 Claude 制定计划
claude "我需要添加用户登录限流功能，请先制定一个实现计划"

# 审查计划并调整
# Claude 会列出步骤、涉及的文件、潜在风险
# 此时你可以提供反馈："不要修改 auth.ts，在 middleware 层实现"

为什么规划重要？

让你有机会在代码修改前调整方向
Claude 会考虑更全面的影响范围
避免返工和错误修改

3. 编码阶段（Coding）

# 执行计划
claude "按照刚才的计划实现登录限流功能"

# 增量验证
claude "实现第一步后，写个测试验证是否工作"

使用 Plan Mode 进行安全分析

Plan Mode 是一个只读模式，适合在不修改代码的情况下进行深度分析：

# 进入 Plan Mode
claude plan "分析这个重构方案的影响范围"

# Plan Mode 适用场景
- 复杂重构前的影响分析
- 代码审查和安全检查
- 架构决策评估
- 性能瓶颈诊断

Plan Mode 会给出详细的分析报告，但不会修改任何文件，让你可以安全地探索各种可能性。

频繁使用 `/clear` 保持会话清晰

长对话会让 AI 代理变得不可预测，这是所有 LLM 的共性问题。最佳实践：

# 完成一个任务后立即清空
/clear

# 切换到新任务前清空
/clear

# 感觉 Claude 理解偏离时清空
/clear

何时应该 /clear？

✅ 完成一个独立功能
✅ 开始新的不相关任务
✅ Claude 的回复开始偏离预期
✅ 上下文已经很长（>10 轮对话）

何时不应该 /clear？

❌ 正在进行多步骤的复杂任务中途
❌ 需要 Claude 记住之前的决策和上下文
❌ 正在调试一个问题的过程中

提供丰富的上下文

好的提示词 = 清晰的意图 + 丰富的上下文

差的提示词示例

# ❌ 太模糊
claude "优化这个函数"

# ❌ 缺少上下文
claude "修复这个 bug"

# ❌ 没有验证方式
claude "添加缓存功能"

好的提示词示例

# ✅ 清晰的意图 + 具体指标
claude "优化 src/utils/parser.ts 中的 parseUserData 函数，
目标是将处理 10000 条记录的时间从 5 秒降低到 1 秒以内。
当前瓶颈是 JSON.parse 调用过于频繁。"

# ✅ 包含错误信息和环境
claude "修复登录失败的问题。错误信息：
Error: Invalid token signature
  at jwt.verify (auth.ts:45)
环境：Node.js 18, JWT 库版本 9.0.0
复现步骤：使用过期 token 调用 /api/user 接口"

# ✅ 明确验证方式
claude "为 UserService 添加 Redis 缓存。
要求：
1. 缓存用户基本信息，TTL 5分钟
2. 提供缓存失效机制
3. 添加单元测试验证缓存命中率
4. 实现后运行 npm test 验证所有测试通过"

让 Claude 验证自己的工作

不要假设 Claude 的输出是正确的，而是给它验证的方式：

# 要求运行测试
claude "实现用户注册功能，完成后运行 npm test 验证"

# 要求检查 linter
claude "重构这个组件，完成后运行 eslint 检查是否有错误"

# 要求构建验证
claude "修改 Webpack 配置，完成后运行 npm run build 确保构建成功"

# 要求手动验证
claude "添加新的 API 端点，完成后用 curl 测试并展示响应"

Claude 会自动执行这些验证命令，并根据结果调整代码，直到验证通过。

高级技巧与模式

使用 Subagents 进行任务委派

Subagent 是 Claude Code 的杀手级特性，允许你将复杂任务分解为并行的子任务：

# 主 Claude 会话
claude "我需要重构整个认证模块，包括：
1. 将 JWT 验证逻辑从 controller 移到 middleware
2. 添加 refresh token 机制
3. 更新所有相关的单元测试
4. 更新 API 文档

请创建 subagents 并行处理这些任务"

Claude 会自动：

创建多个 subagent
为每个 subagent 分配明确的任务
监控各个 subagent 的进度
整合所有结果

Subagent 适用场景：

✅ 多个独立模块的修改
✅ 大规模重构
✅ 并行的测试编写
✅ 多文件的格式化和清理

Subagent 不适用场景：

❌ 有强依赖关系的任务（必须按顺序执行）
❌ 需要频繁交互的任务
❌ 简单的单文件修改

使用 Git Worktrees 进行并行开发

Git Worktrees 允许你在同一个仓库的不同分支上同时工作，结合 Claude Code 可以实现真正的并行开发：

# 创建 worktree 用于新特性
git worktree add ../myproject-feature-auth feature/auth

# 在新 worktree 中启动 Claude
cd ../myproject-feature-auth
claude "实现 OAuth2 登录功能"

# 同时在主 worktree 中处理其他任务
cd ../myproject
claude "修复用户头像上传的 bug"

Worktrees 的优势：

无需频繁切换分支
可以同时运行多个 Claude 会话
避免未提交代码的冲突
方便对比不同实现方案

使用 Extended Thinking Mode

对于特别复杂的问题，可以启用扩展思考模式，让 Claude 进行更深入的分析：

1
2
3

# 启用扩展思考
claude --extended-thinking "分析这个分布式事务的死锁问题，
考虑所有可能的竞态条件和解决方案"

Extended Thinking Mode 会：

花费更多时间分析问题
考虑更多边缘情况
提供更详细的推理过程
适合架构级别的复杂决策

何时使用：

复杂的并发问题
性能优化决策
架构重构方案
安全漏洞分析

Checkpointing：时光机功能

Checkpointing 允许你保存会话状态并随时回退：

# 创建检查点
/checkpoint save "完成用户认证基础功能"

# 继续开发...
claude "添加多因素认证"

# 如果不满意，回退到检查点
/checkpoint restore "完成用户认证基础功能"

# 查看所有检查点
/checkpoint list

Checkpointing 最佳实践：

在每个重要里程碑创建检查点
使用描述性的检查点名称
尝试激进方案前先创建检查点
定期清理不再需要的检查点

Model Context Protocol (MCP) 集成

什么是 MCP

MCP（Model Context Protocol）是 AI 应用的”USB-C 接口”，提供标准化的方式让 Claude Code 连接外部系统：

数据源：本地文件、数据库、API
工具：搜索引擎、计算器、代码分析工具
工作流：GitHub、Sentry、Jira、Slack

配置 MCP 服务器

MCP 服务器通过 JSON 配置文件连接：

// ~/.config/claude/mcp_servers.json
{
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "your_token_here"
    }
  },
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://localhost/mydb"
    }
  },
  "figma": {
    "type": "http",
    "url": "https://mcp.figma.com",
    "headers": {
      "Authorization": "Bearer your_figma_token"
    }
  }
}

MCP 实际应用场景

场景 1：从 GitHub Issue 生成代码

1 2	claude "读取 GitHub Issue #123，根据需求实现对应功能" # Claude 会通过 MCP GitHub 服务器获取 Issue 内容，理解需求后实现

场景 2：数据库驱动开发

1
2
3

claude "连接到生产数据库（只读），分析 users 表的查询性能问题，
找出慢查询并优化索引"
# Claude 通过 MCP Postgres 服务器执行 EXPLAIN ANALYZE

场景 3：从设计稿生成代码

1 2	claude "从 Figma 设计稿 'User Dashboard' 生成 React 组件" # Claude 通过 MCP Figma 服务器获取设计规范，生成匹配的代码

常用 MCP 服务器

MCP 服务器	用途	安装
`@modelcontextprotocol/server-github`	GitHub 集成	`npx -y @modelcontextprotocol/server-github`
`@modelcontextprotocol/server-postgres`	PostgreSQL 数据库	`npx -y @modelcontextprotocol/server-postgres`
`@modelcontextprotocol/server-sentry`	错误追踪	`npx -y @modelcontextprotocol/server-sentry`
`@modelcontextprotocol/server-filesystem`	文件系统访问	`npx -y @modelcontextprotocol/server-filesystem`

完整的 MCP 服务器列表：https://github.com/modelcontextprotocol/servers

自定义与扩展

Hooks：自动化工作流

Hooks 是在 Claude Code 生命周期特定点执行的 Shell 命令，提供确定性的自动化控制：

创建 Hooks 配置

// .claude/hooks.json
{
  "pre-edit": {
    "command": "npm run lint",
    "description": "Run linter before editing"
  },
  "post-edit": {
    "command": "npm run format",
    "description": "Auto-format after editing"
  },
  "pre-commit": {
    "command": "npm test",
    "description": "Run tests before commit"
  },
  "on-error": {
    "command": "notify-send 'Claude Code Error' '$ERROR_MESSAGE'",
    "description": "Desktop notification on error"
  }
}

Hooks 应用场景

自动格式化：每次编辑后运行 Prettier
自动测试：提交前运行测试套件
通知集成：任务完成后发送 Slack 通知
日志记录：记录所有 Claude 操作到审计日志
自定义权限：根据文件路径实现细粒度权限控制

Skills：扩展 Claude 的能力

Skills 是 Claude Code 最强大的扩展机制之一，它允许你创建可重用的指令集，让 Claude 自动获得特定领域的知识和能力。

什么是 Skills

Skills 是遵循 Agent Skills 开放标准的扩展，通过创建 SKILL.md 文件来定义。Claude 会：

自动发现：在相关场景下自动加载 Skills
手动调用：通过 /skill-name 命令直接调用
跨工具兼容：Skills 标准可在多个 AI 工具中使用

创建第一个 Skill

让我们创建一个代码解释 Skill，教会 Claude 用可视化图表和类比来解释代码：

# 1. 创建 Skill 目录
mkdir -p ~/.claude/skills/explain-code

# 2. 创建 SKILL.md
cat > ~/.claude/skills/explain-code/SKILL.md << 'EOF'
---
name: explain-code
description: 用可视化图表和类比解释代码。当用户询问"这段代码如何工作"或需要理解代码逻辑时使用。
---

# 代码解释 Skill

当解释代码时，始终包含以下内容：

## 1. 从类比开始
将代码与日常生活中的事物进行比较，帮助理解抽象概念。

## 2. 绘制图表
使用 ASCII 艺术展示流程、结构或关系：

┌─────────┐ ┌─────────┐ ┌─────────┐
│ 输入数据 │ ──> │ 处理逻辑 │ ──> │ 输出结果 │
└─────────┘ └─────────┘ └─────────┘


## 3. 逐步讲解
分步骤解释代码执行过程，标注关键决策点。

## 4. 指出常见陷阱
说明容易出错的地方或常见误解。

保持解释对话化，对于复杂概念使用多个类比。
EOF

Skill 存放位置

Skills 可以放在不同位置，影响其作用范围：

位置	路径	适用范围
企业级	通过管理配置部署	组织内所有用户
个人级	`~/.claude/skills/<skill-name>/SKILL.md`	你的所有项目
项目级	`.claude/skills/<skill-name>/SKILL.md`	当前项目
插件级	`<plugin>/skills/<skill-name>/SKILL.md`	插件启用的地方

优先级：企业级 > 个人级 > 项目级。插件 Skills 使用 plugin-name:skill-name 命名空间，不会冲突。

Skill 结构最佳实践

基础结构：

---
name: skill-name
description: 简洁描述 Skill 的功能和使用场景
---

# Skill 主体内容

[具体的指令和指导]

高级结构（支持文件）：

my-skill/
├── SKILL.md              # 主指令（必需）
├── reference.md          # 详细参考文档（按需加载）
├── examples.md           # 使用示例（按需加载）
└── scripts/
    ├── validate.sh       # 验证脚本（可执行）
    └── helper.py         # 辅助脚本

渐进式披露模式：

SKILL.md 作为概览，指向详细资料：

# PDF 处理 Skill

## 快速开始
使用 pdfplumber 提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

高级功能

表单填充：详见 FORMS.md
API 参考：详见 REFERENCE.md
示例代码：详见 EXAMPLES.md


Claude 只在需要时才加载这些额外文件，节省 token。

#### Skill 配置选项

通过 frontmatter 控制 Skill 行为：

```yaml
---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true  # 仅允许手动调用
allowed-tools: Bash(*)          # 限制可用工具
context: fork                   # 在独立上下文中运行
agent: Explore                  # 指定使用的 agent 类型
---

关键配置项：

配置项	说明	使用场景
`disable-model-invocation: true`	禁止 Claude 自动调用	有副作用的操作（部署、提交）
`user-invocable: false`	从菜单隐藏，仅 Claude 可用	背景知识类 Skills
`allowed-tools`	限制可用工具	只读模式、安全限制
`context: fork`	在子 agent 中运行	隔离执行、并行任务

实用 Skill 示例

示例 1：Git Commit 消息生成器

---
name: commit-message
description: 分析 git diff 生成规范的 commit 消息。当用户需要提交代码或询问如何写 commit 消息时使用。
---

# Commit 消息生成器

## 格式规范
遵循 Conventional Commits 标准：

():


## Type 类型
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `style`: 代码格式（不影响功能）
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建/工具配置

## 示例

**输入**：添加用户认证功能
**输出**：

feat(auth): implement JWT-based authentication

Add login endpoint with email/password validation
Implement token generation and verification middleware
Add refresh token mechanism for session management

Closes #123


## 生成步骤
1. 运行 `git diff --staged` 查看变更
2. 分析变更类型和影响范围
3. 生成简洁但完整的消息
4. 包含相关 issue 编号（如有）

示例 2：代码审查 Skill

---
name: code-review
description: 系统化审查代码变更，检查质量、安全和最佳实践。用于 PR 审查或代码质量检查。
disable-model-invocation: true
---

# 代码审查 Skill

## 审查清单

### 1. 功能正确性
- [ ] 代码实现符合需求
- [ ] 边缘情况处理完善
- [ ] 错误处理适当

### 2. 代码质量
- [ ] 命名清晰有意义
- [ ] 函数职责单一
- [ ] 避免重复代码
- [ ] 注释必要且准确

### 3. 安全性
- [ ] 输入验证充分
- [ ] 无 SQL 注入风险
- [ ] 敏感数据加密
- [ ] 权限检查正确

### 4. 性能
- [ ] 无明显性能瓶颈
- [ ] 数据库查询优化
- [ ] 避免 N+1 查询

### 5. 测试
- [ ] 有对应单元测试
- [ ] 测试覆盖关键路径
- [ ] 测试用例有意义

## 审查流程
1. 阅读变更概述和相关 issue
2. 逐文件审查代码
3. 运行测试套件
4. 检查是否符合项目规范
5. 提供具体、可操作的反馈

示例 3：数据库查询优化 Skill

---
name: optimize-queries
description: 分析和优化数据库查询性能。当遇到慢查询或需要性能优化时使用。
allowed-tools: Bash(psql *), Read, Grep
---

# 数据库查询优化 Skill

## 诊断流程

### 1. 识别慢查询
```bash
# PostgreSQL 慢查询日志
grep "duration:" /var/log/postgresql/postgresql.log | sort -k3 -n | tail -20

2. 分析查询计划

1 2	EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'user@example.com';

3. 检查关键指标

Seq Scan：全表扫描，通常需要添加索引
Nested Loop：嵌套循环，数据量大时性能差
Cost：查询成本，越低越好

常见优化策略

添加索引

-- 单列索引
CREATE INDEX idx_users_email ON users(email);

-- 复合索引（注意顺序）
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at);

-- 部分索引（减少索引大小）
CREATE INDEX idx_active_users ON users(email) WHERE active = true;

查询重写

-- ❌ 避免：SELECT *
SELECT * FROM users;

-- ✅ 推荐：只选择需要的列
SELECT id, email, name FROM users;

-- ❌ 避免：子查询
SELECT * FROM orders WHERE user_id IN (SELECT id FROM users WHERE active = true);

-- ✅ 推荐：JOIN
SELECT o.* FROM orders o
INNER JOIN users u ON o.user_id = u.id
WHERE u.active = true;

使用缓存

# Redis 缓存热点数据
import redis
r = redis.Redis()

def get_user(user_id):
    # 先查缓存
    cached = r.get(f"user:{user_id}")
    if cached:
        return json.loads(cached)
    
    # 缓存未命中，查数据库
    user = db.query("SELECT * FROM users WHERE id = %s", user_id)
    r.setex(f"user:{user_id}", 300, json.dumps(user))  # 5分钟 TTL
    return user

验证优化效果

记录优化前的查询时间
应用优化方案
运行 EXPLAIN ANALYZE 对比
在生产环境监控性能指标


#### Skills 编写最佳实践

**1. 简洁至上**

Claude 已经很聪明，只添加它不知道的信息：

```markdown
# ❌ 过于啰嗦（150 tokens）
## 提取 PDF 文本
PDF（Portable Document Format）是一种常见的文件格式，包含文本、图像等内容。
要提取 PDF 文本，需要使用库。有很多库可用，但我们推荐 pdfplumber...

# ✅ 简洁明了（50 tokens）
## 提取 PDF 文本
使用 pdfplumber：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()


**2. 设置适当的自由度**

- **高自由度**（文本指令）：多种方法都有效时
- **中等自由度**（伪代码/带参数脚本）：有推荐模式但允许变化
- **低自由度**（具体脚本）：操作易错或需要严格一致性

**3. 使用工作流模式**

对于复杂任务，提供清晰的步骤和检查清单：

```markdown
## 部署工作流

复制此清单并跟踪进度：

部署进度：

步骤 1：运行测试套件
步骤 2：构建生产版本
步骤 3：备份当前版本
步骤 4：部署到生产环境
步骤 5：验证部署成功


**步骤 1：运行测试套件**
```bash
npm run test

所有测试必须通过才能继续。

步骤 2：构建生产版本
…


**4. 实现反馈循环**

关键操作要有验证步骤：

```markdown
## 文档编辑流程
1. 修改 `word/document.xml`
2. **立即验证**：`python scripts/validate.py`
3. 如果验证失败：
   - 仔细查看错误信息
   - 修复 XML 中的问题
   - 再次运行验证
4. **只有验证通过才能继续**
5. 重新打包：`python scripts/pack.py`

5. 提供实用脚本

预制脚本比让 Claude 生成更可靠：

## 实用脚本

**analyze_form.py**：从 PDF 提取表单字段
```bash
python scripts/analyze_form.py input.pdf > fields.json

validate.py：验证字段映射

1 2	python scripts/validate.py fields.json # 返回："OK" 或列出冲突


#### Skills 与其他功能的配合

**Skills + Subagents**：

```markdown
---
name: deep-research
description: 深度研究某个主题
context: fork
agent: Explore
---

研究 $ARGUMENTS：
1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 总结发现，包含具体文件引用

Skills + MCP：

---
name: github-issue-workflow
description: 从 GitHub Issue 创建实现
---

## 工作流
1. 使用 `GitHub:get_issue` 工具获取 Issue 详情
2. 分析需求并制定计划
3. 实现功能
4. 使用 `GitHub:create_pr` 创建 Pull Request

Skills + Hooks：

{
  "hooks": {
    "post-edit": {
      "command": "python scripts/format.py",
      "description": "Auto-format after editing"
    }
  }
}

管理和分享 Skills

查看可用 Skills：

# 列出所有 Skills
claude "有哪些可用的 Skills？"

# 查看 Skill 详情
/help explain-code

分享 Skills：

项目级：将 .claude/skills/ 提交到版本控制
插件：在插件中创建 skills/ 目录
企业级：通过管理配置部署

Skills 故障排查：

问题	可能原因	解决方案
Skill 未触发	description 不够具体	添加关键词和使用场景
触发过于频繁	description 太宽泛	更具体的描述或添加 `disable-model-invocation: true`
Claude 看不到 Skill	超出字符预算	简化 description 或增加 `SLASH_COMMAND_TOOL_CHAR_BUDGET`

创建自定义 Subagent

对于重复的专业任务，可以创建自定义 subagent：

# .claude/subagents/test-writer.py
"""
Custom subagent for writing comprehensive tests
"""

def generate_tests(file_path, coverage_target=80):
    """
    Generate unit tests for given file
    Args:
        file_path: Path to source file
        coverage_target: Target coverage percentage
    """
    # Subagent logic here
    pass

1
2
3

# 使用自定义 subagent
claude "使用 test-writer subagent 为 src/services/ 下所有文件生成测试，
目标覆盖率 90%"

插件系统

Claude Code 支持插件扩展功能：

# 安装插件
claude plugin install code-review-assistant

# 启用插件
claude plugin enable code-review-assistant

# 使用插件功能
claude "使用 code-review-assistant 审查最近的 commit"

常用插件类型：

代码质量检查
安全漏洞扫描
性能分析
文档生成
依赖管理

团队协作与规模化

编写团队级 CLAUDE.md

团队使用 Claude Code 时，CLAUDE.md 应该成为团队知识库的一部分：

# CLAUDE.md - Team Edition

## Project Overview
[项目背景、业务领域、技术栈]

## Team Conventions
- **Branch naming**: feature/*, bugfix/*, hotfix/*
- **Commit messages**: Follow Conventional Commits
- **PR process**: Require 2 approvals, all checks must pass
- **Code ownership**: See CODEOWNERS file

## Common Workflows

### Adding a New API Endpoint
1. Define schema in `src/schemas/`
2. Implement handler in `src/handlers/`
3. Add route in `src/routes/`
4. Write integration test in `tests/integration/`
5. Update OpenAPI spec in `docs/api.yaml`

### Database Migrations
```bash
npm run migration:create -- --name add_user_roles
# Edit migration file
npm run migration:run
npm run migration:test

Troubleshooting

Build fails with “Module not found”: Run npm ci to clean install
Tests timeout: Increase timeout in jest.config.js
Database connection fails: Check VPN connection

Contact

Architecture questions: @architecture-team
DevOps issues: @devops-team
Security concerns: @security-team


### 多会话并行工作

大型项目可以启动多个 Claude 会话并行工作：

```bash
# Terminal 1: 前端开发
cd frontend
claude "实现用户仪表板组件"

# Terminal 2: 后端 API
cd backend
claude "实现用户统计 API"

# Terminal 3: 数据库迁移
cd database
claude "创建用户活动日志表的迁移脚本"

# Terminal 4: 文档更新
cd docs
claude "根据新 API 更新文档"

Headless Mode：自动化与 CI/CD

Claude Code 支持 headless 模式，适合集成到 CI/CD 流程：

# 在 CI 中运行 Claude Code
claude --headless --task "运行所有测试，如果失败则分析原因并尝试修复"

# GitHub Actions 集成
# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Claude Code Review
        run: |
          claude --headless --task "审查这个 PR 的代码变更，
          检查是否符合团队规范，是否有潜在 bug"
        env:
          CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}

企业级配置管理

企业环境可以使用集中式配置管理：

// /etc/claude/enterprise-config.json
{
  "allowed_operations": ["read", "write", "execute"],
  "forbidden_paths": ["/etc", "/var", "~/.ssh"],
  "mcp_servers": {
    "github": { "org": "your-company" },
    "jira": { "project": "PROJ" }
  },
  "audit_log": {
    "enabled": true,
    "destination": "syslog"
  },
  "rate_limits": {
    "requests_per_hour": 1000
  }
}

常见陷阱与解决方案

陷阱 1：过度依赖长对话

问题：在一个会话中处理太多不相关的任务，导致 Claude 混淆上下文。

解决方案：

每完成一个独立任务就 /clear
使用 subagents 分离不同任务
为不同类型的工作启动独立会话

陷阱 2：没有验证就信任输出

问题：假设 Claude 生成的代码是正确的，直接提交。

解决方案：

始终要求 Claude 运行测试验证
使用 hooks 自动运行 linter 和测试
Code review 流程不能省略
关键代码手动审查

陷阱 3：CLAUDE.md 过时或缺失

问题：项目规范变化了，但 CLAUDE.md 没有更新，导致 Claude 使用错误的模式。

解决方案：

将 CLAUDE.md 纳入代码审查流程
重大架构变更时同步更新 CLAUDE.md
定期审查 CLAUDE.md 的准确性
在 PR 模板中提醒更新 CLAUDE.md

陷阱 4：忽略权限和安全

问题：使用 --dangerously-skip-permissions 在不信任的代码库中，导致安全风险。

解决方案：

仅在信任的项目中使用 skip permissions
使用 hooks 实现细粒度权限控制
审计 Claude 的所有文件操作
敏感项目使用沙箱环境

陷阱 5：不合理的任务分解

问题：给 Claude 一个过于庞大的任务，如”重写整个应用”。

解决方案：

将大任务分解为可管理的子任务
使用 Plan Mode 先制定计划
逐步验证每个子任务的结果
使用 checkpoints 保存进度

性能优化建议

减少 Token 消耗

# ❌ 低效：让 Claude 读取整个大文件
claude "优化 src/utils/large-file.ts"

# ✅ 高效：指定具体函数
claude "优化 src/utils/large-file.ts 中的 processData 函数"

# ✅ 使用 .claudeignore 排除无关文件
# .claudeignore
node_modules/
dist/
*.log
coverage/
.git/

利用缓存

# Claude Code 会自动缓存：
- 文件内容
- 命令输出
- MCP 响应

# 利用缓存的最佳实践：
- 避免频繁修改 CLAUDE.md（会使缓存失效）
- 重复的命令会直接使用缓存结果
- 使用 /clear 会清空缓存，谨慎使用

并行化操作

# ❌ 串行处理
claude "为 A.ts 添加测试"
# 等待完成...
claude "为 B.ts 添加测试"
# 等待完成...

# ✅ 并行处理
claude "为 A.ts 和 B.ts 添加测试，使用 subagents 并行处理"

实战案例

案例 1：大规模重构

场景：将 REST API 迁移到 GraphQL

# 第 1 步：探索和规划
claude plan "分析当前 REST API 结构，制定迁移到 GraphQL 的计划"

# 第 2 步：审查计划并调整
# Claude 会列出：
# - 需要创建的 GraphQL schema
# - 需要修改的 resolver
# - 需要更新的客户端代码
# - 测试策略

# 第 3 步：创建检查点
/checkpoint save "开始 GraphQL 迁移"

# 第 4 步：使用 subagents 并行执行
claude "按照计划执行 GraphQL 迁移，创建 subagents 分别处理：
1. 定义 GraphQL schema
2. 实现 resolvers
3. 更新客户端查询
4. 迁移测试用例"

# 第 5 步：验证
claude "运行完整测试套件，确保所有功能正常"

# 第 6 步：文档更新
claude "更新 API 文档，添加 GraphQL 使用示例"

案例 2：性能优化

场景：优化慢查询

# 第 1 步：诊断问题
claude "连接到数据库（通过 MCP），找出最慢的 10 个查询"

# 第 2 步：分析根因
claude --extended-thinking "分析这些慢查询的根本原因，
考虑索引、查询计划、数据量等因素"

# 第 3 步：制定优化方案
claude "为每个慢查询提供优化方案，包括：
- 索引建议
- 查询重写
- 缓存策略
评估每个方案的收益和风险"

# 第 4 步：实施优化
claude "实施优化方案，先在开发环境验证效果"

# 第 5 步：性能测试
claude "运行性能测试，对比优化前后的查询时间"

案例 3：Bug 修复

场景：生产环境出现间歇性错误

# 第 1 步：收集信息
claude "从 Sentry（通过 MCP）获取最近 24 小时的错误报告，
聚焦 'UserService.updateProfile' 相关的错误"

# 第 2 步：复现问题
claude "根据错误堆栈和用户报告，编写能够复现问题的测试用例"

# 第 3 步：调试
claude "分析 UserService.updateProfile 的代码，
找出可能导致间歇性错误的竞态条件或边缘情况"

# 第 4 步：修复验证
claude "修复问题后，运行测试用例 100 次，确保问题不再出现"

# 第 5 步：回归测试
claude "运行完整测试套件，确保修复没有引入新问题"

学习资源与社区

官方资源

官方文档：https://code.claude.com/docs
最佳实践指南：https://www.anthropic.com/engineering/claude-code-best-practices
MCP 协议规范：https://modelcontextprotocol.io/
GitHub Changelog：https://github.com/anthropics/claude-code/releases

社区资源

Claude Code Discord：官方 Discord 服务器，活跃的社区支持
Reddit r/ClaudeAI：用户分享使用技巧和案例
YouTube 教程：搜索 “Claude Code tutorial” 有大量视频教程
GitHub Awesome List：https://github.com/topics/claude-code

进阶学习路径

基础阶段（1-2 周）
- 熟悉基本命令和工作流
- 编写第一个 CLAUDE.md
- 完成简单的代码生成任务
进阶阶段（1 个月）
- 掌握 Plan Mode 和 Subagents
- 配置 MCP 服务器
- 使用 Hooks 自动化工作流
专家阶段（持续学习）
- 创建自定义 Subagents
- 开发 MCP 服务器
- 优化团队协作流程
- 贡献社区插件和最佳实践

总结

Claude Code 不仅仅是一个代码生成工具，而是一个自主编程伙伴。要充分发挥其价值，关键在于：

核心要点

建立正确的心智模型：理解 Claude Code 是自主代理，不是简单的补全工具
投资于配置：编写高质量的 CLAUDE.md，配置 MCP 和 Hooks
遵循最佳流程：探索 → 规划 → 编码，而非直接编码
保持会话清晰：频繁使用 /clear，避免长对话混乱
验证验证验证：永远不要盲目信任 AI 输出，要求自动化验证
善用高级特性：Subagents、Plan Mode、Checkpoints 是效率倍增器
团队协作：将 CLAUDE.md 纳入团队规范，统一工作方式

下一步行动

为你的项目创建 CLAUDE.md
尝试使用 Plan Mode 分析一个复杂任务
配置至少一个 MCP 服务器（建议从 GitHub 开始）
使用 Subagents 处理一个多文件任务
设置 Hooks 自动化你的常用工作流
在团队中分享 Claude Code 最佳实践

参考资源

本文由 AI 辅助生成，如有错误或建议，欢迎指出。

Claude Code 核心理解

什么是 Claude Code

Claude Code vs Cursor：选择指南

环境配置与初始化

快速安装

创建 CLAUDE.md：项目上下文的关键

CLAUDE.md 应该包含什么

Code Style Guidelines

Testing Instructions

Repository Etiquette

Developer Environment Setup

企业代理配置

核心工作流程与最佳实践

黄金法则：探索 → 规划 → 编码

1. 探索阶段（Exploration）

2. 规划阶段（Planning）

3. 编码阶段（Coding）

使用 Plan Mode 进行安全分析

频繁使用 /clear 保持会话清晰

提供丰富的上下文

差的提示词示例

好的提示词示例

让 Claude 验证自己的工作

高级技巧与模式

使用 Subagents 进行任务委派

使用 Git Worktrees 进行并行开发

使用 Extended Thinking Mode

Checkpointing：时光机功能

Model Context Protocol (MCP) 集成

什么是 MCP

配置 MCP 服务器

MCP 实际应用场景

场景 1：从 GitHub Issue 生成代码

场景 2：数据库驱动开发

场景 3：从设计稿生成代码

常用 MCP 服务器

自定义与扩展

Hooks：自动化工作流

创建 Hooks 配置

Hooks 应用场景

Skills：扩展 Claude 的能力

什么是 Skills

创建第一个 Skill

Skill 存放位置

Skill 结构最佳实践

高级功能

实用 Skill 示例

频繁使用 `/clear` 保持会话清晰