# Claude Code Usage Tips

**Repository Path**: yuanwang99/claude-code-usage-tips

## Basic Information

- **Project Name**: Claude Code Usage Tips
- **Description**: Claude Code使用技巧与案例，本项目是一份 Claude Code 项目配置的完整参考模板，涵盖团队协作所需的标准目录结构和配置文件。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: tips, AI, Agent, ClaudeCode

## README

# Claude Code 使用技巧

<div align="center">

![Claude Code Cover](./images/cover.png)

> 🤖 Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI 工具，深度集成终端与代码库，支持多智能体协作、MCP 扩展、自定义命令与 Hook，助你将 AI 真正融入开发工作流。

[![Claude Code](https://img.shields.io/badge/Claude%20Code-Official-orange)](https://docs.anthropic.com/en/docs/claude-code)
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
[![Stars](https://img.shields.io/github/stars/your-repo/cluade-code-usage-tips?style=social)](https://github.com/your-repo/cluade-code-usage-tips)

</div>

---

## 📁 项目结构

> 本项目是一份 Claude Code 项目配置的完整参考模板，涵盖团队协作所需的标准目录结构和配置文件。克隆后可直接作为任何项目的 `.claude/` 初始化基线。

```
your-project/
├── CLAUDE.md                # 🟢 团队共享指令，提交到 Git
├── CLAUDE.local.md          # 🔵 个人本地配置，加入 .gitignore
├── .claude/                 # Claude Code 配置目录
│   ├── settings.json        # 🟢 团队共享配置（权限策略、Hook、模型设置）
│   └── settings.local.json  # 🔵 个人本地配置（密钥、环境差异，加入 .gitignore）
├── commands/                # 自定义斜杠命令（通过 /project:xxx 调用）
│   ├── review.md            # /project:review  代码审查
│   ├── fix-issue.md         # /project:fix-issue  修复问题
│   └── deploy.md            # /project:deploy  部署流程
├── rules/                   # 模块化规则文件（全局生效）
│   ├── code-style.md        # 代码风格规范
│   ├── testing.md           # 测试策略与规范
│   └── api-conventions.md   # API 设计与使用约定
├── skills/                  # 自动调用的工作流（Skills）
│   ├── security-review/     # 安全审查工作流
│   │   └── SKILL.md
│   └── deploy/              # 部署工作流
│       └── SKILL.md
└── agents/                  # 子代理角色定义
    ├── code-reviewer.md     # 代码审查子代理
    └── security-auditor.md  # 安全审计子代理
```

![Claude Code Cover](./images/introduce.png)

### 各目录/文件说明

| 文件/目录 | 作用 | Git | 示例 |
|-----------|------|-----|------|
| `CLAUDE.md` | 团队共享的项目知识库 | ✅ 上传 | 技术栈、编码规范、项目结构 |
| `CLAUDE.local.md` | 个人独享的本地指令 | ❌ 忽略 | 个人工作习惯、本地路径 |
| `.claude/settings.json` | 团队统一的工具权限和 Hook | ✅ 上传 | 白名单命令、PostToolUse 钩子 |
| `.claude/settings.local.json` | 个人环境的差异配置 | ❌ 忽略 | 本地密钥路径、个人 MCP 工具 |
| `commands/` | 自定义 `/project:name` 命令 | ✅ 上传 | `/project:review`、`/project:deploy` |
| `rules/` | 模块化项目规范 | ✅ 上传 | 代码风格、测试策略、API 约定 |
| `skills/` | 自动触发的工作流 | ✅ 上传 | 安全审查、自动化部署 |
| `agents/` | 预定义子代理角色 | ✅ 上传 | 代码审查员、安全审计员 |

> **💡 为什么拆成 `commands/` 和 `skills/`？**
> - `commands/`（Slash Commands）：用户手动输入 `/xxx` 触发，适合需要确认的流程（审查、部署）
> - `skills/`（Skills）：Claude 根据上下文自动加载，适合通用能力（PDF 处理、安全检测）
>
> 两者互补，不冲突 — `commands/` 是用户主动决策，`skills/` 是 AI 智能辅助。

---

## 📚 目录

![TOC Overview](./images/toc.png)

| # | 章节 | 简介 |
|---|------|------|
| 1 | [🚀 快速开始](#-快速开始) | 安装与基础配置 |
| 2 | [⌨️ 常用命令](#️-常用命令) | 核心斜杠命令速查 |
| 3 | [🧠 思考模式](#-思考模式) | 控制模型推理深度 |
| 4 | [👥 SubAgent 多智能体](#-subagent-多智能体) | 并行任务处理 |
| 5 | [🔌 MCP 工具集成](#-mcp-工具集成) | 扩展 AI 能力边界 |
| 6 | [🛠️ 自定义命令](#️-自定义命令) | 打造专属工作流 |
| 7 | [🪝 Hook 钩子](#-hook-钩子) | 自动化触发机制 |
| 8 | [🔒 权限控制](#-权限控制) | 安全与自动化平衡 |
| 9 | [💾 记忆系统](#-记忆系统) | 跨会话知识持久化 |
| 10 | [💡 实战案例](#-实战案例) | 典型使用场景 |
| 11 | [🔧 进阶技巧](#-进阶技巧) | 提效工作流 |

---

## 🚀 快速开始

### 安装

```bash
# 全局安装（需 Node.js 18+）
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 启动 Claude Code（在项目目录下）
claude
```

### 首次使用

进入项目目录后，推荐第一步执行项目初始化：

```bash
# 初始化项目知识库（Claude 会分析整个项目并生成 CLAUDE.md）
/init
```

> **💡 Tip**：`CLAUDE.md` 类似 Cursor 的 CursorRule，是 AI 的"项目说明书"。你可以手动编辑，添加项目规范、技术栈说明、禁止操作等重要信息。

---

## ⌨️ 常用命令

### 斜杠命令速查表

| 命令 | 功能 | 使用场景 |
|------|------|----------|
| `/init` | 初始化项目，生成 `CLAUDE.md` | 首次使用或项目结构变更后 |
| `/compact` | 压缩对话上下文 | 长对话 Token 消耗过高时 |
| `/clear` | 清除全部对话记录 | 开启新任务前 |
| `/ide` | 联通 IDE 与命令行 Claude | 在 VSCode/JetBrains 中使用 |
| `/mcp` | 查看已安装 MCP 工具列表 | 管理扩展工具 |
| `/agents` | 创建并管理 SubAgent | 并行多任务处理 |
| `/permissions` | 查看和管理工具权限 | 配置自动执行规则 |

### 特殊前缀命令

| 前缀 | 功能 | 示例 |
|------|------|------|
| `!` | 切换到命令行模式执行系统命令 | `!npm install axios` |
| `#` | 记忆模式，保存长期记忆 | `#本项目使用 Tailwind CSS，不要使用 Bootstrap` |

#### `!` 命令示例

```bash
# 在 Claude 对话中直接执行系统命令，结果会加入上下文
!git status
!npm run test
!docker ps
!ls -la src/
```

> **💡 案例**：当 Claude 修改了代码后，你可以立即用 `!npm run build` 验证构建结果，Claude 会看到输出并自动修复报错，无需切换窗口。

#### `#` 记忆命令示例

```bash
# 项目级记忆（保存到当前项目 CLAUDE.md）
#这个项目后端用 Spring Boot 3，JDK 21，不要用 JDK 8 的写法

# 用户级记忆（对所有项目生效）
# Windows 用户级记忆路径：C:\Users\用户名\.claude\CLAUDE.md
#我习惯用函数式组件，不要写 class 组件
```

---

## 🧠 思考模式

Claude Code 支持通过特定关键词控制模型的思考深度，思考越深，消耗 Token 越多，但适合复杂推理任务。

### 思考深度梯级

```
think < thinkhard < thinkharder < ultrathink
```

| 关键词 | 适用场景 | Token 消耗 |
|--------|----------|-----------|
| `think` | 简单逻辑、基础代码 | ⭐ |
| `thinkhard` | 中等复杂度功能设计 | ⭐⭐ |
| `thinkharder` | 复杂架构决策、调试难题 | ⭐⭐⭐ |
| `ultrathink` | 系统设计、极复杂问题 | ⭐⭐⭐⭐ |

### 使用示例

```bash
# 普通任务
帮我写一个 util 函数，格式化日期

# 中等复杂任务
thinkhard 帮我设计一个用户权限系统，支持 RBAC 模型

# 复杂架构设计
ultrathink 分析这个微服务架构的性能瓶颈，给出优化方案
```

> **💡 案例**：调试一个 Spring Boot 应用的内存泄露问题时，使用 `ultrathink` 可以让 AI 进行更深入的代码分析，关联多个文件的上下文，找出根本原因。

---

## 👥 SubAgent 多智能体

SubAgent 是 Claude Code 的并行处理能力，类似多线程，可以同时执行多个独立子任务，大幅提升复杂项目的处理效率。

### 工作原理

```
主 Agent（协调者）
    ├── SubAgent 1：负责前端组件开发
    ├── SubAgent 2：负责后端 API 接口
    ├── SubAgent 3：负责数据库 Schema 设计
    └── SubAgent 4：负责编写单元测试
         ↓
    主 Agent 整合所有结果
```

### 创建 SubAgent

```bash
# 方式一：使用 /agents 命令
/agents

# 方式二：在任务描述中隐式触发
# Claude 会自动判断是否需要拆分为并行任务
请同时帮我：1. 重构 UserService 2. 更新对应的单元测试 3. 更新 API 文档
```

### 实战案例：全栈功能开发

**场景**：需要在电商系统中新增"商品收藏"功能。

```bash
# 告知 Claude 使用并行处理
请使用多个 agent 并行完成商品收藏功能：
- Agent 1：设计数据库表结构（favorite_products 表）
- Agent 2：实现后端 RESTful API（收藏/取消/列表接口）
- Agent 3：开发前端收藏按钮组件（React + Tailwind）
- Agent 4：编写集成测试用例

要求接口风格统一，前后端字段名保持一致。
```

> **⚠️ 注意**：SubAgent 共享同一 context window，任务过多时需配合 `/compact` 压缩上下文。

---

## 🔌 MCP 工具集成

MCP（Model Context Protocol）是扩展 Claude Code 能力的核心机制，允许 AI 调用外部工具、数据库、API 等。

### 安装 MCP 工具

```bash
# 基础语法
claude mcp add <工具名> [选项] <安装命令>

# 安装为用户级别（所有项目共享）
claude mcp add <工具名> --scope user <安装命令>

# 查看已安装工具
/mcp

# 删除工具
claude mcp remove <工具名>
```

### 常用 MCP 工具推荐

```bash
# Context7 - 实时获取第三方库最新文档
claude mcp add context7 --scope user --npx @upstash/context7-mcp

# Playwright - 浏览器自动化（测试/爬虫）
claude mcp add playwright --scope user --npx @playwright/mcp@latest

# GitHub - 直接操作 GitHub 仓库
claude mcp add github --scope user --npx @modelcontextprotocol/server-github

# SQLite - 操作本地 SQLite 数据库
claude mcp add sqlite --scope user --npx @modelcontextprotocol/server-sqlite

# Puppeteer - 另一款浏览器自动化工具
claude mcp add puppeteer --scope user --npx @modelcontextprotocol/server-puppeteer
```

### 支持的协议类型

| 协议 | 场景 |
|------|------|
| `npx` | Node.js 工具包 |
| `uvx` / `pip` | Python 工具包 |
| SSE（远程） | 远程 HTTP 服务调用 |
| Streamable HTTP | 流式远程调用 |

### 实战案例：接入 Context7 查询最新文档

```bash
# 安装 Context7
claude mcp add context7 --scope user --npx @upstash/context7-mcp

# 在对话中使用（Claude 会自动调用最新文档）
请参考 Spring Boot 3.3 的最新文档，帮我配置一个 WebFlux 响应式路由

# 指定库版本
查询 React 18 的 useTransition Hook 最新用法示例
```

> **💡 场景**：当你使用 `langchain@0.3.x` 这类快速迭代的库时，Context7 能确保 Claude 使用的是最新 API，而非训练数据中的旧版本。

---

## 🛠️ 自定义命令

自定义命令让你把常见工作流封装为可复用的指令，通过 `/命令名` 快速调用。

### 目录结构

```
your-project/
└── .claude/
    └── commands/
        ├── review.md        # → /review 命令
        ├── deploy.md        # → /deploy 命令
        ├── test-all.md      # → /test-all 命令
        └── gen-api.md       # → /gen-api 命令（支持参数）
```

### 创建命令示例

**`.claude/commands/review.md`** — 代码审查命令

```markdown
请对当前变更的文件进行代码审查，重点关注：

1. **安全性**：SQL注入、XSS、敏感信息泄露
2. **性能**：N+1查询、不必要的全表扫描
3. **可维护性**：命名规范、注释完整性、函数单一职责
4. **测试覆盖**：关键逻辑是否有单元测试

以 Markdown 表格形式输出审查报告，按优先级排序（Critical > High > Medium > Low）。
```

**`.claude/commands/gen-api.md`** — 生成 API 接口（带参数）

```markdown
根据以下实体名称生成完整的 RESTful API：$ARGUMENTS

请生成：
1. Spring Boot Controller（含 Swagger 注解）
2. Service 接口 + 实现类
3. MyBatis-Plus Mapper
4. 请求/响应 DTO
5. 单元测试类

遵循项目现有的代码风格和包结构。
```

### 使用自定义命令

```bash
# 执行无参数命令
/review

# 执行带参数命令（$ARGUMENTS 会被替换）
/gen-api User
/gen-api Product --with-pagination
```

### 更多命令模板示例

**`.claude/commands/commit.md`** — 规范化 Git 提交

```markdown
分析当前 git diff，按照 Conventional Commits 规范生成提交信息：

格式：<type>(<scope>): <subject>

type 可选：feat / fix / docs / style / refactor / test / chore

然后执行：
1. git add -A
2. git commit -m "<生成的提交信息>"

最后展示提交结果。
```

---

## 🪝 Hook 钩子

Hook 允许你在 Claude Code 工作流的特定节点自动触发命令，实现代码质量守门、日志记录、自动化测试等功能。

### 配置文件位置

```bash
# 项目级 Hook（提交到 Git，团队共享）
.claude/settings.json

# 本地 Hook（不提交，个人专用）
.claude/settings.local.json
```

### 触发时机（hookType）

| 钩子名 | 触发时机 |
|--------|----------|
| `PostToolUse` | 每次工具调用完成后 |
| `PreToolUse` | 工具调用前（可用于拦截） |
| `Stop` | Claude 完成回复后 |
| `Notification` | 收到通知时 |

### 配置示例

**`.claude/settings.json`**

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ."
          }
        ]
      }
    ]
  }
}
```

### 实战案例

**场景 1：每次写完文件自动格式化**

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

**场景 2：Java 项目写完代码自动运行测试**

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd /project && mvn test -pl $(dirname $CLAUDE_TOOL_INPUT_FILE_PATH) -q 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}
```

**场景 3：操作完成后发送通知（macOS）**

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 任务完成\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

---

## 🔒 权限控制

### 权限管理命令

```bash
# 查看当前权限配置
/permissions

# 启动时赋予最高权限（跳过所有确认提示）
claude --dangerously-skip-permissions
```

> **⚠️ 警告**：`--dangerously-skip-permissions` 会跳过所有安全确认，建议仅在受控环境（如 CI/CD、Docker 容器）中使用。

### 配置 Allow 列表

在 `.claude/settings.json` 中配置允许自动执行的工具：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff)",
      "Write(src/**)",
      "Edit(src/**)",
      "Read(**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Write(.env*)"
    ]
  }
}
```

### 权限级别说明

| 权限模式 | 说明 | 适用场景 |
|----------|------|----------|
| 默认（交互确认） | 每个操作需用户确认 | 日常开发，安全优先 |
| Allow 白名单 | 指定命令自动执行 | 常见构建/测试命令 |
| `--dangerously-skip-permissions` | 跳过全部确认 | CI/CD 自动化流水线 |

---

## 💾 记忆系统

Claude Code 提供两种记忆层级，让 AI 跨会话保持项目上下文。

### 记忆层级

| 层级 | 文件位置 | 作用域 | 典型内容 |
|------|----------|--------|----------|
| **项目级** | `{项目根目录}/CLAUDE.md` | 当前项目 | 项目架构、技术栈、编码规范 |
| **用户级** | `~/.claude/CLAUDE.md` | 所有项目 | 个人偏好、通用规范、常用工具 |

> **Windows 用户级路径**：`C:\Users\{用户名}\.claude\CLAUDE.md`

### 手动编辑 CLAUDE.md

```markdown
# 项目名称 - Claude Context

## 技术栈
- 后端：Spring Boot 3.3 + JDK 21
- 前端：React 18 + TypeScript + Tailwind CSS
- 数据库：MySQL 8.0 + Redis 7.0
- 构建：Maven + Vite

## 编码规范
- 使用函数式组件，不写 class 组件
- 所有 API 返回统一用 Result<T> 包装
- 禁止在 Controller 层写业务逻辑

## 项目结构
src/
├── main/java/com/example/
│   ├── controller/  # 控制器层
│   ├── service/     # 业务逻辑层
│   ├── mapper/      # 数据访问层
│   └── entity/      # 实体类

## 注意事项
- 生产环境配置在 application-prod.yml，不要提交敏感信息
- 测试数据库连接：localhost:3306/testdb
```

### 使用 `#` 命令快速添加记忆

```bash
# 会询问保存到项目级还是用户级
#我们的 API 前缀统一用 /api/v1

#所有异常统一由 GlobalExceptionHandler 处理，不要在 Service 层 try-catch

#这个项目使用 Lombok，实体类需要加 @Data 注解
```

---

## 💡 实战案例

### 案例 1：快速搭建 Spring Boot 项目骨架

```bash
# 初始化项目
/init

# 告知技术栈
#这是一个 Spring Boot 3 + MyBatis-Plus + Redis 的电商后台项目

# 生成用户模块
/gen-api User

# 验证编译
!mvn compile -q

# 代码审查
/review
```

### 案例 2：调试复杂 Bug

**场景**：线上出现偶发性空指针异常，日志不完整。

```bash
# 使用深度思考模式分析
ultrathink 以下是线上错误日志，请帮我定位根本原因：

[ERROR] NullPointerException at OrderService.createOrder(OrderService.java:87)
    at UserMapper.findById returning null when userId=10086

请分析：
1. 可能的触发条件
2. 相关代码的潜在问题
3. 修复方案和预防措施
```

### 案例 3：批量重构代码

**场景**：将项目中所有 `Date` 类型替换为 `LocalDateTime`。

```bash
# 使用 SubAgent 并行处理多个模块
请使用多个 agent 并行完成 Date → LocalDateTime 重构：

Agent 1：扫描 entity/ 目录，替换所有 Date 字段
Agent 2：更新 DTO 层的 Date 类型
Agent 3：修改 MyBatis XML 中的类型映射
Agent 4：更新相关工具类和序列化配置

完成后，Agent 主体执行 !mvn test 验证无回归问题。
```

### 案例 4：前端组件自动生成

**场景**：根据后端 API 文档生成前端 React 组件。

```bash
# 先让 Claude 读取 API 文档
!cat src/main/resources/api-docs.json

# 生成对应的 React 表单组件
基于以上 API，生成一个 React 用户注册表单组件：
- 使用 React Hook Form 做表单验证
- 使用 Tailwind CSS 样式
- 包含字段：用户名、邮箱、密码、确认密码
- 提交后调用 POST /api/v1/users/register
- 添加 loading 状态和错误提示
```

### 案例 5：自动化测试生成

```bash
# 为现有 Service 生成单元测试
请为 UserService 生成完整的 JUnit 5 单元测试：

要求：
1. 使用 Mockito 模拟依赖
2. 覆盖正常流程和异常场景
3. 测试覆盖率达到 80% 以上
4. 包括边界值测试（null 值、空字符串、超长字段）

生成后执行 !mvn test -pl . -Dtest=UserServiceTest 验证通过
```

---

## 🔧 进阶技巧

### 技巧 1：上下文管理最佳实践

```bash
# 长任务开始前清空上下文
/clear

# 任务进行中，上下文过长时压缩
/compact 保留：技术栈信息、当前任务目标、已完成的模块列表

# 开启新子任务时
/clear
# 然后重新 /init 让 Claude 快速加载项目信息
```

### 技巧 2：提升输出质量的 Prompt 模板

```bash
# 明确输出格式
帮我实现 X 功能，要求：
1. 直接给出完整可运行代码
2. 不要解释，代码注释中说明关键逻辑
3. 遵循项目现有的代码风格（见 CLAUDE.md）
4. 完成后执行 !npm run test 验证

# 迭代优化
上面的实现存在以下问题：[描述问题]
请在保持接口不变的前提下修复，并说明修改了哪些地方
```

### 技巧 4：与 CI/CD 集成

```yaml
# GitHub Actions 示例
- name: AI Code Review
  run: |
    claude --dangerously-skip-permissions \
      "对本次 PR 的改动进行安全审查，输出 JSON 格式报告" \
      > code-review-report.json

- name: Auto Fix Lint
  run: |
    claude --dangerously-skip-permissions \
      "/lint-fix 修复所有 ESLint 错误并提交"
```

### 技巧 5：多项目统一配置

在 `~/.claude/CLAUDE.md` 中设置全局规范，所有项目自动继承：

```markdown
# 全局个人规范

## 代码风格
- 优先使用 async/await，避免 callback 嵌套
- 变量命名使用 camelCase，常量用 UPPER_SNAKE_CASE
- 函数超过 50 行需要拆分

## 工具偏好
- 包管理：优先使用 pnpm > npm > yarn
- 测试框架：Java 用 JUnit5 + Mockito，JS 用 Vitest

## 安全红线
- 不允许将密钥、token 硬编码在代码中
- 不允许直接在生产数据库执行 UPDATE/DELETE（无 WHERE 条件）
```

---

## 📎 参考资源

- 📖 [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)
- 🎯 [MCP 官方协议文档](https://modelcontextprotocol.io/)
- 🛠️ [MCP 工具市场](https://github.com/modelcontextprotocol/servers)
- 💬 [Claude Code GitHub Discussions](https://github.com/anthropics/claude-code/discussions)
- 🧩 [Context7 MCP 工具](https://github.com/upstash/context7)

---

<div align="center">

📝 **持续更新中** · 欢迎 PR 补充更多使用技巧

</div>