用 AI 做出第一个项目 · 第 1 章
Claude Code 完整手册:从装好到用顺
终端里的 AI 编程助手完整用法:安装、配置、工作流与提效技巧,把「让 AI 写代码」变成稳定的日常。
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 服务器
配置作用域(优先级从高到低)
local.claude.json— 单项目(不进入 VCS).mcp.json— 项目级(共享到 VCS)~/.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.json | OAUTH、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— 将模型选择器映射到自定义 IDautoMemoryDirectory— 自定义记忆目录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-mode | plan / 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 服务器
配置作用域(优先级从高到低)
local.claude.json— 单项目(不进入 VCS).mcp.json— 项目级(共享到 VCS)~/.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.json | OAUTH、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— 将模型选择器映射到自定义 IDautoMemoryDirectory— 自定义记忆目录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-mode | plan / 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 软件著作权申请工具,材料备齐再提交;登记结果以中国版权保护中心审核为准。