claude_code完整功能手册

Claude Code 完整功能手册

Claude Code 是 Anthropic 官方推出的 AI 驱动命令行编程助手

目录

1. 简介与安装
2. 命令行参数
3. 斜杠命令详解
4. 自定义技能系统
5. MCP 服务器配置
6. Hooks 钩子系统
7. 权限与安全
8. 会话管理
9. 配置系统详解
10. 插件系统
11. IDE 集成
12. 键盘快捷键
13. 高级功能
14. 故障排查
15. 最佳实践

1. 简介与安装

什么是 Claude Code？

Claude Code 是基于 Claude 大语言模型的智能命令行编程助手，可以帮助你：

• 编写、调试、重构代码
• 理解和探索代码库
• 执行复杂的软件工程任务
• 自动化开发工作流
• 与 Git、GitHub 深度集成
• 通过 MCP 连接外部工具和数据源

系统要求

• Node.js 18+ 或 Bun
• macOS、Linux 或 Windows (WSL2)
• 终端模拟器（推荐支持 24-bit 色彩）

安装方式

# 使用 npm 安装（推荐）
npm install -g @anthropic-ai/claude-code

# 使用 yarn
yarn global add @anthropic-ai/claude-code

# 使用 bun
bun install -g @anthropic-ai/claude-code

首次配置

# 启动并登录
claude

# 使用 API 密钥
export ANTHROPIC_API_KEY="your-api-key"
claude

目录结构

~/.claude/
├── settings.json          # 全局配置
├── settings.local.json    # 本地配置（不同步）
├── CLAUDE.md              # 全局指令文件
├── commands/              # 全局自定义命令
├── hooks/                 # 全局钩子
└── mcp/                   # MCP 服务器日志

.claude/                   # 项目级配置
├── settings.json          # 项目配置
├── settings.local.json    # 项目本地配置
├── commands/              # 项目自定义命令
└── hooks/                 # 项目钩子

2. 命令行参数

基本用法

claude [选项] [提示词]

主要子命令

常用选项

配置子命令

# 查看所有配置
claude config list

# 获取配置值
claude config get model

# 设置配置值
claude config set model opus

# 重置配置
claude config reset

MCP 子命令

# 列出 MCP 服务器
claude mcp list

# 添加 MCP 服务器
claude mcp add <name> <command> [args...]

# 删除 MCP 服务器
claude mcp remove <name>

# 测试 MCP 服务器
claude mcp test <name>

会话管理

# 列出历史会话
claude --list

# 继续上次会话
claude -c

# 恢复特定会话
claude -r <session-id>

# 清理历史会话
claude --clean

输入方式

# 从标准输入读取
echo "解释这段代码" | claude -p

# 从文件读取
claude -p < prompt.txt

# 多行输入（heredoc）
claude -p <<EOF
请帮我：
1. 检查代码错误
2. 优化性能
EOF

输出格式

# 文本格式（默认）
claude -p "..." --output-format text

# JSON 格式
claude -p "..." --output-format json

# 流式 JSON
claude -p "..." --output-format stream-json

3. 斜杠命令详解

内置命令

命令详细说明

/agent - 启动子代理

> /agent <任务描述>

启动独立的子代理来处理复杂任务：

示例：

# 代码重构
> /agent 重构 src/utils 目录，提高代码可读性

# 添加测试
> /agent 为 API 模块添加完整的单元测试

# 性能分析
> /agent 分析项目性能瓶颈并提出优化建议

与普通对话的区别：

/init - 初始化项目

> /init

创建 CLAUDE.md 文件，包含：

• 项目简介
• 技术栈说明
• 目录结构
• 开发规范
• 常用命令

/review - 代码审查

> /review              # 审查当前分支变更
> /review PR#123       # 审查指定 PR

/security-review - 安全审查

> /security-review     # 扫描常见安全问题

检查项包括：

• SQL 注入
• XSS 跨站脚本
• 命令注入
• 敏感信息泄露
• 依赖漏洞

/model - 模型切换

> /model opus          # 切换到 Opus（最强）
> /model sonnet        # 切换到 Sonnet（平衡）
> /model haiku         # 切换到 Haiku（快速）

/compact - 上下文压缩

> /compact             # 压缩当前对话上下文

当对话过长时使用，保留关键信息，减少 token 消耗。

/memory - 记忆管理

> /memory              # 查看记忆
> /memory add "..."    # 添加记忆
> /memory clear        # 清除记忆

4. 自定义技能系统

技能（Skills）概述

技能是可复用的提示词模板，通过 .claude/commands/ 目录定义。

目录结构

.claude/
└── commands/
    ├── my-skill.md           # 调用方式: /my-skill
    └── folder/
        └── nested.md         # 调用方式: /folder:nested

技能文件格式

---
description: 技能的简短描述（可选）
---

# 技能提示词内容

你的提示词指令...

## 可用变量

$ARGUMENTS - 用户传入的参数
$SELECTION - 用户选中的代码（IDE 集成时）

变量系统

示例技能

代码重构技能

---
description: 重构选中的代码
---

请重构以下代码，遵循以下原则：
1. 提高可读性
2. 减少重复
3. 优化性能
4. 添加必要注释

代码：
$SELECTION

用户要求：
$ARGUMENTS

Git 提交技能

---
description: 生成规范的 Git 提交信息
---

请根据以下变更生成 Git 提交信息：

1. 使用 Conventional Commits 格式
2. 标题不超过 50 字符
3. 包含简短说明

变更说明：
$ARGUMENTS

技能交接（Handoff）

技能可以交接给另一个技能：

---
description: 分析并修复 bug
handoff: /fix-code
---

分析以下 bug 并准备修复方案：
$ARGUMENTS

分析完成后，交接给修复技能。

Speckit 工作流与 /agent 联动

Speckit 是一套完整的规范驱动开发工作流，通过 Handoffs 机制 实现技能间的自动联动。

Speckit 命令概览

完整工作流程

┌─────────────────────────────────────────────────────────────────┐
│                     Speckit 工作流程                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  /speckit.specify "实现用户认证功能"                              │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                                │
│  │  spec.md    │ ← 功能规范（WHAT & WHY）                        │
│  └──────┬──────┘                                                │
│         │ handoff                                               │
│         ▼                                                       │
│  /speckit.plan                                                  │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐         │
│  │  plan.md    │  │ research.md  │  │ data-model.md   │         │
│  │  技术计划    │  │ 技术调研      │  │ 数据模型        │         │
│  └──────┬──────┘  └──────────────┘  └─────────────────┘         │
│         │ handoff                                               │
│         ▼                                                       │
│  /speckit.tasks                                                 │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                                │
│  │  tasks.md   │ ← 可执行任务列表                                 │
│  └──────┬──────┘                                                │
│         │ handoff                                               │
│         ▼                                                       │
│  /speckit.implement                                             │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                                │
│  │  代码实现    │ ← 按任务顺序执行                                │
│  └─────────────┘                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Handoffs 机制详解

Handoffs 是技能间的自动交接机制，在技能文件头部定义：

---
description: 创建功能规范
handoffs:
  - label: Build Technical Plan      # 按钮显示文本
    agent: speckit.plan              # 交接目标技能
    prompt: Create a plan for spec   # 交接时的提示
    send: true                       # 自动发送
  - label: Clarify Requirements
    agent: speckit.clarify
    prompt: Clarify specification
---

工作原理：

1. 当前技能执行完成后，Claude 会显示 Handoff 选项
2. 用户选择一个选项（如 “Build Technical Plan”）
3. 自动启动目标技能（speckit.plan）
4. 传递上下文和提示词给新技能

/agent 与 Speckit 联动

/agent 命令可以在 Speckit 工作流中启动子代理，实现并行处理：

场景 1：并行研究

# 在 /speckit.plan 阶段，启动多个研究代理
> /agent 研究 OAuth2 最佳实践
> /agent 研究 JWT vs Session 认证对比
> /agent 研究数据库索引优化策略

场景 2：并行实现

# 在 /speckit.implement 阶段，并行实现独立模块
> /agent 实现用户模型和数据库迁移
> /agent 实现认证中间件
> /agent 实现 API 端点

场景 3：并行测试

# 并行运行不同类型的测试
> /agent 运行单元测试并修复失败
> /agent 运行集成测试
> /agent 进行安全审查

实战示例：完整功能开发

# 步骤 1: 创建规范
> /speckit.specify 实现用户注册和登录功能，支持邮箱和手机号

# Claude 生成 spec.md 后，点击 "Build Technical Plan" 按钮
# 或手动执行：
> /speckit.plan

# 步骤 2: 并行研究（使用 /agent）
> /agent 研究密码加密最佳实践（bcrypt vs argon2）
> /agent 研究短信验证码服务商对比

# 步骤 3: 生成任务
> /speckit.tasks

# 步骤 4: 并行实现（使用 /agent）
> /agent 实现 Phase 1 的所有 Setup 任务
> /agent 实现 User 模型和数据库迁移

# 步骤 5: 执行实现
> /speckit.implement

# 步骤 6: 验证和分析
> /speckit.analyze

目录结构

Speckit 会在项目中创建以下结构：

specs/
└── 1-user-auth/              # 功能目录（自动创建分支）
    ├── spec.md               # 功能规范
    ├── plan.md               # 技术计划
    ├── tasks.md              # 任务列表
    ├── research.md           # 研究记录
    ├── data-model.md         # 数据模型
    ├── contracts/            # API 契约
    │   └── api.yaml
    └── checklists/           # 检查清单
        ├── requirements.md
        └── security.md

.specify/
├── memory/
│   └── constitution.md       # 项目宪法（编码规范）
├── templates/                # 模板文件
│   ├── spec-template.md
│   ├── plan-template.md
│   └── tasks-template.md
└── scripts/                  # 辅助脚本
    └── bash/
        ├── create-new-feature.sh
        └── setup-plan.sh

更多配合功能

1. /speckit.constitution - 项目宪法

在开始任何功能前，先定义项目的核心原则和规范：

# 创建/更新项目宪法
> /speckit.constitution 这是一个 Go 项目，要求：
  - 100% 测试覆盖率
  - 所有 API 需要文档
  - 使用 Clean Architecture

宪法内容包括：

• 编码规范（必须遵守的原则）
• 架构约束
• 测试要求
• 文档标准

与其他命令联动：

• speckit.plan 会检查计划是否违反宪法
• speckit.analyze 会验证所有产物符合宪法

2. /speckit.clarify - 智能需求澄清

在 specify 后、plan 前运行，减少歧义：

# 澄清规范中的模糊点
> /speckit.clarify

功能特点：

• 自动扫描 spec.md 中的模糊点
• 最多问 5 个高优先级问题
• 每个问题提供推荐答案
• 答案自动写回 spec.md

示例交互：

Q1: 用户认证应该使用哪种方式？

**推荐:** Option B - JWT（无状态，易于扩展）

| Option | Description |
|--------|-------------|
| A | Session-based（传统方式）|
| B | JWT（无状态）|
| C | OAuth2（第三方登录）|

回复 "yes" 接受推荐，或选择 A/B/C

3. /speckit.checklist - 需求质量检查清单

生成”需求的单元测试”，验证规范质量：

# 生成 UX 需求质量检查清单
> /speckit.checklist UX 相关的需求检查

# 生成安全需求检查清单
> /speckit.checklist 安全相关的需求

# 生成 API 需求检查清单
> /speckit.checklist API 设计质量

检查清单类型：

关键概念：检查的是需求质量，不是实现

❌ 错误: "验证按钮点击后跳转正确"
✅ 正确: "按钮点击后的跳转目标是否在需求中明确定义？"

4. /speckit.analyze - 一致性分析

在 tasks 生成后运行，检查所有文档的一致性：

> /speckit.analyze

检查内容：

• 需求是否都有对应任务
• 任务是否都有需求来源
• 术语是否一致
• 是否违反项目宪法
• 是否有冲突的需求

输出报告：

| ID | Category | Severity | Location | Summary |
|----|----------|----------|----------|---------|
| A1 | Gap | HIGH | spec.md | 需求 FR-5 没有对应任务 |
| C1 | Conflict | CRITICAL | plan.md | 与宪法原则冲突 |

5. /speckit.taskstoissues - 任务转 GitHub Issues

将 tasks.md 中的任务自动创建为 GitHub Issues：

> /speckit.taskstoissues

功能：

• 自动检测 Git 远程仓库
• 为每个任务创建 Issue
• 保留依赖关系
• 添加适当的 Labels

6. 与 GitHub MCP 深度集成

结合 GitHub MCP 服务器实现完整的项目管理：

# 创建功能分支（speckit.specify 自动执行）
# 创建 PR
> 为当前功能分支创建 PR

# 请求代码审查
> /review

# 安全审查
> /security-review

# 分配 Copilot 处理 Issue
> 让 Copilot 处理 Issue #123

7. 与 Memory MCP 集成

使用知识图谱存储项目知识：

# 存储架构决策
> 记住：我们选择 PostgreSQL 是因为需要复杂查询和事务支持

# 存储技术债务
> 记住：auth 模块需要重构，当前实现不支持 SSO

# 查询历史决策
> 我们为什么选择 PostgreSQL？

完整工作流示例（含所有配合功能）

# 1. 定义项目宪法（首次）
> /speckit.constitution 定义 Go 项目的编码规范和架构原则

# 2. 创建功能规范
> /speckit.specify 实现用户认证系统，支持邮箱登录和 OAuth2

# 3. 澄清需求（减少歧义）
> /speckit.clarify

# 4. 生成检查清单
> /speckit.checklist 安全相关需求
> /speckit.checklist API 设计质量

# 5. 创建技术计划
> /speckit.plan

# 6. 并行研究（使用 /agent）
> /agent 研究 Go 中 OAuth2 最佳实践
> /agent 研究 JWT 刷新令牌策略

# 7. 生成任务
> /speckit.tasks

# 8. 一致性分析
> /speckit.analyze

# 9. 创建 GitHub Issues（可选）
> /speckit.taskstoissues

# 10. 执行实现
> /speckit.implement

# 11. 代码审查
> /review
> /security-review

# 12. 创建 PR
> 创建 PR 并请求审查

配合功能速查表

最佳实践

1. 遵循工作流顺序：constitution → specify → clarify → checklist → plan → tasks → analyze → implement
2. 利用 Handoffs：让系统自动引导下一步
3. 使用 /agent 并行化：在研究和实现阶段启动多个代理
4. 定期运行 /speckit.analyze：确保各产物一致性
5. 善用 /speckit.clarify：在 specify 后澄清不明确的需求
6. 生成多维度检查清单：UX、API、安全、性能分别检查
7. 结合 GitHub MCP：实现完整的项目管理闭环
8. 记录决策到 Memory：保留架构决策的上下文

Hooks 与 Speckit/Agent 配合

Hooks 可以在 Speckit 工作流的关键节点自动触发，实现工作流自动化。

配置位置

.claude/
└── settings.json    # 项目级 hooks 配置

实用 Hooks 示例

1. 实现前验证检查清单

在 speckit.implement 执行前，确保所有检查清单已完成：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Skill",
        "command": "/path/to/verify-checklists.sh",
        "timeout": 10000
      }
    ]
  }
}

#!/bin/bash
# verify-checklists.sh - 检查清单验证

TOOL_INPUT="$CLAUDE_TOOL_INPUT"
SKILL_NAME=$(echo "$TOOL_INPUT" | jq -r '.skill // empty')

# 只在 speckit.implement 时检查
if [[ "$SKILL_NAME" == "speckit.implement" ]]; then
  CHECKLISTS_DIR="specs/*/checklists"

  # 查找未完成的检查项
  INCOMPLETE=$(grep -r "^\- \[ \]" $CHECKLISTS_DIR 2>/dev/null | wc -l)

  if [ "$INCOMPLETE" -gt 0 ]; then
    echo "⚠️ 发现 $INCOMPLETE 个未完成的检查项"
    echo "请先完成所有检查清单，或输入 'yes' 强制继续"
    exit 1  # 阻止执行
  fi

  echo "✅ 所有检查清单已完成"
fi
exit 0

2. 任务完成后自动运行分析

在 speckit.tasks 完成后自动运行一致性分析：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Skill",
        "command": "/path/to/auto-analyze.sh"
      }
    ]
  }
}

#!/bin/bash
# auto-analyze.sh - 自动分析

TOOL_INPUT="$CLAUDE_TOOL_INPUT"
SKILL_NAME=$(echo "$TOOL_INPUT" | jq -r '.skill // empty')

if [[ "$SKILL_NAME" == "speckit.tasks" ]]; then
  echo "📊 任务生成完成，建议运行 /speckit.analyze 进行一致性检查"
fi

3. 提交前运行测试

在 git commit 前确保测试通过：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "/path/to/pre-commit.sh"
      }
    ]
  }
}

#!/bin/bash
# pre-commit.sh - 提交前检查

CMD=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command // empty')

if [[ "$CMD" == *"git commit"* ]]; then
  echo "🧪 运行测试..."

  # 检测项目类型并运行测试
  if [ -f "go.mod" ]; then
    go test ./...
  elif [ -f "package.json" ]; then
    npm test
  elif [ -f "Cargo.toml" ]; then
    cargo test
  fi

  if [ $? -ne 0 ]; then
    echo "❌ 测试失败，阻止提交"
    exit 1
  fi

  echo "✅ 测试通过"
fi
exit 0

4. 长任务完成通知

当 /agent 或 speckit.implement 完成时发送通知：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Task",
        "command": "/path/to/notify-complete.sh"
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "command": "/path/to/desktop-notify.sh"
      }
    ]
  }
}

#!/bin/bash
# notify-complete.sh - 任务完成通知

# macOS 通知
osascript -e 'display notification "子代理任务已完成" with title "Claude Code" sound name "Glass"'

# 可选：发送到 Slack
# curl -X POST -H 'Content-type: application/json' \
#   --data '{"text":"Claude Code 任务完成"}' \
#   $SLACK_WEBHOOK_URL

5. 危险操作审计日志

记录所有写操作和 Bash 命令：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "command": "/path/to/audit-log.sh"
      }
    ]
  }
}

#!/bin/bash
# audit-log.sh - 审计日志

LOG_FILE="$HOME/.claude/speckit-audit.log"
TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")

echo "[$TIMESTAMP] Tool: $CLAUDE_TOOL_NAME" >> "$LOG_FILE"
echo "  Session: $CLAUDE_SESSION_ID" >> "$LOG_FILE"
echo "  Input: $CLAUDE_TOOL_INPUT" >> "$LOG_FILE"
echo "" >> "$LOG_FILE"

6. 实现阶段自动备份

在 speckit.implement 开始前创建备份：

#!/bin/bash
# backup-before-implement.sh

SKILL_NAME=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.skill // empty')

if [[ "$SKILL_NAME" == "speckit.implement" ]]; then
  BACKUP_DIR="$HOME/.claude/backups/$(date +%Y%m%d_%H%M%S)"
  mkdir -p "$BACKUP_DIR"

  # 备份源代码目录
  cp -r src "$BACKUP_DIR/" 2>/dev/null
  cp -r lib "$BACKUP_DIR/" 2>/dev/null

  echo "📦 已创建备份: $BACKUP_DIR"
fi
exit 0

Hooks 与工作流对应表

完整 Hooks 配置示例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Skill",
        "command": ".claude/hooks/pre-skill.sh",
        "timeout": 30000
      },
      {
        "matcher": "Bash",
        "command": ".claude/hooks/pre-bash.sh",
        "timeout": 60000
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Skill",
        "command": ".claude/hooks/post-skill.sh"
      },
      {
        "matcher": "Task",
        "command": ".claude/hooks/notify-agent-complete.sh"
      },
      {
        "matcher": "Write|Edit|Bash",
        "command": ".claude/hooks/audit-log.sh"
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "command": ".claude/hooks/desktop-notify.sh"
      }
    ]
  }
}

Hooks 最佳实践

1. 快速执行：Hooks 应该快速完成（<5秒），避免阻塞工作流
2. 优雅失败：非关键 hooks 应该 exit 0，只有关键验证才 exit 1
3. 清晰反馈：输出简短的状态消息，帮助用户理解发生了什么
4. 条件触发：使用 matcher 精确匹配，避免不必要的执行
5. 日志记录：重要操作写入日志文件，便于事后审计
6. 备份策略：在破坏性操作前自动备份

5. MCP 服务器配置

MCP 协议简介

Model Context Protocol (MCP) 是开放协议，让 Claude 连接外部工具和数据源。

配置文件位置

• 全局配置: ~/.claude/settings.json
• 项目配置: .claude/settings.json

基本配置格式

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "your-key"
      },
      "timeout": 30000,
      "disabled": false
    }
  }
}

官方 MCP 服务器

GitHub 服务器

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

功能：

• 仓库管理（创建、克隆、分支）
• Issue 和 PR 操作
• 代码搜索
• Actions 管理

文件系统服务器

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path1", "/allowed/path2"]
    }
  }
}

PostgreSQL 服务器

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

Brave Search 服务器

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Puppeteer 服务器

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

功能：

• 网页截图
• PDF 生成
• 网页自动化
• 表单填写

Memory 服务器

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

功能：

• 持久化知识存储
• 实体和关系管理
• 知识图谱查询

Slack 服务器

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "xoxb-your-token"
      }
    }
  }
}

社区 MCP 服务器

MCP 服务器管理

# 列出已配置的服务器
claude mcp list

# 添加新服务器
claude mcp add github npx -y @modelcontextprotocol/server-github

# 删除服务器
claude mcp remove github

# 测试服务器连接
claude mcp test github

6. Hooks 钩子系统

钩子概述

钩子允许在特定事件发生时执行自定义脚本。

钩子类型

配置格式

在 settings.json 中配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "/path/to/pre-bash-hook.sh",
        "timeout": 5000
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "command": "/path/to/log-hook.sh"
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "command": "/path/to/notify.sh"
      }
    ]
  }
}

环境变量

钩子脚本可访问的环境变量：

示例钩子

提交前验证

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

if [[ "$CLAUDE_TOOL_NAME" == "Bash" ]]; then
  INPUT=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command')
  if [[ "$INPUT" == *"git commit"* ]]; then
    echo "Running pre-commit checks..."
    npm test
    if [ $? -ne 0 ]; then
      echo "❌ Tests failed! Blocking commit."
      exit 1
    fi
  fi
fi
exit 0

操作日志记录

#!/bin/bash
# log-operations.sh

LOG_FILE="$HOME/.claude/audit.log"
TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")

echo "[$TIMESTAMP] Tool: $CLAUDE_TOOL_NAME" >> "$LOG_FILE"
echo "  Input: $CLAUDE_TOOL_INPUT" >> "$LOG_FILE"
if [ -n "$CLAUDE_TOOL_OUTPUT" ]; then
  echo "  Output: $CLAUDE_TOOL_OUTPUT" >> "$LOG_FILE"
fi
echo "" >> "$LOG_FILE"

桌面通知

#!/bin/bash
# notify-completion.sh

# macOS 通知
osascript -e 'display notification "任务完成" with title "Claude Code"'

# Linux 通知（需要 notify-send）
# notify-send "Claude Code" "任务完成"

危险命令拦截

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

DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "rm -rf \*"
  "> /dev/sda"
  "mkfs"
  "dd if="
)

if [[ "$CLAUDE_TOOL_NAME" == "Bash" ]]; then
  CMD=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command')
  for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if [[ "$CMD" == *"$pattern"* ]]; then
      echo "❌ BLOCKED: Dangerous command detected: $pattern"
      exit 1
    fi
  done
fi
exit 0

钩子返回值

• exit 0 - 继续执行
• exit 1 - 阻止操作（PreToolUse）
• 标准输出会显示给用户

7. 权限与安全

权限系统概述

Claude Code 采用细粒度权限控制，确保操作安全。

工具权限

配置权限规则

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "WebFetch",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff)",
      "Write(*.md)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Write(/etc/*)"
    ]
  }
}

权限模式

# 交互模式（默认）- 危险操作需确认
claude

# 跳过权限确认（危险）
claude --dangerously-skip-permissions

# 限制工具
claude --allowedTools "Read,Grep,Glob"

# 禁用特定工具
claude --disallowedTools "Bash,Write"

沙箱模式

Claude Code 默认在沙箱中运行 Bash 命令：

• 限制文件系统访问
• 限制网络访问
• 限制系统调用

禁用沙箱（不推荐）：

{
  "sandbox": false
}

审计日志

启用审计日志：

{
  "auditLog": {
    "enabled": true,
    "path": "~/.claude/audit.log",
    "level": "all"
  }
}

日志级别：

• all - 记录所有操作
• write - 只记录写操作
• dangerous - 只记录危险操作

安全最佳实践

1. 不要禁用沙箱 - 除非完全信任代码
2. 使用环境变量 - 不要在配置中明文存储密钥
3. 限制文件访问 - 使用 MCP 文件系统服务器限制目录
4. 启用审计日志 - 记录所有操作供审查
5. 定期审查权限 - 移除不需要的权限

8. 会话管理

会话概述

Claude Code 会自动保存会话历史，支持恢复和继续对话。

会话操作

# 启动新会话
claude

# 继续上次会话
claude -c
claude --continue

# 列出历史会话
claude --list

# 恢复特定会话
claude -r <session-id>
claude --resume <session-id>

# 清理历史会话
claude --clean

会话命令

# 在会话中查看信息
> /cost                # 查看 token 消耗
> /compact             # 压缩上下文
> /clear               # 清空对话
> /resume              # 选择历史会话恢复

会话存储

会话存储位置：~/.claude/sessions/

每个会话包含：

• 对话历史
• 上下文信息
• Token 使用统计
• 时间戳

上下文管理

# 查看上下文状态
> /context

# 手动压缩上下文
> /compact

# 清空并保留记忆
> /clear

后台任务

# 查看后台任务
> /tasks

# 获取任务输出
# 使用 TaskOutput 工具

9. 配置系统详解

配置层级

配置按优先级从高到低：

1. 命令行参数
2. 环境变量
3. 项目本地配置 (.claude/settings.local.json)
4. 项目配置 (.claude/settings.json)
5. 用户本地配置 (~/.claude/settings.local.json)
6. 用户配置 (~/.claude/settings.json)
7. 默认配置

完整配置选项

{
  // 基础配置
  "model": "opus",                          // 默认模型: opus, sonnet, haiku
  "alwaysThinkingEnabled": true,            // 启用扩展思考
  "maxThinkingTokens": 10000,               // 最大思考 token

  // 环境变量
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },

  // 权限配置
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm -rf *)"]
  },

  // MCP 服务器
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "xxx" }
    }
  },

  // 钩子
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "Notification": []
  },

  // 插件
  "enabledPlugins": {
    "gopls-lsp@claude-plugins-official": true,
    "typescript-lsp@claude-plugins-official": true
  },

  // UI 配置
  "theme": "dark",                          // 主题: dark, light, auto
  "statusLine": true,                       // 显示状态栏
  "showTokenCount": true,                   // 显示 token 计数

  // 行为配置
  "autoCompact": true,                      // 自动压缩上下文
  "autoCompactThreshold": 100000,           // 自动压缩阈值
  "sandbox": true,                          // 沙箱模式

  // 审计配置
  "auditLog": {
    "enabled": false,
    "path": "~/.claude/audit.log"
  }
}

配置命令

# 查看所有配置
claude config list

# 查看特定配置
claude config get model
claude config get permissions.allow

# 设置配置
claude config set model opus
claude config set permissions.allow '["Read", "Write"]'

# 重置配置
claude config reset
claude config reset model

环境变量

CLAUDE.md 文件

项目级指令文件，提供项目上下文：

# 项目名称

项目简介...

## 技术栈
- 语言：TypeScript
- 框架：React, Node.js
- 数据库：PostgreSQL

## 目录结构
- src/components/ - React 组件
- src/api/ - API 接口
- src/utils/ - 工具函数

## 代码规范
- 使用 ESLint 和 Prettier
- 提交信息遵循 Conventional Commits
- 所有函数需要类型注解

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

## 注意事项
- 不要修改 generated/ 目录
- API 密钥存储在 .env 中

10. 插件系统

插件类型

1. LSP 插件 - 语言服务器协议插件，提供代码智能
2. 功能插件 - 扩展 Claude Code 功能

LSP 插件

LSP 是 Language Server Protocol（语言服务器协议），它把“代码智能能力”从编辑器里拆出来，变成一个独立的 Language Server，通过标准协议给各种编辑器/IDE 提供能力。

你在写代码时常用的这些功能，大多就是 LSP 提供的：

• 语法/类型诊断（报错、warning）
• 跳转定义/查找引用（Go to Definition / Find References）
• 自动补全与参数提示（Completion / Signature Help）
• 重命名符号、代码格式化、代码动作（Rename / Format / Code Action）
• 悬浮提示（Hover，看类型、注释、文档）

Claude Code 里提到的 “LSP” 一般就是指它能利用项目的 Language Server（或编辑器已经连接的 LSP）拿到更准确的语义信息，比如：某个函数到底定义在哪里、类型是什么、引用链路有哪些、当前文件有哪些诊断错误等，从而让改代码/修 bug 的结果更可靠。

插件管理

# 安装插件
> /plugin gopls-lsp@claude-plugins-official

# 查看已安装插件
> /plugin list

# 禁用插件
> /plugin disable gopls-lsp

# 启用插件
> /plugin enable gopls-lsp

# 卸载插件
> /plugin remove gopls-lsp

配置插件

{
  "enabledPlugins": {
    "gopls-lsp@claude-plugins-official": true,
    "typescript-lsp@claude-plugins-official": true
  },
  "pluginSettings": {
    "gopls-lsp": {
      "formatting": true,
      "diagnostics": true
    }
  }
}

LSP 功能

启用 LSP 后可用的功能：

• 跳转定义 - 跳转到符号定义
• 查找引用 - 查找所有引用
• 悬停信息 - 显示类型和文档
• 自动补全 - 智能代码补全
• 诊断 - 实时错误检测
• 格式化 - 代码格式化
• 重命名 - 安全重命名符号

11. IDE 集成

VS Code 集成

安装

1. 打开 VS Code
2. 进入扩展市场（Cmd/Ctrl + Shift + X）
3. 搜索 “Claude Code”
4. 点击安装

功能

• 侧边栏聊天 - 在侧边栏与 Claude 对话
• 内联代码操作 - 选中代码直接与 Claude 交互
• 快速修复 - Claude 提供的代码修复建议
• 代码解释 - 解释选中的代码
• 终端集成 - 在终端中使用 Claude

快捷键

设置

{
  "claudeCode.model": "opus",
  "claudeCode.autoSuggest": true,
  "claudeCode.inlineEnabled": true
}

JetBrains IDE 集成

支持的 IDE：

• IntelliJ IDEA
• PyCharm
• WebStorm
• GoLand
• PhpStorm
• Rider
• RubyMine
• CLion

安装

1. 打开 Settings/Preferences
2. 进入 Plugins
3. 搜索 “Claude Code”
4. 点击 Install
5. 重启 IDE

功能

• 工具窗口聊天
• 代码选择交互
• 快速操作菜单
• 终端集成

终端集成

# 设置终端集成
claude terminal-setup

# 在 VS Code 终端中启动
code . && claude

# 在 IDE 终端中启动
claude

12. 键盘快捷键

CLI 模式快捷键

Vim 模式快捷键

启用 Vim 模式：/vim

工具确认快捷键

当工具需要确认时：

13. 高级功能

批处理模式

# 单次执行并退出
claude -p "重构 src/utils.ts 中的函数"

# 批量处理多个文件
for file in src/*.ts; do
  claude -p "检查 $file 中的问题" --output-format json >> results.json
done

# 管道输入
cat error.log | claude -p "分析这些错误日志"

# JSON 输出
claude -p "列出所有 TODO 注释" --output-format json

模板系统

创建命令模板：

# ~/.claude/templates/fix-bug.txt
请修复以下 bug：

文件：{{file}}
问题描述：{{description}}
重现步骤：{{steps}}

请：
1. 定位问题根因
2. 提供修复方案
3. 添加相关测试

使用模板：

claude -p "$(cat ~/.claude/templates/fix-bug.txt)" \
  --var file=src/api.ts \
  --var description="API 返回 500" \
  --var steps="调用 /users 接口"

并行执行

# 并行分析多个文件
claude -p "同时分析以下文件的代码质量：
- src/api/users.ts
- src/api/posts.ts
- src/api/comments.ts
"

上下文注入

# 注入额外上下文
claude --context "这是一个遗留系统，需要保持向后兼容"

# 从文件注入
claude --context-file context.md

上下文注入 vs Speckit 对比

各自适用场景

用 Speckit 的情况：

# 项目规范（长期有效）
/speckit.constitution 定义编码规范...

# 功能开发（有完整工作流）
/speckit.specify 实现用户认证...

# 项目级上下文 → 写入 CLAUDE.md 或 constitution.md

用 –context 的情况：

# 1. 临时说明（不值得写入文件）
claude --context "今天只修复 bug，不要重构"

# 2. 批处理/自动化脚本
for file in src/*.go; do
  claude -p "检查 $file" --context "重点关注安全问题"
done

# 3. 一次性任务
claude --context "这是客户紧急需求，优先级最高" -p "修复登录问题"

# 4. 动态上下文（从其他系统获取）
claude --context "$(curl -s api.example.com/project-status)" -p "分析项目状态"

最佳实践：组合使用

# 项目级（Speckit + CLAUDE.md）
specs/
├── 1-user-auth/
│   ├── spec.md          # 功能规范
│   ├── plan.md          # 技术计划
│   └── tasks.md         # 任务列表
.specify/
└── memory/
    └── constitution.md  # 项目宪法
CLAUDE.md                # 项目说明

# 临时上下文（--context）
claude --context "今天重点：性能优化" -c

场景选择指南

简单原则：持久的用 Speckit，临时的用 –context。

模型切换

# 会话中切换
> /model sonnet

# 临时使用其他模型
> @haiku 这是一个简单的问题

# 命令行指定
claude --model opus

代理任务

Claude Code 可以启动子代理处理复杂任务：

# 探索代码库
> 探索项目中的认证实现

# 实现功能
> 实现用户注册功能，包括验证和数据库操作

# 审查代码
> 审查 PR #123 的所有变更

后台执行

# 后台运行长任务
> 在后台运行完整的测试套件

# 查看后台任务
> /tasks

# 获取任务结果
# 任务完成后会自动显示结果

14. 故障排查

诊断命令

# 运行诊断
claude doctor

# 详细诊断
claude doctor --verbose

# 检查特定问题
claude doctor --check mcp
claude doctor --check permissions

常见问题

MCP 服务器无法连接

# 测试 MCP 服务器
claude mcp test github

# 检查日志
cat ~/.claude/mcp/github.log

# 解决方案
1. 检查 command 路径是否正确
2. 检查环境变量是否设置
3. 手动运行命令测试

API 连接失败

# 检查 API 配置
claude config get env.ANTHROPIC_API_KEY
claude config get env.ANTHROPIC_BASE_URL

# 测试连接
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/models

# 解决方案
1. 验证 API 密钥有效性
2. 检查网络代理设置
3. 确认 API 配额

权限被拒绝

# 检查权限配置
claude config get permissions

# 临时跳过权限
claude --dangerously-skip-permissions

# 解决方案
1. 添加到 allow 列表
2. 使用钩子验证后允许

上下文过长

# 压缩上下文
> /compact

# 清空对话
> /clear

# 解决方案
1. 使用 /compact 定期压缩
2. 分拆大任务为小任务
3. 启用 autoCompact

插件不生效

# 检查插件状态
> /plugin list

# 重新安装
> /plugin remove gopls-lsp
> /plugin gopls-lsp@claude-plugins-official

# 解决方案
1. 确认插件名称正确
2. 重启 Claude Code
3. 检查语言服务器是否安装

日志位置

重置 Claude Code

# 重置配置
claude config reset

# 清理缓存
rm -rf ~/.claude/cache

# 完全重置（保留配置）
rm -rf ~/.claude/sessions ~/.claude/cache

# 完全重新安装
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude
npm install -g @anthropic-ai/claude-code

15. 最佳实践

项目初始化清单

• 运行 /init 创建 CLAUDE.md
• 配置项目特定的 MCP 服务器
• 设置必要的 Hooks
• 启用相关的 LSP 插件
• 配置权限规则
• 将 .claude/ 目录加入版本控制（排除敏感信息）

高效使用技巧

1. 提供清晰上下文

# 好的提问
> 在 src/components/Button.tsx 中添加一个 loading 状态，
> 参考现有的 disabled 状态实现方式

# 不好的提问
> 添加 loading

2. 利用项目探索

> 这个项目的架构是什么？
> 用户认证是如何实现的？
> 找出所有使用了 deprecated API 的代码

3. 分步骤处理复杂任务

> 先帮我分析这个 bug 的原因
> 现在帮我修复它
> 最后添加相关测试

4. 善用代码审查

> /review
> /security-review

5. 使用自定义技能

创建常用工作流为技能，一键执行：

# .claude/commands/deploy.md
---
description: 部署到生产环境
---

执行以下部署步骤：
1. 运行测试确保通过
2. 构建生产版本
3. 检查构建产物
4. 提示用户确认后执行部署命令

安全注意事项

1. 不要在配置中明文存储密钥 - 使用环境变量
2. 启用审计日志 - 记录所有操作
3. 限制权限 - 只授予必要权限
4. 定期审查 - 检查配置和权限设置
5. 使用沙箱 - 保持沙箱模式开启
6. 验证输出 - 审查生成的代码

推荐工作流

日常开发

# 开始工作
cd project
claude -c  # 继续上次会话

# 探索代码
> 帮我理解这个模块的实现

# 实现功能
> 实现用户头像上传功能

# 审查代码
> /review

# 提交代码
> 帮我生成提交信息

Bug 修复

claude

> 这个错误是什么原因：[粘贴错误信息]
> 帮我定位问题
> 修复这个问题
> 添加测试防止回归

代码重构

claude

> 分析 src/utils/ 目录的代码质量
> 重构 parseData 函数，提高可读性
> 确保测试仍然通过

资源链接

• 官方文档: https://docs.anthropic.com/claude-code
• GitHub: https://github.com/anthropics/claude-code
• MCP 规范: https://modelcontextprotocol.io
• 问题反馈: https://github.com/anthropics/claude-code/issues

最后更新: 2026-01-03

RecoveryAshes Blog