Claude Code 完整使用指南

Anthropic 官方 CLI — AI 驱动的软件开发助手

版本：2026年5月 | 适用模型：Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5

一、Claude Code 概述

Claude Code 是 Anthropic 推出的官方命令行 AI 编程助手。它不是一个简单的代码补全工具，而是一个能够在终端中理解整个代码库、执行复杂软件工程任务的 AI Agent。

核心定位：让 Claude 直接在您的终端中工作，理解代码上下文，编辑文件，运行命令，完成从 bug 修复到功能开发的完整任务。

1.1 可用形态

1.2 核心能力总览

Claude Code 拥有以下核心能力，其中 Superpowers 是最具特色的高级功能：

二、Agent 系统

Agent 是 Claude Code 的核心任务执行单元。不同类型的 Agent 擅长不同的任务，可以独立运行、并行协作。Agent 有自己的工具集和上下文窗口，不会污染主对话。

2.1 Agent 类型

2.2 Agent 调用方式

使用 Agent 工具，通过 description 和 prompt 参数来定义 Agent 的行为：

# 启动一个 Explore Agent（快速搜索）
Agent({
description: “查找认证相关代码”,
subagent_type: “Explore”,
prompt: “搜索项目中所有与用户认证相关的文件，包括登录、注册、token管理等。”
})

# 启动一个 Plan Agent（架构设计）
Agent({
description: “支付模块架构设计”,
subagent_type: “Plan”,
prompt: “为电商平台设计支付模块架构。需要支持微信支付、支付宝。输出模块划分、数据流、接口定义。”
})

# 后台并行运行多个 Agent
Agent({ description: “后端代码分析”, run_in_background: true, … })
Agent({ description: “前端代码分析”, run_in_background: true, … })

2.3 Agent 使用场景示例

示例 1：用 Explore Agent 查找代码

需求：找到项目中所有与”用户权限”相关的代码文件

Agent({
description: “查找权限相关代码”,
subagent_type: “Explore”,
prompt: “在项目中搜索所有与用户权限相关的文件和函数。关注：RBAC、角色管理、权限校验、auth middleware等。返回文件路径和关键函数名。”
})
# Agent 返回：找到 15 个相关文件，包括 PermissionController.java, RoleService.java 等

示例 2：用 Plan Agent 设计新功能

需求：为现有系统设计”消息通知”模块

Agent({
description: “消息通知模块设计”,
subagent_type: “Plan”,
prompt: “现有系统是一个任务管理平台。需要新增消息通知模块。请设计：
1. 通知类型（站内信/邮件/短信）
2. 数据模型（通知模板/发送记录/用户偏好）
3. API 接口定义
4. 与现有任务模块的集成点
输出完整的架构设计文档。”
})

示例 3：并行 Agent 加速工作

需求：同时分析前后端代码结构

# 同时启动两个 Agent，互不阻塞
Agent({
description: “后端架构分析”,
subagent_type: “Explore”,
prompt: “分析 backend/ 目录的代码结构，列出所有微服务模块和它们之间的依赖关系。”,
run_in_background: true
})

Agent({
description: “前端架构分析”,
subagent_type: “Explore”,
prompt: “分析 frontend/ 目录的组件结构，列出页面路由和状态管理方案。”,
run_in_background: true
})
# 两个 Agent 并行执行，完成后系统通知你结果

2.4 Worktree 隔离模式

Agent 支持在 Git Worktree 中隔离运行，避免影响主工作区。适合大规模重构或实验性改动。

# 在隔离的工作树中运行 Agent
Agent({
description: “大规模重构”,
subagent_type: “general-purpose”,
isolation: “worktree”,
prompt: “将所有 API 路由从 /api/v1/ 迁移到 /api/v2/，更新所有引用。”
})
# Agent 在独立 worktree 中操作，完成后可选择合并或丢弃

三、Skill 系统

Skill 是 Claude Code 的可复用能力模块。每个 Skill 是一个 Markdown 文件，定义了一个特定的工作流程或领域知识。通过 /skill-name 即可调用。

3.1 内置 Skill 列表

3.2 自定义 Skill

Skill 存放在项目 .claude/skills/ 目录下，格式为 Markdown + YAML Frontmatter。以下是一个完整的自定义 Skill 示例：

示例：创建一个”需求分析”Skill

—
name: 需求分析
description: 将原始需求转化为结构化 PRD、用户故事和 API 契约。
type: user
—

# 需求分析 Skill

## 工作流程

### 第一步：需求理解
读完用户输入后，先复述理解，然后追问：
1. 用户角色：有哪些角色？各自权限？
2. 核心流程：端到端完整流程是什么？
3. 边界条件：哪些不在本期范围？
4. 性能指标：并发/响应时间/数据量要求？

### 第二步：输出 PRD
生成 docs/requirements/PRD-{模块名}.md，包含：
– 需求概述（背景/目标/范围边界）
– 用户角色与用户故事
– 功能需求清单与详述
– 业务流程（泳道图）
– 接口需求（OpenAPI 3.0 草案）
– 数据模型草案
– 非功能需求
– 验收标准

### 第三步：输出用例清单
生成 docs/requirements/UC-{模块名}.md

### 第四步：输出 API 契约
生成 docs/api/API-{模块名}.yaml

调用自定义 Skill：

/需求分析 用户需要在养护流程中增加”紧急停止”按钮，
工程师发现电池异常时可以随时中断充电

3.3 Skill 的高级用法

Skill 之间可以组合使用，形成完整的 AI 开发流水线：

/需求分析 → 输出 PRD + API Spec
↓ 人工确认
/claude-api → 从 Spec 生成 Controller 骨架 + TS 类型
↓
/review → 代码审查
↓
/simplify → 代码优化
↓
/security-review → 上线前安全检查

四、Superpowers 深度解析

Superpowers 是 Claude Code 区别于普通 AI 编程助手的核心高级能力。它不是单一功能，而是一组让 Claude Code 能够像高级工程师一样思考和工作的能力的集合。

4.1 什么是 Superpowers

Superpowers 是 Claude Code 的”超能力集合”——这些能力让 Claude 不仅能写代码，还能理解项目全貌、自主规划、安全执行、持续学习。核心包括以下五大能力：

4.2 Plan Mode — 规划模式

Plan Mode 让 Claude 在动手写代码之前，先探索代码库、设计方案，等你确认后再执行。这是避免”AI 写了一堆用不上的代码”的关键机制。

使用方式：

# 方式 1：Claude 主动进入 Plan Mode
# 当任务涉及多文件修改、架构决策时，Claude 会自动提议进入 Plan Mode

# 方式 2：手动触发
用户: “帮我实现用户权限系统” → Claude 检测到复杂任务，调用 EnterPlanMode()
→ 用户确认进入 Plan Mode → Claude 开始探索代码库、设计方案
→ Claude 输出完整实现计划 → 用户审核批准 → Claude 开始写代码

# 方式 3：用户直接指定
用户: “先用 Plan Mode 设计一下这个功能的方案”

Plan Mode 工作流程：

1. EnterPlanMode() — 进入规划模式
2. Claude 使用 Glob/Grep/Read 探索代码库
3. Claude 使用 AskUserQuestion 澄清需求
4. Claude 将方案写入 Plan 文件
5. ExitPlanMode() — 提交方案给用户审批
6. 用户批准 → 开始实现
7. 用户拒绝 → 修改方案

适合 Plan Mode 的场景：

4.3 Context Management — 上下文管理

Claude Code 拥有 200K token 的上下文窗口，能一次性加载整个项目的关键文件。它通过以下机制管理上下文：

最佳实践：编写高质量的 CLAUDE.md

# CLAUDE.md 示例
## 项目概述
本项目为动力电池检测平台，包含三端：PC后台、用户小程序、网点小程序。

## 技术架构
– 后端：Spring Boot 3.x + MySQL 8.0 + Redis
– 前端：Vue 3 + Element Plus
– 小程序：UniApp

## 编码规范
– Java 用驼峰，数据库用蛇形
– API 统一返回 Result<T>：{ code, message, data }
– Controller 只做参数校验，业务逻辑放 Service

## AI 开发流程
– 先输出 OpenAPI Spec，人工确认后再写代码
– Agent 之间只传递 Spec 文件，不传递口头约定
– 每个子任务完成后编译验证

4.4 Memory System — 记忆系统

Claude Code 拥有跨会话的持久化记忆系统。它将重大信息存储到 .claude/projects/ 目录，未来的会话可以读取这些记忆，让 Claude 越来越了解你的项目。

使用方式：

# Claude 自动保存
用户: “我是后端开发，第一次接触这个React项目”
→ Claude 自动保存 User 记忆：”用户是后端背景，React新手”

# 手动触发
用户: “/remember 我们的CI用的是GitHub Actions”
→ Claude 保存 Reference 记忆

# 调用记忆
用户: “帮我配置CI”
→ Claude 自动读取之前的记忆，知道用 GitHub Actions

4.5 Hooks System — 钩子系统

Hooks 可以在 Claude Code 的工具调用前后自动执行自定义脚本。这让你可以嵌入自己的安全检查、代码格式化、自定义审批流程。

配置示例：

// .claude/settings.json
{
“hooks”: {
// 每次 Bash 执行前，检查命令安全性
“preBash”: {
“command”: “node
.claude/scripts/check-dangerous-command.js”,
“description”: “检查是否包含危险命令”
},
// 每次 Edit 文件后，自动格式化
“postEdit”: {
“command”: “prettier –write ${FILE_PATH}”,
“description”: “自动格式化修改的文件”
},
// 每次 Write 新文件后，检查是否包含敏感信息
“postWrite”: {
“command”: “gitleaks detect –path=${FILE_PATH}”,
“description”: “检查新文件是否包含密钥/密码”
},
// Git Commit 前运行测试
“preCommit”: {
“command”: “npm test — –changed”,
“description”: “提交前运行相关测试”
}
}
}

4.6 MCP Integration — 外部工具集成

MCP（Model Context Protocol）让 Claude Code 可以连接外部工具和数据源。通过 MCP Server，Claude 可以访问数据库、调用 API、操作第三方服务。

// .claude/settings.json — MCP Server 配置示例
{
“mcpServers”: {
// 数据库 MCP：让 Claude 直接查询数据库
“postgres”: {
“command”: “npx @
anthropic/mcp-server-postgres”,
“args”: [“
postgresql://localhost/mydb”]
},
// GitHub MCP：让 Claude 创建 Issue、管理 PR
“github”: {
“command”: “npx @
anthropic/mcp-server-github”,
“env”: { “GITHUB_TOKEN”: “${GITHUB_TOKEN}” }
},
// 自定义 MCP：连接公司内部系统
“internal-api”: {
“command”: “node
.claude/mcp-servers/internal-api.js”,
“args”: [“–endpoint”, “
https://api.internal.company.com”]
}
}
}

五、Open Spec — 规格驱动的 AI 开发方法论

Open Spec 不是 Claude Code 的一个功能，而是在 Claude Code 生态中实践”规格驱动开发”的方法论。核心思想：用 OpenAPI 3.0 作为单一实际来源，驱动从需求到代码到测试的全流程。

5.1 核心理念

传统 AI 开发流程中，前后端 Agent 通过”口头约定”来协调接口，容易产生理解偏差。Open Spec 流程强制所有 Agent 以 OpenAPI Spec 文件为唯一的契约。

一句话总结：API 变更是从 Spec 开始的。永远先改 Spec，再改代码。

5.2 Open Spec 全流程

需求输入（自然语言）
│
▼
需求分析 Agent → PRD + 用例清单
│ (人工确认)
▼
架构设计 Agent → OpenAPI Spec (docs/api/API-{模块}.yaml) + 数据模型
│ (人工确认) ← 单一实际来源
│
┌───────┼────────┐
│ │ │
▼ ▼ ▼
后端Agent 前端Agent 测试Agent
│ │ │
│ │ │
▼ ▼ ▼
openapi- openapi- portman →
generator generator Postman
→Controller →TS类型 Collection
骨架+DTO +API函数 +集成测试

5.3 工具链

5.4 Open Spec 实战示例

场景：为”电池养护紧急停止”功能走完整的 Open Spec 流程

Step 1: 需求分析 Agent 输出 PRD

/需求分析 养护流程增加”紧急停止”按钮

→ 输出文件：
docs/requirements/PRD-养护紧急停止.md
docs/requirements/UC-养护紧急停止.md

Step 2: 架构设计 Agent 输出 API Spec

# 人工确认 PRD 后，生成 API Spec
→ 输出文件：
docs/api/API-养护紧急停止.yaml

# Spec 内容示例：
openapi: “3.0.0”
paths:

/api/v1/maintenance/order/{orderId}/emergency-stop:
post:
summary: 下发紧急停止指令
requestBody:
content:
application/json:
schema:
type: object
required: [engineerId, chargePhase]
properties:
engineerId: { type: string }
chargePhase: { enum: [STATUS_CHECK, MAINTENANCE] }
responses:
'200': { description: 指令下发成功 }

Step 3: 从 Spec 生成后端代码骨架

# 校验 Spec 语法
spectral lint docs/api/API-养护紧急停止.yaml

# 生成 Spring Boot Controller
openapi-generator-cli generate -i docs/api/API-养护紧急停止.yaml -g spring -o
backend/generated/emergency-stop –additional-properties=interfaceOnly=true,useSpringBoot3=true

# 产物：
# EmergencyStopApi.java ← Controller 接口
# EmergencyStopRequest.java ← 请求 DTO
# EmergencyStopRecord.java ← 响应 DTO

Step 4: 从 Spec 生成前端类型

# 生成 TypeScript 类型和 API 调用函数
openapi-generator-cli generate -i docs/api/API-养护紧急停止.yaml -g typescript-axios -o
miniapp-station/generated/api

# 小程序中直接使用：
import { EmergencyStopApi } from '@/generated/api'
const api = new EmergencyStopApi()
const result = await
api.orderOrderIdEmergencyStopPost(orderId, {
engineerId: currentUser.id,
chargePhase: 'MAINTENANCE'
})

Step 5: 前后端独立开发 + Prism Mock

# 启动 Mock Server（后端未就绪时前端可独立调试）
prism mock docs/api/API-养护紧急停止.yaml –port 4010

# 前端指向 Mock Server 开发
# 后端基于生成的 Controller 骨架实现业务逻辑

Step 6: CI 自动校验

#
.github/workflows/api-check.yml
spec-check:
steps:
– run: npx spectral lint docs/api/*.yaml # 校验 Spec 语法
– run: npx portman –local docs/api/*.yaml # 生成测试用例
– run: npm test — tests/contract/ # 运行契约测试

5.5 Open Spec 的核心价值

六、典型工作流示例

6.1 Bug 修复流程

1. 用户: “登录页面提交后报500错误，帮我修复”
2. Claude 自动读取相关文件（LoginController, AuthService, 日志）
3. Claude 定位根因：AuthService 中 NPE，由于缺少 null 检查
4. Claude 使用 Edit 工具修复代码
5. Claude 运行测试验证修复
6. Claude 提交代码

6.2 新功能开发流程（Open Spec）

1. /需求分析 → PRD + 用例
2. 人工确认 PRD
3. Plan Agent 设计架构 → OpenAPI Spec
4. 人工确认 Spec
5. openapi-generator → 生成后端骨架 + 前端类型
6. prism mock → 前后端并行开发
7. /review → AI 代码审查
8. /simplify → 代码优化
9. CI 自动 spectral lint + 契约测试
10. 人工最终验收

6.3 代码审查流程

1. 用户: “/review”
2. Claude Code 获取当前分支的变更
3. Agent(“code-reviewer”) 独立审查（不受主对话影响）
4. 输出审查报告：安全问题、代码风格、性能问题、测试覆盖
5. 用户根据报告修改

七、最佳实践与技巧

八、官方文档与资源

Claude Code 官方文档与资源链接：

• Claude Code 官方文档：
https://docs.anthropic.com/en/docs/claude-code

• Claude Code CLI 快速开始：
https://docs.anthropic.com/en/docs/claude-code/quickstart

• Claude Code 配置指南：
https://docs.anthropic.com/en/docs/claude-code/settings

• Claude Agent SDK：https://docs.anthropic.com/en/docs/agents-and-tools/agent-sdk

• Claude API 文档：
https://docs.anthropic.com/en/docs/api

• Anthropic 官方控制台：
https://console.anthropic.com/

• Claude Code GitHub 仓库：
https://github.com/anthropics/claude-code

• Claude Code 问题反馈：
https://github.com/anthropics/claude-code/issues

• MCP 协议文档：
https://modelcontextprotocol.io/

• OpenAPI 3.0 规范：
https://swagger.io/specification/

• Spectral (API Linting)：https://stoplight.io/open-source/spectral

• Prism (Mock Server)：https://stoplight.io/open-source/prism

• OpenAPI Generator：https://openapi-generator.tech/

—

本文档基于 Claude Code 2026年5月版本编写。功能持续更新中，请以官方文档为准。