Claude Code 使用手册
与能力全景

00Claude Code 是什么 · 能做什么

Claude Code 是 Anthropic 官方的终端 AI 编程代理(agentic coding tool)。它不是聊天窗口,而是一个能直接在你的电脑上读写文件、执行命令、搜索代码、操作 Git、调用外部服务的智能体。你用自然语言描述目标,它自己规划步骤、调用工具、验证结果。

01安装与登录

系统要求

macOS 13+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+,4GB 内存以上,需联网。Shell 支持 Bash / Zsh / PowerShell / CMD。

教程:四种安装方式

# 方式1:官方安装器(推荐,自带自动更新)—— macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# 方式2:Homebrew(macOS)
brew install --cask claude-code

# 方式3:npm
npm install -g @anthropic-ai/claude-code

# 验证安装 + 健康检查
claude --version
claude doctor

教程:两种登录方式

• 订阅登录(推荐):有 Claude Pro / Max / Team / Enterprise 订阅的,直接在终端输入 claude,首次运行会打开浏览器完成 OAuth 授权,无需 API Key,用量计入订阅额度。
• API Key:从 platform.claude.com 创建 Key 后 export ANTHROPIC_API_KEY=sk-ant-xxx,按 token 计费。也支持走 Amazon Bedrock / Google Vertex / Microsoft Foundry(设置 CLAUDE_CODE_USE_BEDROCK=1 等环境变量)。

# CI / 脚本用:生成一年期长效 token
claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN=<生成的token>

02基本交互:REPL 与命令行参数

教程:第一次使用

cd 你的项目目录
claude                          # 进入交互式会话

# 会话里直接说人话:
> 这个项目是做什么的?入口在哪?
> 给 src/auth.ts 加上登录失败次数限制,并补测试
> 跑一下测试,失败的话修到通过为止

它会自动读文件、搜代码、提出修改;每次要写文件或跑命令时弹出确认,你按回车批准或拒绝。

常用命令行参数

03键盘快捷键与输入技巧

四个改变效率的输入前缀

核心快捷键

多行输入

行尾 \ + 回车(所有终端通用);或 Shift+Enter(iTerm2 / Warp / Ghostty / Windows Terminal 等);或 Ctrl+J。

Vim 模式

在 /config 里把 Editor mode 设为 vim,输入框即支持 NORMAL / INSERT / VISUAL 模式,h j k l、dd、ciw 等常用操作可用。

04内置斜杠命令大全

会话中输入 / 即可唤出菜单。以下按用途分组,均可输入 /help <命令名> 查看详情。

会话与上下文

模型与推理

配置与状态

代码质量与工程

扩展与集成

05记忆系统:CLAUDE.md 与自动记忆

CLAUDE.md 是每次会话开始时自动加载的"项目说明书",用来告诉 Claude 你的规范和习惯;自动记忆(Auto-Memory)则是 Claude 自己跨会话记笔记。

CLAUDE.md 的层级(由宽到窄)

教程:三步建立项目记忆

# 1. 在项目根目录运行,自动扫描生成初版
/init

# 2. 工作中随手补充 —— # 前缀一句话入库
# 测试一律用 vitest,不要用 jest

# 3. 定期整理
/memory     # 打开编辑界面

CLAUDE.md 写法示例

# 项目概览
- TypeScript + React,pnpm monorepo

# 构建与测试
- 构建:pnpm build   测试:pnpm test   Lint:pnpm lint

# 代码规范
- 2 空格缩进;用 async/await 不用裸 Promise
- API handler 统一放 src/api/handlers/

# 引用其他文档(@ 导入语法,启动时自动展开,最多递归4层)
@docs/git-workflow.md
@README.md

自动记忆(Auto-Memory)

Claude 会把跨会话有用的事实(调试结论、你的偏好、项目约束)写进 ~/.claude/projects/<项目>/memory/,其中索引文件 MEMORY.md 每次开新会话自动载入。无需配置,可在 /memory 或 settings 里关闭。

06权限系统与 settings.json

Claude Code 的安全基石:每个工具调用都要经过权限规则。规则写在 settings.json 里,支持用户级、项目级、项目本地级、企业管控级四层。

配置文件位置(优先级从高到低)

1. 企业管控 managed-settings.json(IT 下发,不可覆盖)
2. 命令行 --settings
3. .claude/settings.local.json(项目·个人,gitignore)
4. .claude/settings.json(项目·团队共享)
5. ~/.claude/settings.json(用户全局)

教程:一份典型的项目 settings.json

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(npm run lint)",      // 精确匹配
      "Bash(npm test *)",        // 前缀通配
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",            // 保护密钥文件
      "Read(./secrets/**)",
      "Bash(curl *)"
    ]
  },
  "env": { "NODE_ENV": "development" },
  "model": "claude-sonnet-5"
}

规则语法为 工具名(模式):Bash(git commit *) 放行所有 git commit;Edit(src/**) 允许编辑 src 下所有文件;Read(~/.ssh/*) 可用于 deny 保护敏感路径。

07权限模式与 Plan Mode

模式一览(按 Shift+Tab 循环切换)

教程:用 Plan Mode 做大重构

claude --permission-mode plan        # 或会话内 Shift+Tab 切到 plan

> 把项目的鉴权从 session 改成 JWT,先给我完整方案

# Claude 只读代码 → 输出分步计划(改哪些文件、什么顺序、风险点)
# 你批准后它自动切回可执行模式开始动手;不满意就继续讨论方案

08自定义命令与 Skills

Skills 是可复用的工作流包:平时不占上下文,输入 /名字 调用(或 Claude 判断相关时自动加载)。适合把团队的固定流程(审片、发布、部署、review 清单)固化成一条命令。

教程:创建一个 /deploy 技能

# 目录结构
.claude/skills/
└── deploy/
    ├── SKILL.md        # 技能定义
    └── checklist.md    # 附属资料(按需被读取)

---
description: "部署当前项目到 staging,含构建、检查、通知全流程"
---

# Deploy 流程

1. 运行 `pnpm build`,失败则停止并报告
2. 运行 `pnpm test`,全绿才继续
3. 执行 `./scripts/deploy-staging.sh`
4. 部署后 curl 健康检查接口,贴出结果
5. 按 @checklist.md 逐项确认

## 注意
- 永远不部署 main 以外的分支到 production
- 部署失败时收集最近 50 行日志一并报告

# 使用
/deploy
# 无头模式同样可用:
claude -p "/deploy" --allowedTools "Bash,Read"

09Hooks:确定性自动化

Hooks 是在生命周期节点必定执行的 shell 命令 —— 不依赖模型"记得做",适合强制 lint、格式化、审计、拦截危险命令。

事件类型

教程:每次编辑后自动 lint

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint --silent" }
        ]
      }
    ]
  }
}

教程:拦截危险命令(PreToolUse)

#!/bin/bash
# hook 从 stdin 收到 JSON,含 tool 与 tool_input
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
if [[ "$cmd" == *"rm -rf /"* ]]; then
  echo '{"hookSpecificOutput":{"permissionDecision":"deny","reason":"危险命令已拦截"}}'
  exit 0
fi
echo "{}"

hook 输出 JSON 可以三选一:放行(allow)、拒绝(deny + 理由)、改写输入(updatedInput)。配置可放用户级或项目级 settings。想让 Claude 帮你配,直接说"每次改完文件自动跑 prettier"即可。

10Subagents 子代理与并行

子代理是运行在独立上下文里的专职 Claude 实例:主会话把任务委派出去,只收回结论摘要 —— 既能并行加速,又避免海量搜索结果污染主上下文。

什么时候用

• 大范围代码搜索 / 代码库摸底(结果多但你只要结论)
• 并行审查:一个查安全、一个查性能、一个查风格,同时跑
• 隔离高噪音操作:让子代理去跑测试读日志,主会话只收"3 个失败,原因是 X"

教程:自定义一个审查子代理

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 专职代码审查,检查 bug 与最佳实践
tools: Read, Grep, Glob
model: sonnet          # 可选:给简单任务配便宜模型
---
你是资深代码审查员。只读不改,输出:问题列表(带文件行号)+ 修复建议。

# 使用:直接在对话里点名
> 用 code-reviewer 审查 src/pay/ 目录

# 或者让 Claude 自主并行:
> 同时从安全、性能、可读性三个角度审这次改动,各起一个子代理

11MCP:连接外部工具

MCP(Model Context Protocol)是开放协议,让 Claude Code 接入数据库、Slack、GitHub、Jira、Sentry、浏览器、Figma 等外部系统 —— 接入后这些服务的操作就变成 Claude 可调用的工具。

教程:添加 MCP 服务器

# 远程 HTTP 服务(例:GitHub 官方 MCP)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# 本地 stdio 服务(例:PostgreSQL)
claude mcp add postgres -- npx @modelcontextprotocol/server-postgres \
  "postgresql://user:pass@localhost/db"

# 查看 / 管理已连接的服务器
/mcp

团队共享可把配置写进项目根目录 .mcp.json 提交 git,队友打开项目即用。

接入后的玩法示例

> 查一下数据库:近30天注册用户按渠道分组的数量
> 把这次发布摘要发到 Slack #engineering 频道
> 从 Sentry 拉过去一小时的报错,按频次排序并定位代码
> 用 Chrome DevTools MCP 打开预发环境页面,截图检查布局

12无头模式与脚本化 / CI

claude -p 让 Claude Code 变成一个可以放进管道、脚本、CI 的命令行工具。

教程:管道与结构化输出

# 把任何东西喂给它
cat build-error.log | claude -p "这个报错的根因是什么?"
git diff main | claude -p "审查这次改动的安全问题"

# JSON 输出,配 jq 取字段
claude -p "列出项目里所有 TODO" --output-format json | jq -r '.result'

# 严格结构化输出(给定 JSON Schema,保证可解析)
claude -p "提取本文件所有函数名" \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}'

教程:GitHub Actions 里自动审 PR

- name: Claude review
  run: |
    gh pr diff ${{ github.event.pull_request.number }} | \
      claude -p "做安全向代码审查,输出问题清单" \
        --allowedTools "Read,Bash(git *)" \
        --output-format json | jq -r .result
  env:
    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_TOKEN }}

另有官方 GitHub App:在 PR / Issue 里 @claude 即可让它修 bug、实现需求并自动提交(安装:会话内运行 /install-github-app)。

13Git / GitHub 工作流

日常用法(直接说就行)

> 把当前改动分成两个逻辑独立的 commit,写好 message
> 开个分支 fix/login-rate-limit,把刚才的修复提交上去
> 基于这个分支发 PR,描述里带上改动摘要和测试说明
> 看下 PR #128 的 review 意见,逐条修复并回复
> rebase main 之后把冲突解掉

Claude 会遵循你项目的 commit 规范(写进 CLAUDE.md 即可),GitHub 操作走 gh CLI。/review 128 可直接审查某个 PR。

14IDE、桌面与 Web 集成

15Checkpoint 与 Rewind 回滚

Claude 每次改文件前自动打检查点(最近 100 个)。改崩了不用慌 —— 双击 Esc 或 /rewind 打开回滚菜单。

回滚选项

• 只回滚代码:文件恢复到该检查点,对话保留(最常用 —— "撤销刚才的改动,但我们继续讨论")
• 只回滚对话:消息回到该点,文件保持现状(换个问法重来)
• 代码 + 对话都回滚:完整回到该时刻

16上下文管理与成本控制

看清 token 去哪了

/context    # 可视化:系统提示 / CLAUDE.md / MCP工具 / 对话历史各占多少
/usage      # 本会话用量与订阅配额

五个实用习惯

1. 一个任务一个会话:换任务就 /clear,别让无关历史堆积。
2. 长会话及时压缩:/compact 保留代码决策,丢弃调试过程;上下文快满时系统也会自动压缩,压缩后工作无缝继续。
3. 模型分层:摸底、批量小改用 /model haiku 或 sonnet,硬骨头再上 opus;子代理单独指定便宜模型。
4. 噪音进子代理:跑测试、扫日志这类高输出操作委派出去,主会话只收摘要。
5. 脚本加预算:--max-budget-usd 设硬上限。

17Agent SDK(Python / TypeScript)

想把 Claude Code 的代理能力(工具循环、权限、子代理、hooks)嵌进你自己的程序?用 Agent SDK。

# 安装
npm install @anthropic-ai/claude-agent-sdk     # TypeScript
pip install claude-agent-sdk                   # Python

最小示例(Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="找出并修复 auth.py 里的 bug",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

SDK 同样支持:会话恢复(resume)、结构化输出(json_schema)、自定义子代理、Hooks 回调、MCP 接入 —— 与 CLI 是同一套引擎。典型产品形态:代码审查机器人、客服代理、数据管道里的智能处理节点。

18安全模型

• 权限即防线:所有写操作与命令默认需确认;allow/deny 规则 + 受保护路径(.git、.env、shell 配置等)双重兜底。
• Prompt Injection 防护:文件内容、命令输出、网页里混入的恶意指令会被客户端与服务端双层扫描标记;auto 模式另有独立安全分类器审查每个敏感动作(拦截 force push、下载执行、凭证外发等)。
• 沙箱:settings 里可开启 sandbox,让 Bash 在受限隔离环境执行。
• 企业管控:IT 可下发 managed-settings.json 强制权限策略、登录方式与统一规范,用户无法覆盖。
• 凭证建议:优先 OAuth 订阅登录;.env、secrets/ 写进 deny;对外发布代码前跑 /security-review。

19场景速查:20 个典型用法

20附录:常用环境变量