## 1. 快速上手

### 1.1 启动 Claude Code

    # 在项目目录下启动
    cd ~/projects/my-project
    claude

    # 指定提示词启动
    claude "帮我实现一个用户认证模块"

    # 带系统提示词启动
    claude --system "你是一个资深 Go 工程师"

    # 无头模式（CI/CD）
    claude --print "运行测试并报告结果"

### 1.2 核心工作循环

输入需求→ Claude 读取代码→ Claude 提出方案→ 审批工具调用→ Claude 执行修改→ 验证结果

### 1.3 首次使用推荐

#### 第一步：初始化项目

运行 `/init` 生成 `CLAUDE.md`，让 Claude 理解项目结构、编码规范和架构约定。

#### 第二步：确认权限

使用 `Shift+Tab` 切换到合适的权限模式。新手推荐 Default 模式，每次操作前确认。

#### 第三步：描述任务

用自然语言描述需求，包含关键上下文："在 X 文件中添加 Y 功能，参考 Z 模块的风格"。

#### 提示：让 Claude 自主探索

对于不熟悉的代码库，先让 Claude 自己阅读相关文件，而不是直接给出修改方案。说"先看看相关代码"比直接给出修改指令更有效。

## 2. 斜杠命令全览

### 2.1 核心命令

命令 | 功能 | 使用场景
--- | --- | ---
`/help` | 显示帮助信息和可用命令 | 随时查看当前可用的命令和插件
`/config` | 打开配置 UI | 快速修改主题、模型、字体等设置
`/compact` | 压缩对话上下文 | 长对话后释放上下文窗口，保留关键信息
`/clear` | 清空对话历史 | 开始全新任务，重置对话

### 2.2 代码与项目命令

命令 | 功能 | 使用场景
--- | --- | ---
`/init` | 初始化项目，生成 CLAUDE.md | 首次在新项目中使用，建立项目上下文
`/review` | 审查当前分支的待提交变更 | 提交前自查代码质量
`/security-review` | 安全审查待提交变更 | 合并前检查 SQL 注入、XSS 等安全问题

### 2.3 工作流命令

命令 | 功能 | 使用场景
--- | --- | ---
`/plan` | 进入规划模式 | 复杂任务前，先拆分步骤再实施
`/btw` | 上下文提问不打断当前工作 | 边干活边问细节，不偏离主线
`/loop <interval> <cmd>` | 按间隔循环执行 | 监控构建状态、轮询部署进度
`/permissions` | 查看/修改权限设置 | 管理工具权限白名单
`/plugin` | 管理插件 | 安装/卸载自定义命令、技能、MCP 服务

#### 提示：自定义斜杠命令

在 `.claude/commands/` 目录下创建 `.md` 文件即可定义自定义斜杠命令。也可通过 Agent SDK 编程创建复杂命令。

## 3. 权限模式

Claude Code 提供 5 种权限模式，控制工具执行前的审批行为：

模式 | 行为 | 推荐场景
--- | --- | ---
Auto（自动） | Claude 自动执行，分类器模型在后台审查操作 | 高信任度场景，成熟的代码库
Default（默认/安全） | 潜在危险操作（写文件、Shell 命令）需确认 | 日常开发，推荐作为默认模式
Plan（规划） | 实施前必须先规划 | 架构变更、重构
Custom（自定义） | 通过 settings.json 定义自定义规则 | 团队有特定规范时
Manual（手动） | 每个操作都需要显式批准 | 最高安全要求场景

### 3.1 切换模式

- 快捷键：Shift+Tab 快速切换
- 命令：`/permissions` 查看当前设置
- 配置：`settings.json` 中设置 `permissions.defaultMode`

### 3.2 工具级权限白名单

在 `.claude/settings.json` 中为常用只读操作配置白名单，减少审批提示：

    {
      "permissions": {
        "allow": [
          "Bash(git status:*)",
          "Bash(ls:*)",
          "Bash(find:*)",
          "Bash(grep:*)"
        ]
      }
    }

#### 注意

只读操作（git status、ls、grep）可以安全加入白名单。写操作（rm、git reset）永远不要加入白名单，除非你完全信任自动化流程。

## 4. 键盘快捷键

### 4.1 会话控制

快捷键 | 功能 | 说明
--- | --- | ---
Ctrl+C | 中断当前操作 | 停止 Claude 的执行
Esc Esc | 回退/撤销 | 回退 Claude 的上一次响应
Ctrl+B | 后台运行 | 将长时间命令放入后台
Shift+Enter | 多行输入 | 在提示框中输入换行
↑/↓ | 历史导航 | 浏览之前输入的命令

### 4.2 权限与配置

快捷键 | 功能
--- | ---
Shift+Tab | 循环切换权限模式
Tab | 自动补全/确认

### 4.3 自定义快捷键

在 `~/.claude/keybindings.json` 中自定义快捷键，支持 50+ 内置操作和 17 个不同的上下文：

    {
      "bindings": [
        {
          "keys": ["ctrl+s"],
          "action": "submit",
          "context": "prompt"
        }
      ]
    }

#### 提示

运行 `/keybindings-help` 获取自定义快捷键的配置帮助。

## 5. .claude 目录结构

`.claude/` 目录是 Claude Code 的项目控制中心，包含 5 个子系统配置：

    .claude/
    ├── CLAUDE.md              # 项目指令（自动加载到系统提示）
    ├── settings.json          # 项目级设置和权限（提交到 git）
    ├── settings.local.json    # 本地设置（不提交到 git）
    ├── keybindings.json       # 自定义键盘快捷键
    ├── agents/                # 自定义 Agent 定义
    │   └── researcher.json
    ├── skills/                # 自定义技能定义
    │   └── deploy-skill.json
    ├── memory/                # 持久化记忆文件
    │   ├── MEMORY.md          # 记忆索引
    │   ├── user_preferences.md
    │   └── project_context.md
    ├── rules/                 # 详细规则文件
    │   ├── coding-standards.md
    │   └── testing-policy.md
    ├── commands/              # 自定义斜杠命令
    │   └── deploy.md
    └── plugins/               # 插件配置

### 5.1 用户级 vs 项目级

层级 | 路径 | 说明
--- | --- | ---
用户级 | `~/.claude/` | 对所有项目生效，包含全局设置、技能、团队配置
项目级 | `.claude/` | 仅对当前项目生效，可提交到 git 与团队共享
本地级 | `.claude/settings.local.json` | 仅对当前项目生效，不提交到 git

### 5.2 配置加载优先级

settings.local.json
最高优先级→ settings.json
项目级→ ~/.claude/settings.json
用户级→ managed-settings.json
管理员托管

## 6. CLAUDE.md 配置

`CLAUDE.md` 是 Claude Code 的项目 README，启动时自动加载并注入系统提示。

### 6.1 最佳实践：路由文件模式

保持 `CLAUDE.md` 精简（< 150 行），作为路由文件指向 `.claude/rules/*.md` 中的详细规则：

    # CLAUDE.md

    ## 项目概览
    全栈 Web 应用，前端 React + TypeScript，后端 Node.js + PostgreSQL

    ## 技术栈
    - 前端: React 18, TypeScript, TailwindCSS
    - 后端: Node.js, Express, Prisma ORM
    - 数据库: PostgreSQL 15
    - 测试: Jest + Playwright

    ## 编码规范
    - 前端组件使用函数式 + Hooks
    - API 响应统一为 { data, error } 格式
    - 数据库迁移使用 Prisma migrate

    ## 详细规则
    - 代码规范: [.claude/rules/coding-standards.md](.claude/rules/coding-standards.md)
    - 测试策略: [.claude/rules/testing-policy.md](.claude/rules/testing-policy.md)
    - 部署流程: [.claude/rules/deployment.md](.claude/rules/deployment.md)

### 6.2 层级结构

CLAUDE.md 支持多层级文件，高层级覆盖低层级：

~/.claude/CLAUDE.md
全局→ CLAUDE.md (项目根目录)
项目→ src/CLAUDE.md
目录级

#### 避免

不要把 `CLAUDE.md` 写成知识库。它是上下文注入，不是文档。详细规则拆到 `.claude/rules/` 中，只保留关键信息在 CLAUDE.md。

## 7. 项目记忆系统

Claude Code 通过 `.claude/memory/` 目录实现跨会话持久记忆，分为四种类型：

类型 | 用途 | 示例
--- | --- | ---
user | 用户的角色、偏好、知识背景 | "用户是后端工程师，偏好接口优先开发"
feedback | 用户对 Claude 行为的指导 | "不要在集成测试中 mock 数据库"
project | 项目进行中工作的上下文 | "2026-04-29 后开始非关键合并冻结"
reference | 外部系统资源的位置 | "Grafana 看板: grafana.internal/d/api-latency"

### 7.1 记忆文件格式

    ---
    name: no-db-mocking
    description: 集成测试必须使用真实数据库
    type: feedback
    ---

    集成测试必须使用真实数据库，不能 mock。
    **Why:** 上季度 mock/prod 差异导致迁移失败但测试通过。
    **How to apply:** 所有 integration test 使用真实 PostgreSQL 实例。

### 7.2 MEMORY.md 索引

`MEMORY.md` 是记忆文件的索引，Claude 启动时加载此文件：

    # 记忆索引

    - [数据库测试偏好](no-db-mocking.md) — 集成测试不用 mock
    - [用户背景](user-role.md) — 资深 Go 工程师，新项目学 Rust
    - [合并冻结](merge-freeze.md) — 2026-04-29 后非关键 PR 暂停

#### 记忆存储位置

记忆文件位于 `/home/zdh/.claude/projects/-home-zdh-projects/memory/`，自动创建和维护。Claude 会根据对话内容自动保存和更新记忆。

### 7.3 什么不该存

- 代码模式、架构、文件路径 — 可以从代码本身读取
- Git 历史、谁改了什么 — `git log` 是权威来源
- 调试方案 — 修复已经在代码里了
- 临时任务细节 — 只在当前会话中相关

## 8. Hooks 自动化

Hooks 是 Claude Code 的自动化机制，在特定事件触发时执行 Shell 命令。由 Claude Code harness 执行，不是 LLM 本身。

### 8.1 配置方式

在 `settings.json` 或 `settings.local.json` 中配置：

    {
      "hooks": {
        "PostToolUse": {
          "Write": "npx eslint --fix",
          "Edit": "npx prettier --write"
        },
        "PreToolUse": {
          "Bash": "echo '即将执行: $CLAUDE_TOOL_INPUT'"
        },
        "Notification": {
          "PostCommand": "say 'Claude 完成'"
        }
      }
    }

### 8.2 可用 Hook 事件

Hook | 触发时机 | 典型用途
--- | --- | ---
`PostToolUse.Write` | 每次写文件后 | 自动 lint/format
`PostToolUse.Edit` | 每次编辑文件后 | 自动格式化
`PostToolUse.Bash` | 每次执行 Bash 命令后 | 验证结果
`PreToolUse.*` | 工具执行前 | 注入上下文、安全检查
`Notification.PostCommand` | Claude 完成回复后 | 桌面通知

#### 重要

自动化行为（"每次编辑后 X"、"从现在开始当 Y 时"）必须通过 settings.json 中的 hooks 配置，不能通过记忆或偏好设置。Claude Code harness 执行 hooks，不是 LLM。

## 9. MCP 服务集成

MCP（Model Context Protocol）让 Claude Code 连接外部工具：文件系统、API、数据库、开发工具等。

### 9.1 安装范围

范围 | 配置位置 | 说明
--- | --- | ---
本地 | `~/.claude/mcp.json` | 仅当前用户可用
项目 | `.claude/mcp.json` | 团队共享，提交到 git
用户 | `~/.claude/mcp.json` | 所有项目可用

### 9.2 配置示例

    {
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
        },
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/zdh/projects"]
        },
        "postgres": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
        }
      }
    }

### 9.3 常用 MCP 服务

#### GitHub

PR 管理、Issue 跟踪、仓库操作。适合代码审查和 CI/CD 集成。

#### Filesystem

受限文件系统访问，限制在指定目录下操作。

#### Database

PostgreSQL、MySQL 等数据库直接查询和 schema 探索。

#### Jira/Confluence

项目管理平台集成，查询 issue 和文档。

#### 提示

目前有 25+ 官方 MCP 服务可用。通过 `/plugin` 命令可以浏览和安装更多社区插件。

## 10. Agent 与 Teams

### 10.1 Agent 系统

Claude Code 支持派生专用 Agent 处理复杂任务。每种 Agent 有不同的工具集和能力：

Agent 类型 | 能力 | 适用场景
--- | --- | ---
general-purpose | 全部工具 | 通用复杂任务
Explore | 只读搜索 | 快速定位代码、文件搜索
Plan | 只读分析 | 设计实现方案、架构分析
claude-code-guide | 搜索+文档 | Claude Code 功能查询

### 10.2 Teams 团队协作

多个 Agent 组成 Team，共享任务列表，并行工作：

    # Team 工作流程
    1. TeamCreate — 创建团队和任务列表
    2. TaskCreate — 创建结构化任务
    3. Agent + team_name — 派生 Agent 加入团队
    4. TaskUpdate + owner — 分配任务给 Agent
    5. Agent 完成任务 → TaskUpdate + status:completed
    6. 所有任务完成后 SendMessage 关闭团队

### 10.3 自定义 Agent

在 `.claude/agents/` 中定义自定义 Agent：

    // .claude/agents/frontend-reviewer.json
    {
      "name": "frontend-reviewer",
      "description": "审查前端代码变更",
      "model": "sonnet",
      "instructions": "审查 React 组件代码，关注性能、可访问性和最佳实践。"
    }

## 11. Plan Mode 规划模式

规划模式是处理复杂变更的最佳实践：先设计方案，再实施。

### 11.1 何时使用

- 新功能实现，涉及多个文件和模块
- 重构现有代码，可能影响多个功能
- 架构决策，需要在多个方案中选择
- 不确定的需求，需要先探索代码库

### 11.2 工作流

/plan 进入规划→ 探索代码库→ 设计方案→ 用户审批→ ExitPlanMode 退出→ 实施变更

#### 推荐

对于涉及 3 个以上文件的变更，总是先使用规划模式。这比直接修改后回退要高效得多。

## 12. Skills 技能系统

Skills 是可复用工作流包，通过 `/技能名` 调用，组合提示词、指令和自定义工具。

### 12.1 可用技能

技能列表在会话中通过系统提醒消息显示。分为两类：

类型 | 路径 | 说明
--- | --- | ---
项目级 | `.claude/skills/` | 仅当前项目可用，随代码共享
用户级 | `~/.claude/skills/` | 所有项目可用

### 12.2 调用方式

    # 调用内置技能
    /review
    /security-review
    /init

    # 调用自定义技能（需要显式调用）
    /project-dir-manager
    /remote-sync
    /loop 5m /status

#### 注意

不要猜测技能名称。只调用系统提醒列表中显示的技能，或用户明确输入 `/技能名` 的技能。

## 13. Settings 配置详解

### 13.1 settings.json 核心字段

v2.1 支持 60+ 设置项和 175+ 配置选项：

    {
      "permissions": {
        "defaultMode": "default"
      },
      "hooks": {
        "PostToolUse": {
          "Write": "npx eslint --fix"
        }
      },
      "env": {
        "NODE_ENV": "development"
      },
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"]
        }
      },
      "allowedTools": ["Bash", "Read", "Edit", "Write"],
      "disabledTools": ["Agent"],
      "model": "opus"
    }

### 13.2 配置层次

settings.local.json
不提交 git→ settings.json
提交 git→ ~/.claude/settings.json
用户全局

#### 提示

个人偏好设置（API key、本地路径）放在 `settings.local.json` 中，避免提交到 git。团队共享配置放在 `settings.json` 中。

## 14. 开发工作流最佳实践

### 14.1 高效提示词编写

差 | 好 | 原因
--- | --- | ---
"修复 bug" | "修复 src/auth.py 第 42 行的空指针异常，当 user_id 为 None 时" | 具体、可操作
"优化性能" | "api/handler.go 的 ListUsers 函数响应超 500ms，数据库查询占 80%，优化它" | 有数据支撑
"加个登录功能" | "在 src/auth/ 中添加 OAuth2 登录，参考 src/oauth/ 中已有的 Google 集成风格" | 有上下文

### 14.2 推荐开发流程

#### 标准开发流程

1. 理解代码 — 让 Claude 先读取相关文件，说"先看看这个模块的代码"

2. 制定方案 — 复杂变更用 `/plan`，让 Claude 展示方案并审批

3. 实施变更 — 审批后 Claude 实施，使用 Default 权限模式逐步确认

4. 验证结果 — 运行测试 `npm test` / `go test` / `pytest`

5. 代码审查 — 运行 `/review` 自查，再 `/security-review`

6. 提交变更 — 让 Claude 创建 commit，遵循项目风格

### 14.3 多文件开发策略

- 独立变更：并行派生多个 Agent 同时处理
- 依赖变更：按顺序处理，先改底层再改上层
- 大规模重构：使用 Plan Mode 拆分步骤，逐步实施

### 14.4 测试驱动开发

    # 推荐：先让 Claude 写测试，再实现功能
    "为 UserService.createUser 写单元测试，包含正常路径和异常路径"
    # 然后：运行测试看失败
    "现在实现 createUser 让测试通过"
    # 最后：确认所有测试通过
    "运行测试确认全部通过"

## 15. 上下文管理策略

### 15.1 上下文窗口管理

Claude Code 有有限的上下文窗口。长对话会逐渐填满，需要管理：

- 自动压缩：Claude Code 在接近限制时自动压缩早期消息
- 手动压缩：使用 `/compact` 主动压缩，保留关键信息
- 新对话：使用 `/clear` 开始全新对话

### 15.2 何时压缩

场景 | 建议
--- | ---
对话超过 50 轮 | 运行 `/compact` 或 `/clear`
完成一个任务，开始下一个 | `/clear` 开始新对话
Claude 开始遗忘早期上下文 | `/compact` 压缩
需要 Claude 记住特定信息 | 保存到 `.claude/memory/` 持久记忆

### 15.3 信息留存策略

对话中的关键信息通过以下方式留存：

- CLAUDE.md：项目结构和规范，每次启动自动加载
- 记忆系统：用户偏好、项目决策、外部资源位置
- 代码本身：最重要的信息是代码本身，不需要额外记忆

## 16. Git 工作流集成

### 16.1 Claude Code 的 Git 操作

Claude Code 可以直接执行 Git 命令，但遵循安全协议：

- 不跳过 hook（`--no-verify`）
- 不强制 push（`--force`），除非用户明确要求
- 不修改 git config
- 创建新 commit 而非 amend，除非用户明确要求

### 16.2 推荐的 Git 工作流

    # 1. 让 Claude 查看当前状态
    "看看当前 git 状态"

    # 2. 让 Claude 创建 commit
    "把刚才的变更提交，写一个简洁的 commit message"

    # 3. 审查 commit
    "看看这个 commit 包含了什么"

    # 4. 创建 PR（需要 gh CLI）
    "创建一个 PR，标题简短，正文用 bullet points 描述变更"

    # 5. 处理冲突
    "这个分支和 main 有冲突，帮我解决"

### 16.3 Worktree 隔离

对于并行开发，使用 Git Worktree 隔离不同分支的工作：

- Claude Code 内置 `EnterWorktree` 支持
- 自动创建临时分支和工作目录
- 完成后自动清理或保留

## 17. 安全与权限

### 17.1 Claude Code 安全原则

- 默认安全：Default 模式下，危险操作需要确认
- 不执行不可信代码：Claude 不会直接运行从网上复制的代码
- 不暴露密钥：Claude 避免将敏感文件（.env、credentials）提交到 git
- OWASP 安全：Claude 避免引入 XSS、SQL 注入等常见漏洞

### 17.2 安全审查

在合并变更前运行 `/security-review`，检查：

- SQL 注入和参数化查询
- XSS 和输入验证
- 认证和授权绕过
- 敏感数据泄露
- 依赖安全问题

#### 重要提醒

Claude Code 仅辅助授权安全测试、防御安全、CTF 竞赛和教育场景。拒绝拒绝技术、DoS 攻击、大规模攻击、供应链妥协或恶意检测规避的请求。

## 18. 性能优化

### 18.1 响应速度

优化 | 方法 | 效果
--- | --- | ---
减少上下文 | 定期 `/compact`，精简 CLAUDE.md | 减少 token 处理时间
并行 Agent | 独立任务同时派生多个 Agent | 减少串行等待
权限白名单 | 只读操作加入 settings.json allow | 减少审批等待
后台任务 | 长时间命令 `run_in_background: true` | 不阻塞 Claude 响应

### 18.2 避免的反模式

- 不要 sleep 轮询：用 `run_in_background` + 等待完成
- 不要重复搜索：Agent 的 Explore 模式结果复用
- 不要全量扫描：`find` 从 `.` 开始，不扫描整个文件系统
- 不要过度抽象：3 行相似代码优于半成品的抽象

#### 提示

使用 Fast Mode（`/fast`）获取更快的响应速度，使用 Claude Opus 4.6 模型快速输出（不会降级到小模型）。

## 19. Loop 与定时任务

### 19.1 Loop 循环执行

`/loop` 命令按固定间隔重复执行提示或命令：

    # 每 5 分钟检查构建状态
    /loop 5m 检查 CI 构建是否完成

    # 每 10 分钟运行测试
    /loop 10m /review

    # 默认间隔 10 分钟
    /loop /status

### 19.2 ScheduleWakeup 定时唤醒

更精细的定时控制，支持一次性或重复任务：

- 一次性：60s-3600s 范围内，适合"1 小时后提醒我"
- 重复：最小 60s，最大 3600s（1 小时）
- 自动过期：重复任务 7 天后自动过期

### 19.3 Cron 调度

通过 `CronCreate` 工具支持标准 5 字段 cron 表达式：

    # 每个工作日 9am
    "0 9 * * 1-5"

    # 每 5 分钟
    "*/5 * * * *"

    # 今天下午 2:30 一次性
    "30 14 29 4 *" (recurring: false)

#### 注意

定时任务只在 Claude Code 会话活跃期间执行。Cron 任务可以通过 `durable: true` 持久化到 `.claude/scheduled_tasks.json`，重启后恢复。

## 20. 常见问题

### Q: Claude Code 和 Claude API 有什么区别？

Claude Code 是 CLI 工具，内置文件操作、Shell 执行、Git 集成。Claude API 是原始 API，需要自己编写所有集成代码。

### Q: Claude Code 能看到我整个代码库吗？

不会。Claude Code 按需读取文件，不会自动扫描整个代码库。对于大项目，建议让 Claude 搜索相关文件而不是读取全部。

### Q: 如何保护敏感信息？

Claude Code 会避免将 .env、credentials.json 等敏感文件提交到 git。但最好的实践是确保这些文件已在 .gitignore 中。

### Q: Claude 会记住什么？

对话历史在当前会话中保留。跨会话记忆通过 `.claude/memory/` 持久化。CLAUDE.md 每次启动时自动加载。

### Q: 如何让 Claude 更自主地工作？

切换到 Auto 权限模式，为常用只读操作配置权限白名单，使用 Hooks 实现自动化后处理。

### Q: Claude Code 能用来做 CI/CD 吗？

可以。使用 `--print` 标志在无头模式下运行，或结合 GitHub Actions 等 CI 系统。

### Q: 自定义斜杠命令怎么创建？

在 `.claude/commands/` 目录下创建 `.md` 文件，或通过 Agent SDK 编程创建复杂命令。

### Q: 如何选择模型？

通过 `/config` 或在 settings.json 中设置 `"model": "opus"` / `"model": "sonnet"` / `"model": "haiku"`。Opus 最强，Sonnet 平衡，Haiku 最快。