Claude Code 完全指南

从入门到精通：CLI flags、Skills、Hooks、工作流、最佳实践。基于官方文档和社区经验整理。

🚀 快速入门

基础操作

操作	快捷键/命令
停止 Claude	`Esc`
回滚操作	`Esc+Esc` 或 `/rewind`
暂存草稿	`Ctrl+S`
后台运行	`Ctrl+B`
外部编辑器	`Ctrl+G`
粘贴图片	`Ctrl+V`（Mac）
执行 Bash	`!command`

启动与恢复

claude                    # 启动交互会话
claude "query"            # 带初始提示启动
claude -c                 # 继续最近会话
claude -r                 # 交互式选择会话
claude -r "<session>"     # 恢复特定会话
claude -p "query"         # 脚本模式，输出后退出
cat file | claude -p "query"  # 处理管道内容

输入框导航

Ctrl+A/E：行首/行尾
Option+←/→：按词跳转
Ctrl+W/U/K：删词/删至行首/删至行尾

📋 CLI Flags 参考

会话管理

Flag	说明	示例
`--name` / `-n`	给会话命名	`claude -n "auth-refactor"`
`--fork-session`	恢复时创建新会话	`claude -r abc123 --fork-session`
`--worktree` / `-w`	在 git worktree 中启动	`claude -w feature-auth`
`--from-pr`	恢复关联到 GitHub PR 的会话	`claude --from-pr 123`

控制模型

Flag	说明
`--model`	指定模型（opus/sonnet）
`--effort`	努力级别（low/medium/high/max），Opus 4.6
`--betas`	启用 beta 功能

脚本模式

Flag	说明
`--print` / `-p`	非交互模式
`--output-format`	输出格式（text/json/stream-json）
`--json-schema`	强制 JSON Schema 输出
`--max-turns`	限制 agentic 轮数
`--max-budget-usd`	限制 API 花费
`--bare`	跳过 hooks/LSP/插件/自动记忆

系统提示词

Flag	说明
`--system-prompt`	替换整个系统提示词
`--system-prompt-file`	从文件加载
`--append-system-prompt`	追加到默认提示词末尾

推荐：用 --append-system-prompt 而不是 replace，保留 Claude Code 内置能力。

权限控制

Flag	说明
`--permission-mode`	权限模式（default/plan/acceptEdits/bypassPermissions）
`--dangerously-skip-permissions`	跳过所有权限提示（慎用）
`--allowedTools`	白名单工具
`--disallowedTools`	禁用工具

远程和 Web

Flag	说明
`--remote`	在 claude.ai 创建 Web 会话
`--remote-control`	启用远程控制
`--teleport`	在本地恢复 Web 会话
`--channels`	启用 MCP 消息推送

🧩 Skills 系统

Skills 是扩展 Claude 能力的核心方式。一个 SKILL.md 文件就能添加新功能。

存放位置

位置	路径	作用范围
个人	`~/.claude/skills/<name>/SKILL.md`	所有项目
项目	`.claude/skills/<name>/SKILL.md`	当前项目
插件	`<plugin>/skills/<name>/SKILL.md`	插件启用时

Frontmatter 字段

---
name: my-skill
description: 技能描述（Claude 用这个决定何时使用）
argument-hint: [issue-number]
disable-model-invocation: true  # 只能手动 /invoke
user-invocable: false  # 从 / 菜单隐藏
allowed-tools: Read, Grep
model: opus
effort: high
context: fork  # 在子代理中运行
agent: Explore
---

参数传递

---
name: fix-issue
description: 修复 GitHub issue
---

修复 GitHub issue $ARGUMENTS。
# 或按位置访问：$0（$1 到 $2）

调用：/fix-issue 123 → $ARGUMENTS = 123

动态上下文注入

用 !`command` 在发送给 Claude 之前执行：

---
name: pr-summary
description: 总结 PR 变更
---

## PR 上下文
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Files: !`gh pr diff --name-only`

总结这个 PR...

内置 Skills

Skill	说明
`/batch <instruction>`	大规模并行修改（5-30 个独立任务）
`/debug [description]`	调试当前会话
`/loop [interval] <prompt>`	定时重复执行
`/simplify [focus]`	审查修改，修复代码质量问题

🪝 Hooks 系统

Hooks 在特定生命周期事件时自动执行 shell 命令。

事件列表

事件	触发时机	可阻止
`PreToolUse`	工具调用前	✅
`PostToolUse`	工具调用后	❌
`PermissionRequest`	权限对话框出现时	✅
`UserPromptSubmit`	用户提交 prompt 时	✅
`SessionStart`	会话开始/恢复时	❌
`Stop`	Claude 完成响应时	✅
`Notification`	Claude 需要输入时	❌
`PreCompact` / `PostCompact`	上下文压缩前后	❌

退出码

退出码	效果
0	操作继续，stdout 添加到上下文
2	阻止操作，stderr 作为反馈给 Claude
其他	操作继续，stderr 仅记录

配置示例

自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

阻止危险命令

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

脚本检查 rm -rf、drop table 等则 exit 2 阻止。

桌面通知

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 需要你的注意\"'"
          }
        ]
      }
    ]
  }
}

Prompt-based Hooks

用 LLM 做判断：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查所有任务是否完成。如果没有，返回 {\"ok\": false, \"reason\": \"还有什么没做\"}。"
          }
        ]
      }
    ]
  }
}

🧠 上下文管理

关键命令

命令	说明
`/clear`	清空上下文，开始新任务
`/compact`	手动压缩上下文
`/btw`	侧问，不影响主上下文

`@` 引用文件

@src/auth/middleware.ts 精确指向文件，省去 Claude 搜索的代价。

HANDOFF.md 交接文档

关闭自动压缩，手动让 Claude 写交接文档（目标、已试什么、什么有效/无效、下一步），新会话只需提供文件路径即可继续。

Auto Memory

Claude 自动维护 ~/.claude/projects/<project>/memory/MEMORY.md，记录构建命令、调试洞察、项目约定等。

📄 CLAUDE.md 配置文件

最佳实践

大小：目标 < 200 行
结构：用 markdown headers 和 bullets
具体性：写可验证的指令

✅ 包含	❌ 排除
Claude 猜不到的 Bash 命令	Claude 能从代码推断的
与默认不同的代码风格	标准语言约定
测试指令和偏好	详细 API 文档（链接即可）
仓库礼仪（分支命名、PR 约定）	频繁变化的信息

`@imports` 保持精简

@docs/git-instructions.md
@docs/testing-guide.md

Claude 按需读取，不占主文件空间。

Claude 犯错后更新

“更新 CLAUDE.md 让这个问题不再发生”

Claude 会自己写规则，下次会话自动遵守。

🔒 权限管理

权限规则语法

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

配置作用域

作用域	位置	共享
User	`~/.claude/settings.json`	否
Project	`.claude/settings.json`	是（提交到 git）
Local	`.claude/settings.local.json`	否（gitignore）

`/permissions` 白名单

停止对 npm run lint 重复点击确认，白名单信任命令。

🎯 高级工作流

Plan Mode 分离探索与执行

Explore：Plan Mode 下读取文件、回答问题，不做修改
Plan：让 Claude 创建详细实现计划
Implement：切换 Normal Mode，按计划编码
Commit：提交并创建 PR

Git Worktrees 并行工作

git worktree add ../feature-branch feature-branch
cd ../feature-branch && claude

容器中运行高风险任务

docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  node:20 \
  claude --dangerously-skip-permissions

💡 最佳实践

给 Claude 验证工作的方式

最重要的一点：包含测试、截图或预期输出，让 Claude 能自我检查。

策略	错误示例	正确示例
提供验证条件	”implement a function that validates email"	"write a validateEmail function. test cases: user@example.com is true, invalid is false. run the tests”
视觉验证 UI	”make the dashboard look better"	"[paste screenshot] implement this design. take a screenshot and compare”
解决根本原因	”the build is failing"	"the build fails with this error: [paste error]. fix it and verify. address root cause”

提供具体上下文

策略	错误示例	正确示例
限定范围	”add tests for foo.py"	"write a test for foo.py covering the edge case where user is logged out”
指向来源	”why does ExecutionFactory have weird api?"	"look through ExecutionFactory’s git history and summarize”
引用模式	”add a calendar widget"	"look at HotDogWidget.php as an example. follow the pattern”

🆕 新功能速览（2025-2026）

新 Slash 命令

命令	说明
`/voice`	语音输入模式
`/remote-control`	桥接到 claude.ai/code
`/effort`	设置模型努力级别
`/color`	设置提示栏颜色
`/sandbox`	管理沙箱设置
`/fork`	分叉当前会话
`/rename`	重命名会话

性能优化

启动内存优化：~60ms 更快，~80MB 内存节省
--resume 大会话提速 45%
响应文本逐行流式输出

📊 监控与调试

命令	说明
`/usage`	查看 Rate Limits
`/stats`	查看使用统计
`/mcp`	管理 MCP 服务器
`/config`	设置输出风格