Claude Code 使用指南

约 1581 字大约 5 分钟

2026-03-12

一句话摘要：Claude Code 是 Anthropic 官方的 AI 编程助手工具，支持多平台、多编辑器集成，通过 CLAUDE.md、Skills、子智能体等机制实现高效的人机协作。

工具与安装

常用工具

软件	说明
CCGUI	IDEA CC 插件
Claude Code for VS Code	VS Code 插件
Clarc	MacOS 端 GUI
AionUI	全平台 GUI
CCSwitch	CC 可视化管理工具

安装方法

使用 Homebrew 安装：

brew install --cask claude-code

集成 OpenRouter

配置环境变量以使用 OpenRouter 作为后端：

sudo vi ~/.zshrc

添加以下配置：

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""
export ANTHROPIC_MODEL="google/gemini-2.0-flash-lite-001"
export ANTHROPIC_DEFAULT_SONNET_MODEL="google/gemini-2.0-flash-lite-001"

生效配置：

source ~/.zshrc

CLAUDE.md 配置文件

作用域层级

CLAUDE.md 是项目级配置文件，按优先级从高到低：

项目级：./CLAUDE.md（项目根目录）
规则级：.claude/rules/*.md
本地级：./CLAUDE.local.md
用户级：~/.claude/CLAUDE.md
企业级：/etc/claude-code/CLAUDE.md

结构模板

以下是一个订单服务 API 项目的 CLAUDE.md 示例：

# 订单服务 API

## 技术栈

- Node.js 20 + TypeScript 5.3（严格模式）
- Fastify 4 框架（不使用 Express）
- Prisma ORM + PostgreSQL 15
- pnpm 8 包管理（不使用 npm/yarn）

## 项目结构

- src/routes/ — 路由定义，只做参数解析和响应构造
- src/services/ — 业务逻辑层，所有核心逻辑在此
- src/repositories/ — 数据访问层，封装 Prisma 调用
- src/schemas/ — Zod 验证 schema，与路由一一对应

## 关键约定

- API 统一返回格式：{ success: boolean, data?: T, error?: { code: string, message: string } }
- 错误码使用 UPPER_SNAKE_CASE，如 ORDER_NOT_FOUND
- 数据库表名 snake_case 复数形式，主键 UUID，必带 created_at 和 updated_at

## 常用命令

- `pnpm dev` - 启动开发服务器，端口 3000
- `pnpm test` - 运行全部测试（vitest）
- `pnpm build` - TypeScript 编译 + 类型检查
- `pnpm db:migrate` - 执行 Prisma 数据库迁移

Skills 技能系统

作用域层级

企业级：<managed-path>/.claude/skills/
用户级：~/.claude/skills/<skill-name>/
项目级：<project>/.claude/skills/<skill-name>/
插件级：<插件目录>/skills/

目录结构

my-skill/
├── SKILL.md          # 必需：技能定义文件
├── scripts/          # 可选：辅助脚本
├── templates/        # 可选：输出模板
├── references/       # 可选：参考文档
└── examples/         # 可选：示例文件

SKILL.md 结构

---
name: skill-name              # 技能名称，会变成 /skill-name 命令
description: 简短描述         # 用于 Claude 自动匹配触发
category: development         # 分类
tags:                         # 标签
  - code
  - automation
---

# 技能标题

## 使用场景

什么时候用这个技能。

## 执行步骤

1. 第一步
2. 第二步

## 注意事项

- 注意点 1
- 注意点 2

核心特性

结构化：清晰的目录和文件组织
渐进式披露：按需加载相关内容
语义触发：通过描述自动匹配触发时机
安全约束：可定义执行边界
动态注入：运行时注入上下文

设计模式

模板驱动模式：基于模板生成输出
脚本增强模式：结合脚本扩展能力
知识分层模式：按层次组织知识
工具隔离模式：限制可用工具集

子智能体

目录结构

your-project/
└── .claude/
    └── agents/
        ├── code-reviewer.md    # 代码审查子智能体
        ├── test-runner.md      # 测试运行子智能体
        ├── log-analyzer.md     # 日志分析子智能体
        └── bug-locator.md      # bug 定位子智能体

定义结构

---
name: code-reviewer
description: |
  审查代码质量、安全漏洞和性能问题的专家
  当用户要求代码审查、安全审计或质量评估时使用
tools:
  - Read
  - Grep
  - Glob
model: sonnet
permissionMode: plan
---

## 审查维度

### 安全性

- 检查敏感数据暴露
- 验证输入过滤

### 代码质量

- 代码可读性
- 命名规范

### 性能

- 算法复杂度
- 资源使用

## 输出格式

### 审查摘要

### 发现的问题

- 问题列表

子智能体模式

只读型：观察者，只读取分析不修改
执行型：高噪声任务处理器（外观模式）
并行型：多专家工作流
流水线型：串行处理
团队型：多智能体协作

与 Skills 的关系

角色驱动：子智能体是主角，可调用 Skills
知识/流程驱动：Skills 是主角，子智能体负责专门任务

Hook 钩子系统

作用域层级

企业级：managed-settings.json
项目级：project/.claude/settings.json
项目本地级：project/.claude/settings.local.json
用户级：~/.claude/skills/<skill-name>/
插件级：hooks/hooks.json

事件类型

会话级事件

SessionStart：会话启动
SessionEnd：会话终止
PreCompact：上下文压缩前

工具调用事件

PreToolUse：调用工具执行前
PostToolUse：调用工具使用后
PostToolUseFailure：调用工具失败后
PermissionRequest：权限对话框打开前
UserPromptSubmit：用户提交后

子智能体事件

SubagentStart：子智能体启动前
SubagentStop：子智能体完成任务后

完成事件

Stop：轮询结束后
Notification：发送系统通知前

其他事件

TeammateIdle：多智能体协作，队友完成任务进入空闲时触发
TaskCompleted：多智能体协作，任务全部完成时触发
ConfigChange：配置文件变更前
WorktreeCreate 与 WorktreeRemove

处理器类型

command：确定性命令执行
prompt：模型评估判断
agent：多轮子智能体验证

MCP 服务

作用域

项目级：project/.mcp.json

Rule 规则系统

规则文件按功能分类：

.claude/
├── CLAUDE.md              # 项目概述和核心规则
└── rules/
    ├── coding-style.md    # 代码风格规范
    ├── git-workflow.md    # Git 工作流
    ├── testing.md         # 测试要求
    └── security.md        # 安全规则

Plugin 插件系统

简介

插件系统方便已有技能的迁移和分发。

目录结构

react-workflow/                    # Plugin 根目录
├── .claude-plugin/
│   └── plugin.json                # [必需] Plugin 清单文件
├── commands/                      # 斜杠命令定义
│   ├── review.md
│   └── deploy.md
├── agents/                        # 子智能体定义
│   ├── security-scanner.md
│   └── quick-fix.md
├── skills/                        # Skills 领域知识包
│   └── react-patterns/
│       ├── SKILL.md
│       └── chapters/
│           ├── hooks.md
│           └── performance.md
├── hooks/                         # Hooks 配置与脚本
│   ├── hooks.json
│   ├── check-bash.sh
│   └── auto-format.sh
├── .mcp.json                      # MCP 服务器配置引用
└── README.md                      # 文档说明

其他功能

终断重启

通过 .claude-work/log-analysis.md 可恢复中断的会话。

常用命令

claude mcp list    # 查看安装的 MCP 启动状态

总结

Claude Code 通过分层配置体系（CLAUDE.md、Skills、Rules）和模块化扩展机制（子智能体、Hooks、Plugins），实现了灵活可控的 AI 辅助编程体验。核心要点：

配置按作用域分层，项目级优先级最高
Skills 封装领域知识和工作流程
子智能体实现角色分工和并行处理
Hooks 提供全生命周期的干预点
Plugins 便于能力分发和复用