Claude Code 使用指南

目录

第1章：概述

1.1 什么是 Claude Code

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，基于最新的 Claude 模型（Claude Opus 4.6、Sonnet 4.6、Haiku 4.5）。它将 Claude 的强大能力直接集成到您的开发工作流中，让您可以在终端中与 AI 进行自然语言对话，完成代码编写、调试、重构等任务。

1.2 核心能力

能力 描述
AI 驱动的开发体验 通过自然语言对话完成编程任务，无需记忆复杂命令
智能文件操作 自动读取和分析项目文件，理解代码上下文
Git 集成 支持对话式 Git 操作，如创建提交、解决冲突、管理分支
精准代码编辑 展示建议修改并请求批准，确保变更符合预期
多模型支持 可选择不同模型（Opus/Sonnet/Haiku）以平衡能力和速度
扩展生态 支持 Skills 自定义和 MCP Server 集成，扩展 AI 能力

1.3 安装方式

NPM 安装（跨平台）
npm install -g @anthropic-ai/claude-code
Homebrew 安装（macOS、Linux）
brew install --cask claude-code
Windows PowerShell 安装
irm https://claude.ai/install.ps1 | iex

1.4 基本使用命令

启动 Claude Code
# 在当前目录启动
claude

# 指定工作目录启动
claude /path/to/project
常用命令行参数
参数 说明
--model <model> 指定使用的模型（如 claude-sonnet-4-6）
--permission-mode <mode> 设置权限模式（default/acceptEdits/plan）
-p "<prompt>" 直接执行提示词（headless 模式）
--continue 继续上一个会话
--resume <session-id> 恢复指定会话
会话内常用命令
命令 说明
/help 显示帮助信息
/clear 清除当前会话上下文
/init 初始化项目 CLAUDE.md 文件
/mcp 管理 MCP 服务器
/compact 压缩会话历史
/cost 显示当前会话成本
/config 打开配置设置
快捷键
快捷键 说明
Shift+Tab 循环切换权限模式
Esc+Esc 回滚最近的文件更改
Ctrl+C 中断当前操作

1.5 模型选择

Claude Code 支持以下模型，您可以根据任务需求选择：

模型 ID 特点 适用场景
Opus 4.6 claude-opus-4-6 最强能力，深度推理 复杂架构设计、困难问题解决
Sonnet 4.6 claude-sonnet-4-6 平衡能力与速度 日常开发任务（默认推荐）
Haiku 4.5 claude-haiku-4-5-20251001 最快响应 简单查询、快速迭代 
# 切换模型示例
claude --model claude-opus-4-6

第2章：工程初始化配置

本章介绍如何为项目配置 Claude Code，包括 CLAUDE.md 文件、规则目录、settings.json 配置等。

2.1 CLAUDE.md 文件

CLAUDE.md 是 Claude Code 的核心配置文件，用于向 Claude 提供项目上下文和指令。Claude 在每次会话开始时会自动读取该文件。

作用域层级
作用域 位置 用途 是否共享
组织级 系统目录 IT/DevOps 管理的全局规则 全组织
项目级 ./CLAUDE.md 团队共享的项目规则 通过 Git 共享
用户级 ~/.claude/CLAUDE.md 个人偏好设置 仅自己可见
本地级 ./CLAUDE.local.md 项目个人配置 不提交到 Git
初始化项目

使用 /init 命令自动生成 CLAUDE.md 文件：

# 在项目根目录运行
claude
> /init

Claude 会分析项目结构，自动生成包含以下内容的 CLAUDE.md：

  • 项目概述和技术栈
  • 主要目录结构
  • 构建和测试命令
  • 代码风格指南
CLAUDE.md 最佳实践示例
# 项目名称：My Web Application

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 测试：Jest + Playwright

## 项目结构
- `/src/components` - React 组件
- `/src/pages` - 页面组件
- `/src/api` - API 路由
- `/src/utils` - 工具函数
- `/tests` - 测试文件

## 常用命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm test` - 运行测试
- `npm run lint` - 代码检查

## 代码风格
- 使用函数式组件和 Hooks
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case
- 使用 ESLint + Prettier 格式化

## 架构决策
- 采用分层架构：UI → Services → Data
- 状态管理使用 Zustand
- API 响应使用统一格式
@path 导入语法

CLAUDE.md 支持使用 @path 语法导入其他文件内容：

# 项目配置

## API 规范
@./docs/api-spec.md

## 数据库 Schema
@./database/schema.sql

## 共享类型定义
@./src/types/index.ts

2.2 .claude/rules/ 目录

对于复杂的规则配置，可以使用 .claude/rules/ 目录进行模块化管理。

目录结构
.claude/
└── rules/
    ├── code-style.md      # 代码风格规则
    ├── security.md        # 安全规范
    ├── testing.md         # 测试规则
    └── api-conventions.md # API 约定
路径特定规则

使用 YAML frontmatter 限定规则的应用范围：

---
globs:
  - "src/**/*.ts"
  - "src/**/*.tsx"
---

# TypeScript 代码规范

- 所有函数必须有类型注解
- 避免使用 `any` 类型
- 优先使用接口（interface）而非类型别名（type）
规则文件示例

code-style.md:

---
globs: ["src/**/*"]
---

# 代码风格规范

## 命名约定
- 变量：camelCase
- 常量：UPPER_SNAKE_CASE
- 函数：camelCase
- 类/组件：PascalCase
- 文件：kebab-case

## 注释规范
- 复杂逻辑必须添加注释
- 使用 JSDoc 格式编写函数文档
- 避免无意义的注释

security.md:

---
globs: ["**/*"]
---

# 安全规范

- 禁止硬编码敏感信息（密钥、密码等）
- 用户输入必须验证和清理
- SQL 查询必须使用参数化
- API 响应不暴露内部错误详情

2.3 settings.json 配置

settings.json 用于配置 Claude Code 的行为，包括权限、环境变量、钩子等。

配置作用域
作用域 位置 影响范围
Managed 服务端/系统级 机器上所有用户（由 IT 管理）
User ~/.claude/settings.json 您的所有项目
Project .claude/settings.json 仓库的所有协作者
Local .claude/settings.local.json 仅此仓库中的您
完整配置示例
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",

  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm install *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(./src/**)",
      "Read(./docs/**)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo *)",
      "Read(./.env*)",
      "Read(./secrets/**)"
    ],
    "defaultMode": "default"
  },

  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  },

  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": ["./.claude/hooks/format.sh"]
      }
    ]
  },

  "model": "claude-sonnet-4-6",

  "apiProvider": "anthropic"
}
配置项说明
配置项 说明
permissions.allow 自动允许的工具操作
permissions.deny 始终拒绝的工具操作
permissions.defaultMode 默认权限模式
env 环境变量设置
hooks 事件钩子配置
model 默认使用的模型
apiProvider API 提供商

2.4 完整目录结构

一个完整的 Claude Code 项目配置目录结构如下：

项目根目录/
├── CLAUDE.md                    # 主项目指令文件（Git 跟踪）
├── CLAUDE.local.md              # 本地个人配置（不提交）
├── .mcp.json                    # MCP 服务器配置（可选）
│
└── .claude/
    ├── settings.json            # 团队共享设置（Git 跟踪）
    ├── settings.local.json      # 本地个人设置（不提交）
    │
    ├── agents/                  # 自定义子代理
    │   └── security-reviewer.md
    │
    ├── rules/                   # 模块化规则
    │   ├── code-style.md
    │   ├── security.md
    │   └── testing.md
    │
    ├── skills/                  # 技能定义
    │   └── api-conventions/
    │       └── SKILL.md
    │
    └── hooks/                   # 钩子脚本
        ├── format.sh
        └── lint-check.sh
.gitignore 建议
# Claude Code 本地配置
.claude/settings.local.json
CLAUDE.local.md

# 可选：不跟踪会话历史
.claude/history/

第3章：团队项目配置规则

本章介绍如何在团队环境中配置和管理 Claude Code，包括权限控制、组织级设置和 Hooks 系统。

3.1 配置优先级

Claude Code 的配置按以下优先级合并（高优先级覆盖低优先级）：

Managed > 命令行参数 > Local > Project > User
优先级 配置来源 说明
1（最高） Managed 由 IT/DevOps 管理的组织级配置
2 命令行参数 启动时指定的参数
3 Local .claude/settings.local.json
4 Project .claude/settings.json
5（最低） User ~/.claude/settings.json

3.2 权限配置详解

权限模式
模式 说明 使用场景
default 标准确认模式，每次操作需确认 正常交互开发
acceptEdits 自动接受编辑操作 信任的自动化重构
plan 只读计划模式 复杂任务规划阶段
bypassPermissions 跳过所有权限检查 脚本化/CI 环境操作（谨慎使用）
切换权限模式

会话中切换： 按 Shift+Tab 循环切换

Normal Mode → Auto-Accept Mode → Plan Mode → Normal Mode

启动时指定：

# 以计划模式启动
claude --permission-mode plan

# 以自动接受模式启动
claude --permission-mode acceptEdits
权限规则语法

基本格式： 工具名(参数模式)

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",      // 允许所有 npm run 命令
      "Bash(git status)",     // 允许 git status
      "Bash(git diff *)",     // 允许 git diff 及其参数
      "Read(./src/**)",       // 允许读取 src 目录
      "Edit(./lib/**)"        // 允许编辑 lib 目录
    ],
    "deny": [
      "Bash(rm -rf /*)",      // 拒绝危险命令
      "Bash(sudo *)",         // 拒绝 sudo 命令
      "Bash(curl * | *)",     // 拒绝管道到 shell
      "Read(./.env*)",        // 拒绝读取环境文件
      "Read(./secrets/**)",   // 拒绝读取敏感目录
      "Write(./config/**)"    // 拒绝写入配置目录
    ]
  }
}

通配符说明：

通配符 匹配规则
* 匹配任意字符（不包括 /）
** 匹配任意字符（包括 /）
? 匹配单个字符

ask 规则： 强制询问用户

{
  "permissions": {
    "ask": [
      "Bash(npm publish *)",  // 发布前确认
      "Bash(git push *)"      // 推送前确认
    ]
  }
}

3.3 组织级管理设置

企业环境可以通过 Managed Settings 实现统一管控。

managed-settings.json 位置
平台 路径
macOS /Library/Application Support/ClaudeCode/managed-settings.json
Linux /etc/claude-code/managed-settings.json
Windows C:\Program Files\ClaudeCode\managed-settings.json
企业级配置示例
{
  "$schema": "https://json.schemastore.org/claude-code-managed-settings.json",

  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(./**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | bash)",
      "Read(**/.env*)",
      "Read(**/credentials*)"
    ]
  },

  "mcpAllowlists": {
    "allow": [
      "github",
      "internal-jira"
    ],
    "deny": ["*"]
  },

  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["/usr/local/bin/audit-command.sh"]
      }
    ]
  },

  "model": "claude-sonnet-4-6",
  "apiProvider": "anthropic"
}
沙箱配置

增强安全性，限制 Claude Code 的系统访问：

{
  "sandbox": {
    "enabled": true,
    "allowedPaths": [
      "/home/user/projects"
    ],
    "deniedPaths": [
      "/etc",
      "/var",
      "~/.ssh"
    ],
    "allowNetwork": true,
    "allowedDomains": [
      "api.anthropic.com",
      "github.com"
    ]
  }
}

3.4 Hooks 系统

Hooks 允许在特定事件发生时执行自定义脚本，实现自动化工作流。

Hook 事件类型
事件 触发时机 可用匹配器
PreToolUse 工具执行前 工具名称（Bash, Read, Edit 等）
PostToolUse 工具执行后 工具名称
PermissionRequest 权限对话框显示时 工具名称
Notification 发送通知时 通知类型
UserPromptSubmit 用户提交提示时 无
Stop 主代理完成响应时 无
SessionStart 会话开始时 startup 或 resume
SessionEnd 会话结束时 退出原因
Hook 配置示例

1. 文件编辑后自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": ["./.claude/hooks/format.sh"]
      }
    ]
  }
}

format.sh:

#!/bin/bash
# 获取编辑的文件路径
FILE_PATH="$CLAUDE_TOOL_INPUT_file_path"

# 根据文件类型格式化
case "$FILE_PATH" in
  *.js|*.jsx|*.ts|*.tsx)
    npx prettier --write "$FILE_PATH"
    ;;
  *.py)
    black "$FILE_PATH"
    ;;
  *.go)
    gofmt -w "$FILE_PATH"
    ;;
esac

2. 阻止危险命令

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["./.claude/hooks/check-dangerous.sh"]
      }
    ]
  }
}

check-dangerous.sh:

#!/bin/bash
COMMAND="$CLAUDE_TOOL_INPUT_command"

# 检查危险命令
if echo "$COMMAND" | grep -qE "(rm -rf /|sudo|curl.*|.*bash|> /dev/)"; then
  echo "ERROR: 检测到危险命令，已阻止执行"
  exit 2  # exit 2 阻止工具执行
fi

exit 0  # 允许执行

3. 会话启动时设置环境

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": ["./.claude/hooks/init-env.sh"]
      }
    ]
  }
}

init-env.sh:

#!/bin/bash
# 检查项目依赖
if [ -f "package.json" ] && [ ! -d "node_modules" ]; then
  echo "检测到缺少依赖，正在安装..."
  npm install
fi

# 加载环境变量
if [ -f ".env.local" ]; then
  export $(cat .env.local | grep -v '^#' | xargs)
fi

echo "环境初始化完成"

4. 提交前检查

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit *)",
        "hooks": ["./.claude/hooks/pre-commit-check.sh"]
      }
    ]
  }
}

pre-commit-check.sh:

#!/bin/bash
# 运行 lint 检查
npm run lint
if [ $? -ne 0 ]; then
  echo "ERROR: Lint 检查失败，请修复后再提交"
  exit 2
fi

# 运行测试
npm test -- --passWithNoTests
if [ $? -ne 0 ]; then
  echo "ERROR: 测试失败，请修复后再提交"
  exit 2
fi

exit 0
Hook 环境变量

Hook 脚本可访问以下环境变量：

变量 说明
CLAUDE_SESSION_ID 当前会话 ID
CLAUDE_TOOL_NAME 触发的工具名称
CLAUDE_TOOL_INPUT_* 工具输入参数（如 CLAUDE_TOOL_INPUT_command）
CLAUDE_TOOL_RESULT 工具执行结果（仅 PostToolUse）
Hook 返回值
返回值 含义
0 成功，继续执行
1 成功，但显示警告
2 阻止操作并显示错误

第4章：编辑模式与计划模式

本章介绍 Claude Code 的不同权限模式，重点讲解计划模式的使用场景和工作流程。

4.1 权限模式概览

Claude Code 提供三种权限模式，适用于不同的开发场景：

Normal Mode → Auto-Accept Mode → Plan Mode
     ↑                                  │
     └──────────────────────────────────┘
           (按 Shift+Tab 循环切换)
模式 快捷键 特点 适用场景
Normal - 每次操作需确认 日常开发、学习新代码库
Auto-Accept Shift+Tab 一次 自动接受编辑 批量重构、信任的自动化任务
Plan Shift+Tab 两次 只读，生成计划 复杂任务规划、架构设计

4.2 计划模式 (Plan Mode)

计划模式是一种只读模式，Claude 会探索代码库并制定详细的实施计划，然后请求您的批准。

何时使用计划模式
场景 说明
多步实现 功能需要修改多个文件，需要协调变更
代码探索 在更改前需要彻底研究代码库结构和依赖
交互式开发 与 Claude 讨论方案方向，迭代细化需求
架构决策 需要评估多种实现方案的技术决策
团队协作 需要向团队成员展示详细的实施计划
启用计划模式

方式一：会话中切换

按 Shift+Tab 两次，进入计划模式

方式二：启动时指定

claude --permission-mode plan

方式三：Headless 模式

claude --permission-mode plan -p "分析认证系统并提出改进建议"
计划模式工作流程
┌─────────────────────────────────────────────────────────────┐
│                     计划模式工作流程                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 进入计划模式                                             │
│     └─→ Claude 进入只读状态                                  │
│                                                             │
│  2. 探索代码库                                               │
│     └─→ 使用 Explore Agent 搜索和分析代码                    │
│     └─→ 只读操作：Read, Grep, Glob                          │
│                                                             │
│  3. 制定计划                                                 │
│     └─→ 创建详细的实施计划文件                               │
│     └─→ 列出需要修改的文件和步骤                             │
│                                                             │
│  4. 用户审查                                                 │
│     └─→ 展示计划内容                                         │
│     └─→ 用户提问、修改、批准                                 │
│                                                             │
│  5. 执行计划                                                 │
│     └─→ 切换到 Normal Mode                                   │
│     └─→ 按计划逐步执行                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
计划模式最佳实践

1. 先规划后执行

用户: 帮我重构用户认证模块

Claude (计划模式):
我将探索认证模块的代码结构，然后制定重构计划...

[探索代码...]

## 重构计划

### 当前状态分析
- 文件：`src/auth/`
- 主要组件：AuthService, TokenManager, SessionStore
- 发现的问题：...

### 实施步骤
1. 重构 AuthService 为策略模式
2. 迁移 TokenManager 到 Redis
3. 添加单元测试
4. 更新 API 文档

是否批准此计划？

2. 记录决策

  • 在计划中记录关键决策和理由
  • 方便团队成员理解设计意图
  • 为未来的维护提供上下文

3. 迭代细化

  • 不要期望一次性制定完美计划
  • 允许在执行过程中调整
  • 保持计划的灵活性

4. 让 Claude 采访你

Claude (计划模式):
在制定计划之前，我需要了解一些信息：

1. 这个功能的主要用户是谁？
2. 预期的并发量是多少？
3. 是否需要向后兼容现有 API？
4. 有哪些技术限制？

请回答这些问题，我会据此制定更准确的计划。

4.3 编辑模式

编辑模式是 Claude Code 的核心功能，通过 Edit 工具实现精准的代码修改。

Edit 工具使用

基本参数：

  • file_path: 要编辑的文件路径
  • old_string: 要替换的原始文本（必须精确匹配）
  • new_string: 替换后的新文本

示例：

用户: 将函数名 getUserById 改为 fetchUserById

Claude:
我将编辑 `src/services/userService.ts` 文件：

--- a/src/services/userService.ts
+++ b/src/services/userService.ts
@@ -10,7 +10,7 @@
-export async function getUserById(id: string) {
+export async function fetchUserById(id: string) {
   return await db.users.findUnique({ where: { id } });
 }
精确匹配要求

Edit 工具要求 old_string 必须与文件内容完全匹配：

✅ 正确：精确匹配，包括空格和缩进
❌ 错误：模糊匹配或部分匹配

匹配失败示例：

文件内容：
  function hello() {
    console.log("Hello");
  }

old_string:
function hello() {
  console.log("Hello");
}
# 结果：匹配失败（缩进不一致）
检查点机制

Claude Code 自动创建检查点，支持回滚：

回滚最近更改： 按 Esc+Esc

查看更改历史：

# 在会话中
> /history

4.4 Agent 工具与 Subagents

Claude Code 可以委派任务给专门的子代理（Subagents），以隔离上下文或并行处理任务。

Subagent 类型
类型 模型 用途 访问工具
Explore Haiku 只读代码探索 Read, Grep, Glob, WebFetch
Plan 继承父模型 制定实施计划 只读工具
general-purpose 默认模型 通用任务 所有工具
Bash - 执行后台命令 Bash
何时使用 Subagent
场景 推荐 Agent 原因
搜索代码定义 Explore 快速、低成本
分析代码结构 Explore 隔离上下文
制定复杂计划 Plan 专注规划
并行搜索多个关键词 Explore × N 提高效率
后台运行测试 Bash 不阻塞主会话
使用示例

Explore Agent 示例：

用户: 找出项目中所有的 API 端点

Claude:
我将启动 Explore Agent 来搜索 API 端点定义...
[启动 Explore Agent]
找到 23 个 API 端点，分布在以下文件中...

并行探索示例：

用户: 同时搜索 Authentication 和 Authorization 相关代码

Claude:
我将并行启动两个 Explore Agent：
- Agent 1: 搜索 Authentication 相关代码
- Agent 2: 搜索 Authorization 相关代码
[并行执行]

4.5 模式选择指南

任务类型 推荐模式 说明
简单查询 Normal 直接问答，无需计划
单文件编辑 Normal 快速修改，即时反馈
多文件重构 Plan → Normal 先规划再执行
新功能开发 Plan → Normal 理解需求，规划架构
Bug 调试 Normal 快速迭代尝试
代码审查 Plan 只读分析，提出建议
批量操作 Auto-Accept 信任的自动化任务

第5章：Skills 功能与自定义

Skills 是 Claude Code 的扩展机制，允许您创建可复用的"工具箱"，为 Claude 提供专业知识和工作流程。

5.1 Skills 概念

什么是 Skill

Skill 是一个包含特定知识和指令的 SKILL.md 文件。当 Claude 判断需要某种专业知识时，会自动加载对应的 Skill 内容作为上下文。

┌─────────────────────────────────────────────────────────────┐
│                    Skill 工作原理                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  用户请求 ──→ Claude 分析意图 ──→ 匹配 Skill description     │
│                                      │                      │
│                                      ▼                      │
│                              加载 SKILL.md 内容              │
│                                      │                      │
│                                      ▼                      │
│                              按照 Skill 指令执行             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
Skills 的特点
特点 说明
可复用 一次创建，多处使用
可共享 通过 Git 与团队共享
上下文隔离 可在子代理中运行，不影响主会话
动态注入 支持执行命令并注入输出
触发控制 可控制由谁触发（用户或 Claude）

5.2 内置 Bundled Skills

Claude Code 自带以下内置 Skills：

Skill 命令 用途
batch /batch <plan> 并行执行大规模代码变更
claude-api /claude-api Claude API 使用参考
debug /debug [description] 会话调试和分析
loop /loop [interval] <prompt> 循环执行提示词
simplify /simplify [focus] 代码审查和简化
内置 Skill 使用示例

/batch - 并行批量变更：

用户: /batch 在所有组件文件中添加错误边界

Claude:
我将分析所有组件文件，然后并行执行变更...
找到 15 个组件文件需要修改
正在并行处理...
完成：15 个文件已更新

/simplify - 代码审查：

用户: /simplify src/utils/

Claude:
我将审查 src/utils/ 目录中的代码，寻找简化机会...

## 审查报告

### 可简化的代码
1. `formatDate.ts` - 可使用 Intl.DateTimeFormat 替代手动格式化
2. `validation.ts` - 存在重复的验证逻辑，可提取公共函数

### 建议
- 合并相似的工具函数
- 移除未使用的导出

5.3 创建自定义 Skill

Skill 文件位置
位置 路径 适用范围
个人 ~/.claude/skills/<name>/SKILL.md 您的所有项目
项目 .claude/skills/<name>/SKILL.md 仅当前仓库
插件 <plugin>/skills/<name>/SKILL.md 启用插件时
SKILL.md 基本结构
---
name: my-skill
description: 简短描述这个 Skill 的用途（Claude 用此判断何时使用）
---

# Skill 标题

这里写具体的指令和知识内容...

## 示例部分

具体的使用示例...
完整 Skill 示例

示例 1：代码解释 Skill

---
name: explain-code
description: 用"类比 + ASCII 图"的方式解释复杂代码逻辑
allowed-tools: Read, Grep
---

# 代码解释助手

当解释代码时，始终遵循以下结构：

## 1. 类比开头

将代码比作日常生活中的事物，帮助理解：

**示例：**
- API 网关 → 餐厅前台服务员
- 缓存系统 → 便利贴
- 消息队列 → 邮局信箱

## 2. ASCII 流程图

使用 ASCII 艺术展示代码执行流程：

┌─────────┐ ┌─────────┐ ┌─────────┐
│ 请求 │ ──→ │ 处理 │ ──→ │ 响应 │
└─────────┘ └─────────┘ └─────────┘


## 3. 关键点说明

列出代码的关键行为和注意事项。

示例 2：API 文档生成 Skill

---
name: api-docs
description: 为 API 端点生成标准化文档
allowed-tools: Read, Grep, Write
---

# API 文档生成器

## 文档模板

为每个 API 端点生成以下格式的文档：

### `METHOD /path`

**描述：** [简短描述]

**请求参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ... | ... | ... | ... |

**请求示例：**
​```json
{
  "example": "request"
}

响应示例：

{
  "example": "response"
}

错误码：

状态码 说明
400 请求参数错误
401 未授权
500 服务器错误 

**示例 3：安全审查 Skill**

​```yaml
---
name: security-review
description: 审查代码中的安全漏洞（SQL注入、XSS、敏感信息泄露等）
allowed-tools: Read, Grep
---

# 安全审查清单

审查以下安全问题：

## 1. 注入漏洞
- [ ] SQL 查询是否使用参数化
- [ ] 用户输入是否经过清理
- [ ] 是否存在命令注入风险

## 2. 认证与授权
- [ ] 敏感操作是否验证权限
- [ ] 密码是否正确哈希存储
- [ ] Session 管理是否安全

## 3. 敏感信息
- [ ] 是否有硬编码的密钥或密码
- [ ] 错误信息是否泄露内部细节
- [ ] 日志是否记录敏感数据

## 4. XSS 和 CSRF
- [ ] 用户输入是否正确转义
- [ ] 是否有 CSRF Token 保护

输出格式：
- 🔴 高危：需要立即修复
- 🟡 中危：建议修复
- 🟢 低危：可选修复

5.4 Frontmatter 字段详解

字段 类型 必填 说明
name string ✅ Skill 名称，用于调用
description string 推荐 描述 Skill 用途，Claude 用此判断何时使用
disable-model-invocation boolean ❌ 设为 true 后只能通过 /skill-name 手动触发
user-invocable boolean ❌ 设为 false 后从用户菜单隐藏
allowed-tools string[] ❌ 免确认可用的工具列表
context string ❌ 设为 fork 在子代理中运行
agent string ❌ 指定子代理类型（与 context: fork 配合）

5.5 高级模式

动态上下文注入

使用 !command`` 语法执行命令并注入输出：

---
name: pr-summary
description: 生成 PR 变更摘要
context: fork
agent: Explore
---

## PR 上下文信息

### 变更文件
!`git diff --name-only HEAD~1`

### 变更统计
!`git diff --stat HEAD~1`

### 最近提交
!`git log -1 --pretty=format:"%h - %s (%an)"`

请基于以上信息生成 PR 描述摘要。
在子代理中运行

使用 context: fork 隔离 Skill 执行上下文：

---
name: analyze-deps
description: 分析项目依赖关系
context: fork
agent: Explore
---

分析 package.json 中的依赖：
1. 列出所有依赖及其版本
2. 检查过时的依赖
3. 识别潜在的安全漏洞
4. 建议更新策略
字符串替换变量

在 Skill 内容中使用变量：

变量 说明
$ARGUMENTS 调用 Skill 时传入的参数
${CLAUDE_SESSION_ID} 当前会话 ID 
---
name: search-code
description: 在代码中搜索关键词
---

搜索关键词：`$ARGUMENTS`

请搜索代码库中所有包含 "$ARGUMENTS" 的位置，并报告：
- 匹配的文件数量
- 每个文件中的匹配位置
- 相关的上下文

使用方式：

/search-code authenticate
# $ARGUMENTS 会被替换为 "authenticate"

5.6 控制 Skill 触发

配置 用户可调用 Claude 可调用 说明
默认 ✅ ✅ 两种方式都可触发
disable-model-invocation: true ✅ ❌ 只能用户手动调用
user-invocable: false ❌ ✅ 只能 Claude 自动触发

示例：只能手动触发的 Skill

---
name: deploy
description: 部署到生产环境
disable-model-invocation: true
allowed-tools: Bash(npm run deploy)
---

# 部署流程

执行生产环境部署：

1. 运行测试
2. 构建生产版本
3. 部署到服务器

5.7 Skills vs 其他功能对比

使用场景 推荐选择 原因
给 Claude 专业知识 Skills 可复用、可共享
设置项目级指令 CLAUDE.md 自动加载，适合通用规则
委派任务到独立上下文 Subagents 适合隔离执行
事件触发脚本 Hooks 适合自动化工作流
连接外部工具和数据源 MCP 适合实时数据访问

第6章：MCP Server 概念与使用

本章介绍 Model Context Protocol (MCP) 的概念，以及如何通过 MCP Server 扩展 Claude Code 的能力。

6.1 MCP 概念

什么是 MCP

Model Context Protocol (MCP) 是一个开源的 AI-工具集成标准，由 Anthropic 推动。通过 MCP，Claude Code 可以连接到各种外部工具和数据源，获得实时信息访问能力。

┌─────────────────────────────────────────────────────────────┐
│                    MCP 架构图                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐ │
│  │ Claude Code │ ←──→ │ MCP Client  │ ←──→ │ MCP Server  │ │
│  └─────────────┘      └─────────────┘      └─────────────┘ │
│                                                   │         │
│                                                   ▼         │
│                                          ┌─────────────┐   │
│                                          │ 外部资源    │   │
│                                          │ • GitHub    │   │
│                                          │ • Sentry    │   │
│                                          │ • Database  │   │
│                                          │ • Figma     │   │
│                                          └─────────────┘   │
└─────────────────────────────────────────────────────────────┘
MCP 能做什么
能力 示例场景
问题跟踪 从 JIRA、GitHub Issues 获取任务详情，实现功能
错误监控 从 Sentry 获取错误报告，分析并修复 Bug
数据库查询 直接查询 PostgreSQL、MySQL，分析数据
设计工具 从 Figma 获取设计规范，实现 UI 组件
文档系统 从 Confluence、Notion 获取文档内容
云服务 操作 AWS、GCP、Azure 资源

6.2 常见 MCP Servers

服务器 用途 传输方式 安装命令
GitHub GitHub API 集成，PR/Issue 管理 HTTP claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Sentry 错误监控和分析 HTTP claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
PostgreSQL 数据库查询 Stdio claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://..."
MySQL 数据库查询 Stdio claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "mysql://..."
Google Drive 文件管理 HTTP claude mcp add --transport http gdrive https://mcp.gdrive.example.com/mcp
Slack 消息发送 HTTP 需配置 OAuth

6.3 安装与配置

传输方式

MCP Server 支持两种传输方式：

HTTP（远程服务器）：

claude mcp add --transport http <name> <url>

Stdio（本地进程）：

claude mcp add --transport stdio <name> -- <command> [args...]
安装范围
范围 参数 存储位置 用途
Local 默认 ~/.claude.json 仅当前项目
Project --scope project .mcp.json 通过 Git 共享给团队
User --scope user ~/.claude.json 跨所有项目
配置文件格式

.mcp.json 示例：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://localhost/mydb"]
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

6.4 管理命令

列出已安装的服务器
claude mcp list

输出示例：

Name      Type    Status    Scope
────────────────────────────────────
github    http    ✓ 已连接   project
sentry    http    ✓ 已连接   user
database  stdio   ✗ 离线     local
获取服务器详情
claude mcp get <name>
移除服务器
claude mcp remove <name>
会话内检查状态

在 Claude Code 会话中使用：

> /mcp

这将显示所有 MCP 服务器的连接状态和可用工具。

6.5 企业级配置

managed-mcp.json

企业可以完全控制可用的 MCP 服务器：

位置：

  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux: /etc/claude-code/managed-mcp.json
  • Windows: C:\Program Files\ClaudeCode\managed-mcp.json

配置示例：

{
  "mcpServers": {
    "internal-jira": {
      "type": "http",
      "url": "https://jira.company.com/mcp"
    },
    "internal-docs": {
      "type": "http",
      "url": "https://docs.company.com/mcp"
    }
  },
  "allowlists": {
    "allow": ["internal-jira", "internal-docs"],
    "deny": ["*"]
  }
}
Allowlists/Denylists

控制允许使用的 MCP 服务器：

{
  "mcpAllowlists": {
    "allow": [
      "github",
      "sentry",
      "internal-*"
    ],
    "deny": [
      "personal-*",
      "external-*"
    ]
  }
}

6.6 实际场景示例

场景1：Sentry 错误监控

安装：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

认证：

> /mcp
选择 sentry 进行认证...

使用示例：

用户: 过去24小时最常见的错误是什么？

Claude:
让我查询 Sentry 中的错误数据...

## 过去24小时错误报告

### Top 5 错误

1. **TypeError: Cannot read property 'id' of undefined**
   - 出现次数：1,234 次
   - 影响用户：567 人
   - 文件：src/components/UserProfile.tsx:45

2. **NetworkError: Request timeout**
   - 出现次数：892 次
   - 影响用户：234 人
   - API：/api/users/profile

建议优先修复第一个错误，它影响了最多用户。

修复示例：

用户: 帮我修复 UserProfile.tsx 中的错误

Claude:
我来分析这个错误并修复...
[读取文件]
[分析代码]
问题在于 user 对象可能为 null 时直接访问 user.id。
已修复：添加了空值检查。
场景2：GitHub 代码审查

安装：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

使用示例：

用户: 审查 PR #456 并提出改进建议

Claude:
让我获取 PR #456 的详细信息...

## PR #456: 添加用户认证功能

### 变更摘要
- 新增文件：5 个
- 修改文件：12 个
- 删除文件：2 个

### 代码审查意见

**🔴 必须修复：**
1. `src/auth/login.ts:45` - 密码未使用 bcrypt 哈希
2. `src/middleware/auth.ts:23` - Token 过期时间硬编码

**🟡 建议改进：**
1. 添加输入验证
2. 使用环境变量存储密钥

**🟢 良好实践：**
1. 错误处理完善
2. 有适当的日志记录
场景3：PostgreSQL 数据库查询

安装：

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb"

使用示例：

用户: 本月的总收入是多少？

Claude:
让我查询数据库...

## 本月收入报告

| 指标 | 数值 |
|------|------|
| 总收入 | ¥1,234,567 |
| 订单数 | 8,901 |
| 平均订单金额 | ¥138.70 |

### 按产品分类

| 产品 | 收入 | 占比 |
|------|------|------|
| 产品A | ¥456,789 | 37% |
| 产品B | ¥345,678 | 28% |
| 产品C | ¥432,100 | 35% |
场景4：结合多个 MCP Server
用户: 分析最近一周的用户投诉，并创建修复任务

Claude:
我将综合使用多个数据源...

1. 从 Sentry 获取相关错误...
2. 从数据库查询受影响的用户...
3. 在 GitHub 创建 Issue...

## 分析报告

### 错误统计（Sentry）
- 相关错误：15 个
- 影响用户：2,345 人

### 用户反馈（数据库）
- 投诉数量：89 条
- 主要问题：登录失败、页面加载慢

### 创建的任务（GitHub）
- Issue #123: 修复登录超时问题
- Issue #124: 优化页面加载性能
- Issue #125: 添加错误监控告警

6.7 MCP 最佳实践

实践 说明
使用环境变量 敏感信息（Token、DSN）使用环境变量
限制权限 数据库连接使用只读账户
监控使用量 定期检查 API 调用量
错误处理 处理 MCP 服务器不可用的情况
团队共享 使用 .mcp.json 共享配置

第7章：最佳实践与常见问题

本章汇总 Claude Code 的最佳实践、常见问题解决方案和安全建议。

7.1 项目初始化检查清单

在开始使用 Claude Code 的项目时，按以下清单检查配置：

基础配置
  • 运行 /init 命令生成 CLAUDE.md
  • CLAUDE.md 包含项目概述和技术栈
  • CLAUDE.md 包含构建命令（npm run build 等）
  • CLAUDE.md 包含测试命令（npm test 等）
  • CLAUDE.md 包含代码风格指南
权限与安全
  • 创建 .claude/settings.json 配置团队规则
  • 敏感文件被 deny 规则阻止（如 .env*）
  • 危险命令被 deny 规则阻止（如 rm -rf /*）
  • settings.local.json 已添加到 .gitignore
  • CLAUDE.local.md 已添加到 .gitignore
团队协作
  • .claude/rules/ 目录包含项目规则
  • 规则文件使用正确的 globs 匹配器
  • 共享的 Skills 已添加到 .claude/skills/
  • MCP 配置已添加到 .mcp.json（如需要）
Git 配置
# 添加到 .gitignore
.claude/settings.local.json
CLAUDE.local.md
.claude/history/

# 可选
.env.local
.env.*.local

7.2 上下文管理最佳实践

做法 原因 示例
任务开始前运行 /init 确保 Claude 了解项目结构 新项目首次使用时
任务完成后使用 /clear 避免上下文污染 完成一个功能后
明确指定相关文件 减少 Claude 的搜索时间 “修改 src/auth/login.ts”
分阶段提供上下文 避免一次性信息过载 先讲需求，再讲实现
使用 @path 导入 保持 CLAUDE.md 简洁 @./docs/api.md
上下文管理示例

不好的做法：

用户: 帮我改一下那个登录的东西

Claude: 我需要更多信息...
- 哪个登录相关的文件？
- 要修改什么内容？
- 有什么具体需求？

好的做法：

用户: 修改 src/auth/LoginForm.tsx，添加"记住我"复选框功能，
     勾选后登录状态保持30天。参考 src/auth/types.ts 中的类型定义。

Claude: 我理解了，我将：
1. 读取 LoginForm.tsx 了解当前实现
2. 读取 types.ts 了解类型定义
3. 添加"记住我"复选框
4. 实现持久化登录逻辑

7.3 常见问题解决

CLAUDE.md 相关

问题：Claude 没有遵循 CLAUDE.md 中的指令

可能原因和解决方案：

原因 解决方案
文件位置错误 确保放在项目根目录
格式问题 检查 Markdown 格式是否正确
指令太模糊 使用更具体、可操作的指令
冲突的配置 检查是否有多个配置文件冲突

问题：修改 CLAUDE.md 后不生效

解决方案：

> /clear    # 清除当前上下文
> /init     # 重新初始化
Skills 相关

问题：Skill 不触发

检查项：

  • description 是否足够具体，让 Claude 能判断何时使用
  • 文件路径是否正确
  • YAML frontmatter 语法是否正确
  • disable-model-invocation 是否设为 true

问题：Skill 不加载

检查项：

  • 文件名是否为 SKILL.md（大写）
  • 目录结构是否正确
  • YAML 语法是否有效（使用在线验证器检查）
MCP 相关

问题：MCP 服务器连接失败

# 检查状态
claude mcp list

# 查看详情
claude mcp get <name>

# 重新添加
claude mcp remove <name>
claude mcp add ...

问题：认证失败

  • HTTP 服务器：检查 /mcp 进行认证
  • 检查环境变量是否正确设置
  • 检查 Token 是否过期
编辑相关

问题：Edit 工具匹配失败

常见原因：

  • 空格/缩进不一致
  • 换行符不同（CRLF vs LF）
  • 文件内容已变更

解决方案：

用户: Edit 匹配失败

Claude: 让我重新读取文件获取最新内容...
[读取文件]
现在我有了准确的内容，让我再次尝试编辑...

7.4 安全建议

1. 验证输入

在 Hooks 中验证 Claude 的操作：

#!/bin/bash
# pre-tool-check.sh

TOOL_NAME="$CLAUDE_TOOL_NAME"
COMMAND="$CLAUDE_TOOL_INPUT_command"

# 记录所有操作（审计）
echo "$(date): $TOOL_NAME - $COMMAND" >> ~/.claude/audit.log

# 验证危险模式
if echo "$COMMAND" | grep -qE "(rm -rf|sudo|curl.*bash|eval)"; then
  echo "ERROR: 检测到危险命令模式"
  exit 2
fi

exit 0
2. 避免硬编码密钥

不要这样：

{
  "env": {
    "API_KEY": "sk-xxxxx"  // ❌ 危险
  }
}

应该这样：

{
  "env": {
    "API_KEY": "${API_KEY}"  // ✅ 使用环境变量
  }
}
3. 限制文件访问
{
  "permissions": {
    "deny": [
      "Read(**/.env*)",
      "Read(**/credentials*)",
      "Read(**/secrets/**)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(~/.ssh/**)"
    ]
  }
}
4. 使用 exit 2 阻止危险操作

在 Hooks 中使用 exit 2 可以阻止工具执行：

#!/bin/bash
# block-dangerous.sh

if [ "$CLAUDE_TOOL_NAME" = "Bash" ]; then
  CMD="$CLAUDE_TOOL_INPUT_command"

  # 阻止删除命令
  if echo "$CMD" | grep -q "rm -rf"; then
    echo "ERROR: rm -rf 命令已被阻止"
    exit 2  # 阻止执行
  fi

  # 阻止特权命令
  if echo "$CMD" | grep -q "sudo"; then
    echo "ERROR: sudo 命令已被阻止"
    exit 2  # 阻止执行
  fi
fi

exit 0  # 允许执行
5. 定期审查权限
# 查看当前配置
cat .claude/settings.json | grep -A 20 "permissions"

# 检查危险权限
grep -r "allow.*rm\|allow.*sudo" .claude/

7.5 性能优化建议

建议 说明
使用 Haiku 模型进行简单查询 更快、更便宜
限制 @path 导入的文件大小 避免上下文膨胀
定期使用 /compact 压缩历史 保持会话高效
使用 Explore Agent 并行搜索 加速代码探索
缓存 MCP 查询结果 减少 API 调用

7.6 团队协作建议

共享配置
项目根目录/
├── CLAUDE.md              # 提交到 Git
├── .mcp.json              # 提交到 Git（不含密钥）
└── .claude/
    ├── settings.json      # 提交到 Git
    ├── rules/             # 提交到 Git
    │   └── *.md
    └── skills/            # 提交到 Git
        └── */SKILL.md
不共享的配置
# 添加到 .gitignore
.claude/settings.local.json
CLAUDE.local.md
.env.*
代码审查清单

使用 Claude 进行代码审查时：

  • 让 Claude 解释变更的原因
  • 检查是否有安全风险
  • 验证测试覆盖
  • 检查是否遵循项目规范
  • 评估性能影响

附录

快速参考卡

常用命令
命令 说明
claude 启动 Claude Code
claude --model opus 使用 Opus 模型
claude --permission-mode plan 以计划模式启动
/init 初始化项目
/clear 清除上下文
/mcp 管理 MCP 服务器
/help 显示帮助
Shift+Tab 切换权限模式
Esc+Esc 回滚更改
配置文件位置
文件 位置 用途
CLAUDE.md 项目根目录 项目指令
settings.json .claude/ 团队设置
settings.local.json .claude/ 个人设置
.mcp.json 项目根目录 MCP 配置
权限模式
模式 说明
default 标准确认模式
acceptEdits 自动接受编辑
plan 只读计划模式

参考资源

文档版本：1.0
最后更新：2026年3月

# python
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

AI + 渗透测试开源项目调研报告

基于AI的开源渗透项目调研分析

avatar AtomGit开源社区
cover

带你轻松学习LangChain4j

avatar AtomGit开源社区
cover

项目介绍 MATLAB实现基于ACO-BFOA 蚁群算法（ACO）结合细菌觅食优化算法（BFOA）进行无人机三维路径规划（含模型描述及部分示例代码） 还请多多点一下关注 加油 谢谢 你的鼓励是我前行的

avatar AtomGit开源社区