用 AI 做出第一个项目 · 第 1 章

Claude Code 完整手册:从装好到用顺

终端里的 AI 编程助手完整用法:安装、配置、工作流与提效技巧,把「让 AI 写代码」变成稳定的日常。

  • 学什么Claude Code 完整手册:从装好到用顺
  • 难度L1
  • 预计时间45 分钟
  • 涉及工具AI编程 / Claude Code

Claude Code 完整手册:从装好到用顺

官方 Cheat Sheet 100% 完整还原(Win/Mac 全标注)+ 12 个实战技巧。从快捷键到 MCP 服务器,从记忆文件到成本控制,一网打尽。建议收藏备用。🔥

🎮 一、键盘快捷键

通用(Win / Mac 相同)

快捷键作用
Ctrl+C取消输入 / 生成
Ctrl+D退出会话
Ctrl+L清屏
Ctrl+O切换详细输出
Ctrl+R反向搜索历史
Ctrl+G在编辑器中打开提示词
Ctrl+B后台运行任务
Ctrl+T切换任务列表
Ctrl+V粘贴图片
Ctrl+F(连按 2 次)杀死后台 agents

Win 专属

快捷键作用
Esc回退 / 撤销
Shift+Tab循环切换权限模式
Alt+P切换模型
Alt+J切换角色模式

Mac 专属

快捷键作用
Esc回退 / 撤销
Tab循环切换权限模式

会话选择器

按键作用
↑ / ↓导航
← / →展开 / 折叠
P预览
R重命名
/搜索
A全部项目
B当前分支

⚡ 二、Slash 命令

✅ 所有 Slash 命令均支持 Tab 自动补全。

命令作用
/help显示帮助 + 所有命令
/context查看上下文使用情况 + 优化建议
/compact [focus]带焦点压缩(自动压缩约 95% 容量)
/voice启用语音模式(Mac 按住 Space 录音,支持 20 种语言)
/btw question侧边提问,不占主上下文
/feedback 或 /bug提交反馈
/release-notes查看完整更新日志
/stickers订阅按钮(功能彩蛋)
/simplify代码审查(见 Skills 部分)
/batch大规模并行修改(见 Skills)
/debug [desc]调试排障
/loop [interval]周期性任务
/claude-api加载 API + SDK 参考

🧠 三、工作流与技巧

Plan 模式

  • 模式切换:Shift+Tab(Win)/ Tab(Mac),顺序为:普通 → 自动接受 → Plan 模式
  • 启动时指定:--permission-mode plan

思考与 Effort

  • 开关思考模式:Alt+↑(Win)/ 鼠标菜单(Mac)
  • 输入 ultrathink → 本轮最高 effort
  • 查看思考过程:Ctrl+↓(Win)/ Ctrl+0(Mac)
  • 设置 effort 等级:/effort low / med / high

Git Worktrees

--worktree name       # 每个功能独立分支工作区
isolation: worktree   # Agent 在独立 worktree 中运行
sparsePaths           # 仅 checkout 所需目录
/batch                # 自动创建 worktrees

语音模式

  • /voice 启用,按住 Space 录音,松开发送
  • 支持 20 种语言(英 / 法 / 德 / 捷 / 波……)

上下文管理

  • /context — 查看使用情况 + 优化建议
  • /compact [focus] — 带焦点压缩
  • Auto-compact — 约 95% 容量自动触发
  • 1M context — Opus 4.6(Max / Team / Ent 套餐)
  • CLAUDE.md — 压缩后仍保留

会话进阶用法

claude -c           # 继续最近一次对话
claude -r "name"    # 按名称恢复会话
/btw question       # 侧边问题,不占上下文

SDK / 无头模式

claude -p "query"          # 非交互运行
--output-format json       # 结构化输出
--max-budget-usd 5         # 成本上限(美元)
cat file | claude -p       # 管道输入

调度与远程

/loop 5m msg    # 周期任务(每 5 分钟执行)
/rc             # 远程控制
--remote        # 连接 claude.ai 网页会话

🤖 四、Skills & Agents

内置 Skills

Skill作用
/simplify代码审查(3 个并行 agents)
/batch大规模并行修改(5–30 个 worktrees)
/debug [desc]根据调试日志排序 / 排障
/loop [interval]周期性计划任务
/claude-api加载 API + SDK 参考

自定义 Skill 位置

  • 项目 Skills:.claude/skills/<name>/
  • 个人 Skills:~/.claude/skills/<name>/

Skill Frontmatter(头部 YAML 配置)

description: 自动触发说明
allowed-tools: 跳过权限提示
model: 为 skill 覆盖模型
effort: low/med/high    # 覆盖 effort 等级
context: fork           # 在 subagent 中运行

动态占位符:

  • #ARGUMENTS(Win)/ $ARGUMENTS(Mac)— 用户输入占位符
  • $[CLAUDE_SKILL_DIR](Win)/ ${CLAUDE_SKILL_DIR}(Mac)— Skill 自身目录
  • !cmd — 动态上下文注入

内置 Agents

Agent特点
Explore快速只读(Haiku 模型)
Plan为 plan 模式调研
General完整工具,适合复杂任务
Bash独立上下文终端

Agent Frontmatter(头部配置)

permissionMode: default / acceptEdits / plan / dontAsk / bypass
isolation: worktree     # 在 git worktree 中运行
memory: user | project  # 持久化记忆
background: true        # 后台任务
maxTurns: 数值          # 限制 agentic 轮数

SendMessage — 可自动恢复已停止的 agents(替代旧的 resume)


🔌 五、MCP 服务器

支持的传输类型

transport说明
http远程 HTTP(推荐)
stdio本地进程
sse远程 SSE

管理命令

mcp                    # 交互式界面
claude mcp list        # 列出所有服务器
claude mcp serve       # 将 Claude Code 作为 MCP 服务器

配置作用域(优先级从高到低)

  1. local.claude.json — 单项目(不进入 VCS)
  2. .mcp.json — 项目级(共享到 VCS)
  3. ~/.claude.json — 用户全局

Elicitation — 服务器可在任务执行中主动请求用户输入。


📂 六、记忆与文件

CLAUDE.md 位置(优先级从高到低)

路径作用域
/etc/claude-code/托管级(组织范围)
~/.claude/CLAUDE.md个人级(所有项目)
./CLAUDE.md项目级(团队共享)

规则与导入

  • .claude/rules/*.md — 项目规则
  • ~/.claude/rules/*.md — 用户规则
  • 在 frontmatter 中指定 paths: — 路径专用规则
  • 在 CLAUDE.md 中使用 @path/to/file — 导入外部文件

自动记忆(Auto Memory)

  • 目录:~/.claude/projects/<proj>/memory/
  • 文件:MEMORY.md + 各 topic 文件(自动加载)

压缩后,CLAUDE.md 和记忆文件仍会保留。


⚙️ 七、配置与环境变量

关键配置文件

文件作用
~/.claude/settings.json用户设置
./.claude/settings.json项目设置(共享)
~/.claude.jsonOAUTH、MCP、状态
.mcp.json项目 MCP 服务器

重要环境变量

ANTHROPIC_API_KEY=xxx
ANTHROPIC_MODEL=claude-3-opus-sonnet
CLAUDE_CODE_EFFORT_LEVEL=low / med / high
MAX_THINKING_TOKENS=0    # 0 = 关闭思考
IS_DEMO=true             # 演示模式(隐藏邮箱组)

settings.json 其他配置项

  • modelOverrides — 将模型选择器映射到自定义 ID
  • autoMemoryDirectory — 自定义记忆目录
  • worktree.sparsePaths — Sparse checkouts 目录列表
  • keybindings — 自定义键盘快捷键(Win/Mac 分开)

🖥️ 八、CLI 与 Flags

核心命令

claude                  # 交互式启动
claude "query"          # 携带提示词运行
claude -p "query"       # 无头模式(非交互)
claude -c               # 继续最近一次对话
claude -r "name"        # 按名称恢复会话
claude update           # 更新到最新版

完整 Flags 列表

Flag作用
--model设置模型
--worktree使用 Git worktree
--n / --name指定会话名
--add-dir添加额外目录
--agent使用指定 agent
--allowedTools预批准工具列表
--output-format json / stream输出格式
--json-schema结构化输出 schema
--max-turns限制 agent 轮数
--max-budget-usd 5成本上限(美元)
--console通过 Anthropic Console 认证
--verbose详细输出
--bare极简无头模式(无 hooks / LSP 插件)
--channels权限转发 / MCP 推送
--remote连接 claude.ai 网页会话
--effort low / med / high / max努力程度
--permission-modeplan / default / acceptEdits / dontAsk / bypass
--dangerously-skip-permissions跳过所有权限提示(高危)
--chrome使用 Chrome 浏览器

💡 九、实用小技巧合集

1️⃣ 快速恢复会话

claude -c                # 继续最近一次
claude -r "项目名"        # 按名称恢复,更精准

给会话起名,下次直接按名恢复:

claude --name bugfix-123

2️⃣ 管道 + 无头模式:自动化工作流

# 让 Claude 解释错误日志
cat error.log | claude -p "解释这个错误,给出修复建议"

# 批量生成 commit message
git diff | claude -p "为这些改动生成 commit message"

配合 --output-format json 可以写脚本批量处理。


3️⃣ 成本控制

--max-budget-usd 0.5    # 单次会话上限 0.5 美元
--max-turns 20          # 限制 agent 轮数,防止死循环
--effort low            # 低 effort 省钱,简单任务够用

用 --verbose 查看预估 token 消耗。


4️⃣ 后台任务 + 任务列表

Ctrl+B        → 当前任务放后台
Ctrl+T        → 切换任务列表,查看所有后台任务
Ctrl+F×2      → 杀死后台指定 agent

配合 /loop 10m "检查日志" 开启周期性后台任务,同时在前台处理其他工作。


5️⃣ 手动编辑记忆文件

自动记忆有时不够准确,直接编辑更可靠:

~/.claude/projects/<你的项目>/memory/MEMORY.md

在里面写项目规范、目录结构说明、常见坑点,每次会话自动加载。


6️⃣ /btw 的正确用法

/btw 这个函数的命名规范是什么?

主任务进行中临时提问,不打断主流程,也不消耗主上下文的 token。


7️⃣ Plan 模式 + ultrathink 组合拳

适合复杂设计场景:

# 启动时进入 plan 模式
--permission-mode plan

# 会话中触发最高 effort
ultrathink

用 Ctrl+↓ 查看完整思考过程,确认方案后再 Shift+Tab 切回普通模式执行。


8️⃣ 路径专用规则文件

在项目根目录创建 .claude/rules/style.md:


paths: "*.py"

所有 Python 代码必须遵循 PEP8,使用 type hints,docstring 用 Google 格式。

规则文件支持 glob 路径匹配,不同文件类型自动套用不同规则。


9️⃣ 让 Agent 自动调试

/debug "用户登录接口返回 500"

Claude 会主动插入日志、重跑、分析,而不只是等你贴日志。调试上下文过长时,先 /compact focus 再继续。


🔟 远程会话跨设备联动

claude --remote    # 启动远程会话,自动同步到 claude.ai 网页端

在公司电脑开启远程,回家用浏览器继续,无需复制上下文。


1️⃣1️⃣ 自定义快捷键

在 ~/.claude/settings.json 中配置:

{
  "keybindings": {
    "ctrl+shift+s": "/compact",
    "ctrl+shift+m": "/btw"
  }
}

把高频 Slash 命令绑到顺手的键位上。


1️⃣2️⃣ 极简无头模式(CI/CD 场景)

claude -p "测试所有 API 接口" \
  --bare \
  --output-format json \
  --allowedTools Bash,Read

--bare 禁用 hooks 和 LSP,启动极快;--allowedTools 只给必要权限,安全且干净。


🎁 彩蛋: 在任意会话中输入 /stickers,会弹出一个 emoji 订阅按钮。没什么实际功能,但很好玩 😂

🎮 一、键盘快捷键

通用(Win / Mac 相同)

快捷键作用
Ctrl+C取消输入 / 生成
Ctrl+D退出会话
Ctrl+L清屏
Ctrl+O切换详细输出
Ctrl+R反向搜索历史
Ctrl+G在编辑器中打开提示词
Ctrl+B后台运行任务
Ctrl+T切换任务列表
Ctrl+V粘贴图片
Ctrl+F(连按 2 次)杀死后台 agents

Win 专属

快捷键作用
Esc回退 / 撤销
Shift+Tab循环切换权限模式
Alt+P切换模型
Alt+J切换角色模式

Mac 专属

快捷键作用
Esc回退 / 撤销
Tab循环切换权限模式

会话选择器

按键作用
↑ / ↓导航
← / →展开 / 折叠
P预览
R重命名
/搜索
A全部项目
B当前分支

⚡ 二、Slash 命令

✅ 所有 Slash 命令均支持 Tab 自动补全。

命令作用
/help显示帮助 + 所有命令
/context查看上下文使用情况 + 优化建议
/compact [focus]带焦点压缩(自动压缩约 95% 容量)
/voice启用语音模式(Mac 按住 Space 录音,支持 20 种语言)
/btw question侧边提问,不占主上下文
/feedback 或 /bug提交反馈
/release-notes查看完整更新日志
/stickers订阅按钮(功能彩蛋)
/simplify代码审查(见 Skills 部分)
/batch大规模并行修改(见 Skills)
/debug [desc]调试排障
/loop [interval]周期性任务
/claude-api加载 API + SDK 参考

🧠 三、工作流与技巧

Plan 模式

  • 模式切换:Shift+Tab(Win)/ Tab(Mac),顺序为:普通 → 自动接受 → Plan 模式
  • 启动时指定:--permission-mode plan

思考与 Effort

  • 开关思考模式:Alt+↑(Win)/ 鼠标菜单(Mac)
  • 输入 ultrathink → 本轮最高 effort
  • 查看思考过程:Ctrl+↓(Win)/ Ctrl+0(Mac)
  • 设置 effort 等级:/effort low / med / high

Git Worktrees

--worktree name       # 每个功能独立分支工作区
isolation: worktree   # Agent 在独立 worktree 中运行
sparsePaths           # 仅 checkout 所需目录
/batch                # 自动创建 worktrees

语音模式

  • /voice 启用,按住 Space 录音,松开发送
  • 支持 20 种语言(英 / 法 / 德 / 捷 / 波……)

上下文管理

  • /context — 查看使用情况 + 优化建议
  • /compact [focus] — 带焦点压缩
  • Auto-compact — 约 95% 容量自动触发
  • 1M context — Opus 4.6(Max / Team / Ent 套餐)
  • CLAUDE.md — 压缩后仍保留

会话进阶用法

claude -c           # 继续最近一次对话
claude -r "name"    # 按名称恢复会话
/btw question       # 侧边问题,不占上下文

SDK / 无头模式

claude -p "query"          # 非交互运行
--output-format json       # 结构化输出
--max-budget-usd 5         # 成本上限(美元)
cat file | claude -p       # 管道输入

调度与远程

/loop 5m msg    # 周期任务(每 5 分钟执行)
/rc             # 远程控制
--remote        # 连接 claude.ai 网页会话

🤖 四、Skills & Agents

内置 Skills

Skill作用
/simplify代码审查(3 个并行 agents)
/batch大规模并行修改(5–30 个 worktrees)
/debug [desc]根据调试日志排序 / 排障
/loop [interval]周期性计划任务
/claude-api加载 API + SDK 参考

自定义 Skill 位置

  • 项目 Skills:.claude/skills/<name>/
  • 个人 Skills:~/.claude/skills/<name>/

Skill Frontmatter(头部 YAML 配置)

description: 自动触发说明
allowed-tools: 跳过权限提示
model: 为 skill 覆盖模型
effort: low/med/high    # 覆盖 effort 等级
context: fork           # 在 subagent 中运行

动态占位符:

  • #ARGUMENTS(Win)/ $ARGUMENTS(Mac)— 用户输入占位符
  • $[CLAUDE_SKILL_DIR](Win)/ ${CLAUDE_SKILL_DIR}(Mac)— Skill 自身目录
  • !cmd — 动态上下文注入

内置 Agents

Agent特点
Explore快速只读(Haiku 模型)
Plan为 plan 模式调研
General完整工具,适合复杂任务
Bash独立上下文终端

Agent Frontmatter(头部配置)

permissionMode: default / acceptEdits / plan / dontAsk / bypass
isolation: worktree     # 在 git worktree 中运行
memory: user | project  # 持久化记忆
background: true        # 后台任务
maxTurns: 数值          # 限制 agentic 轮数

SendMessage — 可自动恢复已停止的 agents(替代旧的 resume)


🔌 五、MCP 服务器

支持的传输类型

transport说明
http远程 HTTP(推荐)
stdio本地进程
sse远程 SSE

管理命令

mcp                    # 交互式界面
claude mcp list        # 列出所有服务器
claude mcp serve       # 将 Claude Code 作为 MCP 服务器

配置作用域(优先级从高到低)

  1. local.claude.json — 单项目(不进入 VCS)
  2. .mcp.json — 项目级(共享到 VCS)
  3. ~/.claude.json — 用户全局

Elicitation — 服务器可在任务执行中主动请求用户输入。


📂 六、记忆与文件

CLAUDE.md 位置(优先级从高到低)

路径作用域
/etc/claude-code/托管级(组织范围)
~/.claude/CLAUDE.md个人级(所有项目)
./CLAUDE.md项目级(团队共享)

规则与导入

  • .claude/rules/*.md — 项目规则
  • ~/.claude/rules/*.md — 用户规则
  • 在 frontmatter 中指定 paths: — 路径专用规则
  • 在 CLAUDE.md 中使用 @path/to/file — 导入外部文件

自动记忆(Auto Memory)

  • 目录:~/.claude/projects/<proj>/memory/
  • 文件:MEMORY.md + 各 topic 文件(自动加载)

压缩后,CLAUDE.md 和记忆文件仍会保留。


⚙️ 七、配置与环境变量

关键配置文件

文件作用
~/.claude/settings.json用户设置
./.claude/settings.json项目设置(共享)
~/.claude.jsonOAUTH、MCP、状态
.mcp.json项目 MCP 服务器

重要环境变量

ANTHROPIC_API_KEY=xxx
ANTHROPIC_MODEL=claude-3-opus-sonnet
CLAUDE_CODE_EFFORT_LEVEL=low / med / high
MAX_THINKING_TOKENS=0    # 0 = 关闭思考
IS_DEMO=true             # 演示模式(隐藏邮箱组)

settings.json 其他配置项

  • modelOverrides — 将模型选择器映射到自定义 ID
  • autoMemoryDirectory — 自定义记忆目录
  • worktree.sparsePaths — Sparse checkouts 目录列表
  • keybindings — 自定义键盘快捷键(Win/Mac 分开)

🖥️ 八、CLI 与 Flags

核心命令

claude                  # 交互式启动
claude "query"          # 携带提示词运行
claude -p "query"       # 无头模式(非交互)
claude -c               # 继续最近一次对话
claude -r "name"        # 按名称恢复会话
claude update           # 更新到最新版

完整 Flags 列表

Flag作用
--model设置模型
--worktree使用 Git worktree
--n / --name指定会话名
--add-dir添加额外目录
--agent使用指定 agent
--allowedTools预批准工具列表
--output-format json / stream输出格式
--json-schema结构化输出 schema
--max-turns限制 agent 轮数
--max-budget-usd 5成本上限(美元)
--console通过 Anthropic Console 认证
--verbose详细输出
--bare极简无头模式(无 hooks / LSP 插件)
--channels权限转发 / MCP 推送
--remote连接 claude.ai 网页会话
--effort low / med / high / max努力程度
--permission-modeplan / default / acceptEdits / dontAsk / bypass
--dangerously-skip-permissions跳过所有权限提示(高危)
--chrome使用 Chrome 浏览器

💡 九、实用小技巧合集

1️⃣ 快速恢复会话

claude -c                # 继续最近一次
claude -r "项目名"        # 按名称恢复,更精准

给会话起名,下次直接按名恢复:

claude --name bugfix-123

2️⃣ 管道 + 无头模式:自动化工作流

# 让 Claude 解释错误日志
cat error.log | claude -p "解释这个错误,给出修复建议"

# 批量生成 commit message
git diff | claude -p "为这些改动生成 commit message"

配合 --output-format json 可以写脚本批量处理。


3️⃣ 成本控制

--max-budget-usd 0.5    # 单次会话上限 0.5 美元
--max-turns 20          # 限制 agent 轮数,防止死循环
--effort low            # 低 effort 省钱,简单任务够用

用 --verbose 查看预估 token 消耗。


4️⃣ 后台任务 + 任务列表

Ctrl+B        → 当前任务放后台
Ctrl+T        → 切换任务列表,查看所有后台任务
Ctrl+F×2      → 杀死后台指定 agent

配合 /loop 10m "检查日志" 开启周期性后台任务,同时在前台处理其他工作。


5️⃣ 手动编辑记忆文件

自动记忆有时不够准确,直接编辑更可靠:

~/.claude/projects/<你的项目>/memory/MEMORY.md

在里面写项目规范、目录结构说明、常见坑点,每次会话自动加载。


6️⃣ /btw 的正确用法

/btw 这个函数的命名规范是什么?

主任务进行中临时提问,不打断主流程,也不消耗主上下文的 token。


7️⃣ Plan 模式 + ultrathink 组合拳

适合复杂设计场景:

# 启动时进入 plan 模式
--permission-mode plan

# 会话中触发最高 effort
ultrathink

用 Ctrl+↓ 查看完整思考过程,确认方案后再 Shift+Tab 切回普通模式执行。


8️⃣ 路径专用规则文件

在项目根目录创建 .claude/rules/style.md:


paths: "*.py"

所有 Python 代码必须遵循 PEP8,使用 type hints,docstring 用 Google 格式。

规则文件支持 glob 路径匹配,不同文件类型自动套用不同规则。


9️⃣ 让 Agent 自动调试

/debug "用户登录接口返回 500"

Claude 会主动插入日志、重跑、分析,而不只是等你贴日志。调试上下文过长时,先 /compact focus 再继续。


🔟 远程会话跨设备联动

claude --remote    # 启动远程会话,自动同步到 claude.ai 网页端

在公司电脑开启远程,回家用浏览器继续,无需复制上下文。


1️⃣1️⃣ 自定义快捷键

在 ~/.claude/settings.json 中配置:

{
  "keybindings": {
    "ctrl+shift+s": "/compact",
    "ctrl+shift+m": "/btw"
  }
}

把高频 Slash 命令绑到顺手的键位上。


1️⃣2️⃣ 极简无头模式(CI/CD 场景)

claude -p "测试所有 API 接口" \
  --bare \
  --output-format json \
  --allowedTools Bash,Read

--bare 禁用 hooks 和 LSP,启动极快;--allowedTools 只给必要权限,安全且干净。


🎁 彩蛋: 在任意会话中输入 /stickers,会弹出一个 emoji 订阅按钮。没什么实际功能,但很好玩 😂


做出来了,下一步:登记

项目能跑只是前半程。源码文档整理、申报材料生成这类重复劳动,可以交给软著通——AI 软件著作权申请工具,材料备齐再提交;登记结果以中国版权保护中心审核为准。

软著通下载入口