第一章 Claude Code 高效使用手册

导读｜读完这章能做什么

• 配置权限白名单减少 70% 确认弹框
• 用 Meta+P 快速切模型省钱
• 用 --json-schema 做 CI 集成

从源码中整理的技巧、隐藏命令、高级配置，帮助开发者更高效地使用 Claude Code。

一、常用但文档未覆盖的 CLI 参数

结构化输出：让 Claude Code 返回 JSON

claude --print "分析这个项目的依赖" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"deps":{"type":"array","items":{"type":"string"}},"risks":{"type":"array"}}}'

返回的不是对话文本，而是严格符合 schema 的 JSON。适合写脚本和做 CI 集成。

Bare 模式：最小化启动

claude --bare --system-prompt "你是一个 shell 脚本专家"

跳过所有自动发现：CLAUDE.md、hooks、LSP、plugins、keychain、auto-memory。启动速度最快，适合在沙盒/CI 中使用。

在我的 ~/.bashrc 或 ~/.zshrc 中添加以下 Claude Code 快捷别名（如果已存在就跳过）：
alias cc='claude'
alias ccp='claude --print'
alias ccf='claude --fast'
alias ccb='claude --bare'
alias ccr='claude --resume'
alias ccc='claude --continue'

预填充 Prompt（不提交）

claude --prefill "帮我重构 src/utils/ 下所有"

打开交互界面时 prompt 已填好，可以编辑后再提交。适合常用的长 prompt 模板。

分叉会话：从断点开始新分支

claude --resume abc123 --fork-session

恢复旧会话但创建新的 session ID——原会话不受影响。适合 "如果我换一种方法" 的探索。

文件时间回溯

claude --resume abc123 --rewind-files user-msg-id

恢复会话，同时把项目文件恢复到那条消息时的状态。后悔改了某些文件？用这个。

流式 JSON 管道

echo '{"type":"user","content":"list all TODO items"}' | \
  claude --print --input-format stream-json --output-format stream-json

标准输入/输出都是 JSON 流——可以和其他工具管道组合。

花钱上限

claude --print "大规模重构" --max-budget-usd 5.00

超过 5 美元自动停止。防止失控的 Agent 循环消耗额度。

多目录上下文

claude --add-dir ../shared-libs --add-dir ../docs

让 Claude Code 同时看到多个目录的代码——跨仓库工作时需要。

Worktree + Tmux 一键隔离

claude --worktree feature-x --tmux

自动创建 Git worktree + tmux session，在隔离环境中工作。完成后用 /exit 选择保留或删除。

二、快捷键参考

多数用户只用 Enter 和 Ctrl+C，但 Claude Code 有一套完整的快捷键系统：

常用快捷键

确认对话框中的快捷键

自定义快捷键

编辑 ~/.claude/keybindings.json：

{
  "keybindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+shift+r": "review",
        "ctrl+shift+t": "test"
      }
    }
  ]
}

注意： Ctrl+C 和 Ctrl+D 不可重绑定（保留给中断和退出）。

帮我创建 Claude Code 自定义快捷键配置文件 ~/.claude/keybindings.json，添加以下快捷键：Ctrl+Shift+R 触发 review，Ctrl+Shift+T 触发 test。如果文件已存在就合并。

三、CLAUDE.md 高级用法

自动发现机制

Claude Code 会向上递归扫描所有父目录的 CLAUDE.md：

/home/user/projects/my-app/src/  ← 当前目录
/home/user/projects/my-app/CLAUDE.md  ← 加载
/home/user/projects/CLAUDE.md    ← 也加载
/home/user/CLAUDE.md             ← 也加载

所以可以在 ~/CLAUDE.md 放全局偏好，在项目根目录放项目规则。

特殊 Section Headers

# claude
主要指令和上下文（始终加载）

# claude up
初始化命令（/up 命令触发）

# claude tools
工具特定指令

# claude settings
内联配置（会被解析为 settings）

# claude hooks
Hook 定义（替代 settings.json）

# claude agents
Agent 定义

外部文件引用

<!-- @include ./coding-standards.md -->
<!-- @include ./api-docs.md -->

CLAUDE.md 可以引用外部文件——保持主文件简洁，详细内容分文件。

帮我在项目 CLAUDE.md 中添加 @include 引用：如果项目有 coding-standards.md 就引用它，如果有 api-docs.md 也引用。用 <!-- @include ./filename.md --> 格式。先检查这些文件是否存在。

禁用 CLAUDE.md 自动发现

CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 claude
# 或
claude --bare

四、权限配置的实用策略

减少重复确认

每次都弹 "Allow Bash(git status)?" 确认框？在 settings.json 中配置一次，之后不再弹窗：

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:test)",
      "Bash(npm:run:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(find:*)",
      "Bash(grep:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(chmod:777:*)"
    ]
  }
}

帮我配置 Claude Code 权限白名单。编辑 ~/.claude/settings.json，在 permissions 中设置以下规则（如果文件已存在就合并，不覆盖其他配置）：

allow:
- Read, Glob, Grep
- Bash(git:*), Bash(npm:test), Bash(npm:run:*), Bash(npx:*)
- Bash(node:*), Bash(python:*), Bash(bun:*), Bash(cargo:*), Bash(go:*)
- Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(tail:*)
- Bash(find:*), Bash(grep:*), Bash(rg:*), Bash(wc:*)
- Bash(echo:*), Bash(which:*), Bash(env:*), Bash(pwd), Bash(date)
- Bash(mkdir:*), Bash(touch:*), Bash(cp:*), Bash(mv:*)

deny:
- Bash(rm:-rf:*), Bash(sudo:*), Bash(chmod:777:*)
- Bash(curl:*:POST:*), Bash(dd:*), Bash(kill:-9:*), Bash(pkill:*)

权限规则语法

"Bash(git:*)"        → 所有 git 命令
"Read(*.ts)"         → 读取所有 .ts 文件
"Edit(src/**/*.tsx)"  → 编辑 src 下所有 .tsx
"Write"              → 所有写操作
"Bash(npm:run:*)"    → 所有 npm scripts

快速模式切换

在对话中按 Shift+Tab 循环切换：

default (逐一确认) → acceptEdits (自动接受编辑) → plan (规划模式)

或者直接：

claude --dangerously-skip-permissions  # 完全跳过（仅你信任的项目）

权限决策链的完整流程可参考第六章。

五、Hook 系统：自动化工作流

例 1：每次编辑后自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "prettier --write $CHANGED_FILES",
        "if": "Edit(*)",
        "timeout": 10
      }
    ]
  }
}

帮我在 ~/.claude/settings.json 中添加 Hook 配置：每次 Edit 工具执行后，自动运行 prettier --write 格式化修改过的文件。设为异步执行、超时 10 秒。如果 hooks 字段不存在就创建，已存在就追加不覆盖。

例 2：每次 Bash 后自动 git add

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "git add -A",
        "if": "Bash(git:*)",
        "timeout": 5
      }
    ]
  }
}

帮我在 ~/.claude/settings.json 的 hooks.PostToolUse 中添加一个 Hook：每次执行 git 相关的 Bash 命令后，自动运行 git add -A。超时 5 秒。如果已存在就追加。

例 3：Agent 验证器——完成后自动跑测试

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "agent",
        "prompt": "Run unit tests and verify all pass. If any fail, explain why.",
        "model": "claude-sonnet-4-6",
        "timeout": 120,
        "if": "Edit(src/**/*)"
      }
    ]
  }
}

帮我在 ~/.claude/settings.json 中添加一个 Agent 类型的 Hook：每次编辑 src/ 下的文件后，自动用 claude-sonnet-4-6 跑一遍单元测试并验证是否通过。超时 120 秒。

例 4：HTTP Webhook 通知

{
  "hooks": {
    "SessionEnd": [
      {
        "type": "http",
        "url": "https://hooks.slack.com/services/YOUR/WEBHOOK",
        "headers": {
          "Content-Type": "application/json"
        },
        "timeout": 5
      }
    ]
  }
}

帮我在 ~/.claude/settings.json 中添加一个 SessionEnd Hook，类型是 http，会话结束时发送通知到 Slack webhook。URL 先用占位符，我之后替换。超时 5 秒。

所有 Hook 事件 (26 种)

六、环境变量参考

性能调优

# 禁用非必要网络流量（隐私模式）
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 禁用 prompt caching（调试用）
export DISABLE_PROMPT_CACHING=1

# Bash 工具超时（默认 120秒）
export BASH_MAX_TIMEOUT_MS=300000    # 改为 5 分钟

# 最大并发工具执行数
export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=8

# API 超时
export API_TIMEOUT_MS=60000

帮我在 ~/.bashrc 或 ~/.zshrc 中添加 Claude Code 性能相关环境变量：BASH_MAX_TIMEOUT_MS=300000（5分钟超时）和 ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5-20251001（子Agent用便宜模型）。检查是否已存在，避免重复。

功能开关

# 禁用自动记忆（不想让它记住东西）
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# 禁用自动压缩（手动 /compact 控制）
export DISABLE_AUTO_COMPACT=1

# 禁用 CLAUDE.md 自动发现
export CLAUDE_CODE_DISABLE_CLAUDE_MDS=1

# 禁用后台任务
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

# 启用 LSP 工具（代码智能）
export ENABLE_LSP_TOOL=1

# 启用工具搜索
export ENABLE_TOOL_SEARCH=1

帮我在 ~/.bashrc 或 ~/.zshrc 中添加 Claude Code 隐私模式配置：CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 和 ENABLE_LSP_TOOL=1。检查是否已存在。

模型配置

# 全局默认模型
export ANTHROPIC_MODEL=claude-sonnet-4-6

# 子 Agent 用便宜的模型
export ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5-20251001

# 自定义 API 端点（企业代理）
export ANTHROPIC_BASE_URL=https://my-proxy.company.com/v1

# 自定义请求头
export ANTHROPIC_CUSTOM_HEADERS='{"X-Team": "platform"}'

帮我配置 Claude Code 默认使用 Sonnet 模型（省钱），子 Agent 用 Haiku。在 ~/.bashrc 或 ~/.zshrc 中添加：ANTHROPIC_MODEL=claude-sonnet-4-6 和 ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5-20251001。

代理/网络

# HTTP 代理（小写优先级高于大写）
export https_proxy=http://proxy.company.com:8080
export no_proxy=localhost,127.0.0.1,.company.com

# 让代理做 DNS 解析
export CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1

# 自定义 CA 证书
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

AWS Bedrock / Google Vertex

# 使用 AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-west-2

# 使用 Google Vertex
export CLAUDE_CODE_USE_VERTEX=1
export VERTEX_BASE_URL=https://your-vertex-endpoint

七、模型选择与 Fast 模式

三种模型的使用场景

Fast 模式到底是什么

claude --fast  # 或会话内 /fast 或 Meta+O

Fast 模式的本质： 同样是 Opus 4.6 模型，但使用更快的推理通道。代价是按 "extra usage" 计费，有独立的速率限制。

不可用的情况：

• 免费 Claude AI 账户
• 组织禁用了 extra usage
• 第三方提供商 (Bedrock/Vertex)
• 非 Opus 模型

动态切换模型

对话中任意时刻：

/model sonnet    ← 切换到便宜模型做简单任务
/model opus      ← 切回来做复杂任务

或者用 Meta+P 打开模型选择器。

Effort 级别

claude --effort low     # 快速响应，减少思考
claude --effort high    # 深度分析
claude --effort max     # 最大努力
claude --effort auto    # 模型自己判断

也可以对话中：/effort high

八、会话管理技巧

给会话命名（方便找回）

claude --name "重构认证模块"
# 或对话中
/rename "重构认证模块"

之后 /resume 时可以搜索 "认证" 找到。

从 PR 恢复会话

claude --from-pr 123       # PR 号
claude --from-pr https://github.com/org/repo/pull/123  # URL

自动恢复与该 PR 关联的最新会话。

导出对话

/export   # 导出当前会话为文件
/share    # 分享会话链接

/compact 的高级用法

/compact                                # 默认摘要
/compact "只保留架构决策和 API 设计"      # 自定义摘要指令
/compact "用中文总结，重点保留代码片段"    # 指定语言和重点

技巧： 当上下文快满时，用自定义指令 compact 可以精确控制保留什么。

帮我压缩当前对话上下文。执行 /compact "只保留架构决策、API 设计和关键代码片段，删除探索性对话"。

九、MCP 服务器：扩展 Claude Code 的能力

查看已连接的 MCP 服务器

/mcp

添加自定义 MCP 服务器

方式 1：CLI 参数

claude --mcp-config '{"servers":{"my-db":{"command":"npx","args":["mcp-server-postgres","postgresql://..."]}}}'

方式 2：配置文件 (~/.claude/mcp-servers.json)

{
  "my-db": {
    "command": "npx",
    "args": ["mcp-server-postgres", "postgresql://localhost/mydb"]
  },
  "filesystem": {
    "command": "npx",
    "args": ["@anthropic-ai/mcp-server-filesystem", "/path/to/allowed"]
  }
}

方式 3：从 Claude Desktop 导入

claude mcp add-from-claude-desktop

帮我配置一个 MCP 文件系统服务器：在 ~/.claude/mcp-servers.json 中添加 @anthropic-ai/mcp-server-filesystem，允许访问当前项目目录。如果文件不存在就创建。

严格 MCP 模式

claude --strict-mcp-config --mcp-config my-servers.json

只使用指定的 MCP 服务器，忽略所有其他配置。

十、自定义 Agent 类型

在项目中定义

创建 .claude/agents/reviewer.md：

---
name: reviewer
description: 代码审查专家，只读不写
tools: [Read, Glob, Grep]
model: claude-sonnet-4-6
effort: thorough
permissionMode: acceptEdits
memory: project
maxTurns: 50
---
你是一个代码审查专家。规则：
1. 永远不要修改文件
2. 关注安全漏洞、性能问题、可维护性
3. 用表格总结发现
4. 严重程度分级：Critical / Warning / Info

使用：对话中 Claude Code 会自动发现并在 Agent 工具中提供 reviewer 类型。

帮我创建一个只读代码审查 Agent：在 .claude/agents/reviewer.md 中定义，工具限制为 Read/Glob/Grep，用 claude-sonnet-4-6 模型，最多 50 轮。规则：不修改文件、检查安全漏洞和性能问题、按 Critical/Warning/Info 分级。

多 Agent 的编排模式和协作机制可参考第三章中的架构说明。

全局 Agent（跨项目）

放在 ~/.claude/agents/ 下，所有项目都可用。

CLI 直接定义

claude --agents '{"quick-check":{"description":"快速检查","prompt":"用最少的步骤检查代码健康度"}}'

帮我创建一个项目健康检查 Agent：在 .claude/agents/quick-check.md 中定义，工具为 Read/Glob/Grep/Bash，用 haiku 模型，最多 20 轮。任务：检查 npm audit 漏洞、未处理的 TODO/FIXME、是否有 .env 被 git 追踪、TypeScript any 类型泛滥。输出不超过 20 行摘要。

十一、输出风格定制

内置风格

切换：/config → Output Style

自定义风格

创建 ~/.claude/output-styles/concise.md：

---
name: concise
description: 精简输出，不解释，只给代码
---
规则：
1. 不要解释代码做了什么
2. 不要给出替代方案
3. 直接输出代码/命令
4. 如果是代码修改，只显示 diff
5. 回复控制在 3 行以内（除非是代码块）

帮我创建一个精简输出风格：在 ~/.claude/output-styles/concise.md 中定义，规则：不解释代码、不给替代方案、直接输出代码或命令、回复控制在 3 行以内。

十二、调试与诊断

/doctor 命令

/doctor

自动检查：安装完整性、设置有效性、认证状态、API 连通性、权限配置、Hook 状态、插件状态、MCP 服务器。

Debug 模式

claude --debug "*"                # 所有 debug 信息
claude --debug "api,hooks"        # 只看 API 和 Hooks
claude --debug "!file,!1p"        # 排除特定类别
claude --debug-file debug.log     # 写入文件（不影响终端）

查看上下文使用情况

/context

显示彩色网格，直观展示 Token 使用分布：system prompt、对话历史、工具结果各占多少。

查看成本

/cost

显示当前会话的总费用、总时长、按模型分的 Token 用量。

性能分析

export CLAUDE_CODE_PROFILE_STARTUP=1   # 启动性能分析
export CLAUDE_CODE_PROFILE_QUERY=1     # 查询性能分析

十三、CI/CD 集成模式

Print 模式：脚本友好

# 代码审查 CI
result=$(claude --print "Review this PR for security issues" \
  --output-format json \
  --max-turns 5 \
  --max-budget-usd 1.00)

# 解析 JSON 输出
echo "$result" | jq '.result'

流式输出 + Hook 事件

claude --print "Run full test suite" \
  --output-format stream-json \
  --include-hook-events \
  --include-partial-messages

实时流式获取每一个工具调用、Hook 执行、部分消息。

结构化输出用于自动化

claude --print "分析 package.json 的所有依赖" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "outdated": {"type": "array"},
      "vulnerable": {"type": "array"},
      "unused": {"type": "array"}
    }
  }'

不保存会话（CI 专用）

claude --print "task" --no-session-persistence

十四、隐藏功能

/good-claude

/good-claude

给 Claude 正向反馈的命令——源码暗示可能用于 RLHF 数据收集。

/btw

/btw 顺便说一下，我更喜欢 tabs 而不是 spaces

快速旁注命令，不影响当前任务流。

Buddy 伴侣精灵

源码中有完整的终端伴侣/宠物系统 (src/buddy/)：

• CompanionSprite.tsx — 精灵渲染
• sprites.ts — 精灵图形定义
• useBuddyNotification.tsx — 通知

Feature flag BUDDY 控制开关。

Vim 模式

/vim

真正的 Vim 模式——Escape 切换 INSERT/NORMAL，支持 hjkl 导航。

帮我开启 Claude Code 的 Vim 模式。运行 /vim 命令切换到 Vim 编辑模式，并在 ~/.claude/settings.json 中设置 editorMode 为 vim 使其永久生效。

十五、推荐配置模板

把这些放在 ~/.claude/settings.json 里：

{
  "model": "sonnet",
  "effort": "auto",
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "Bash(git:*)", "Bash(npm:test)", "Bash(npm:run:*)",
      "Bash(ls:*)", "Bash(cat:*)", "Bash(find:*)",
      "Bash(grep:*)", "Bash(rg:*)",
      "Bash(node:*)", "Bash(python:*)",
      "Bash(echo:*)", "Bash(which:*)", "Bash(env:*)"
    ],
    "deny": [
      "Bash(rm:-rf:*)", "Bash(sudo:*)",
      "Bash(chmod:777:*)", "Bash(curl:*:POST:*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "prettier --write --ignore-unknown $CHANGED_FILES 2>/dev/null || true",
        "if": "Edit(*)",
        "timeout": 10,
        "async": true
      }
    ]
  },
  "enableAutoMemory": true
}

加上 ~/CLAUDE.md：

# claude
- 我是全栈开发者，主要使用 TypeScript + React + Node.js
- 偏好函数式编程风格
- 测试框架用 vitest
- 不要给我加 JSDoc 注释除非我要求
- commit message 用中文
- 重要决策先说方案再执行

效果： 常见读取/搜索/git 操作无需确认，格式化自动运行，记忆跨会话保留，个人偏好始终生效。

帮我创建全局 Claude Code 偏好文件 ~/CLAUDE.md，内容：
- 回复用中文
- 不用 emoji
- 重要决策先说方案再执行
- 不确定的事先问，不要猜
- 不要给时间估计
- 修改代码前先读文件
如果文件已存在就追加到末尾，不覆盖已有内容。

下图展示了 Claude Code 的整体架构，便于理解上述配置项如何与各子系统关联：

总结：提高效率的 10 个方向

帮我做 Claude Code 项目初始化（先问我项目用什么语言和框架）：
1. 创建 CLAUDE.md：包含项目语言、框架、测试工具，加上工作规则（先读后改、一次一件事、报错先分析）
2. 创建 .claude/settings.json：权限白名单（放行 git/npm/搜索/读取，拒绝 rm -rf 和 sudo）
3. 创建 .claude/agents/reviewer.md：只读代码审查 Agent（工具限制为 Read/Glob/Grep，最多 50 轮）
完成后逐个汇报创建了什么。