reference/docs/claude.md

ClaudeCode 备忘清单

ClaudeCode 命令行开发工具快速参考备忘单。

CLI 参考

命令行

命令	描述	示例
claude	启动交互式 REPL	claude
claude "query"	使用初始提示启动 REPL	claude "explain this project"
claude -p "query"	通过 SDK 查询，然后退出	claude -p "explain this function"
cat file | claude -p "query"	处理管道内容	cat logs.txt | claude -p "explain"
claude -c	继续最近的对话	claude -c
claude -c -p "query"	通过 SDK 继续	claude -c -p "Check for type errors"
claude -r "<session-id>" "query"	通过 ID 恢复会话	claude -r "abc123" "Finish this PR"
claude update	更新到最新版本	claude update
claude mcp	配置模型上下文协议 (MCP) 服务器	请参阅 Claude Code MCP 文档。

CLI 标志

使用这些命令行标志自定义 Claude Code 的行为：

标志	描述	示例
--add-dir	添加额外的工作目录供 Claude 访问（验证每个路径是否作为目录存在）	claude --add-dir ../apps ../lib
--allowedTools	除了 settings.json 文件 之外，应该在不提示用户许可的情况下允许的工具列表	"Bash(git log:*)" "Bash(git diff:*)" "Read"
--disallowedTools	除了 settings.json 文件 之外，应该在不提示用户许可的情况下禁止的工具列表	"Bash(git log:*)" "Bash(git diff:*)" "Edit"
--print, -p	打印响应而不使用交互模式（有关编程使用详细信息，请参阅 SDK 文档）	claude -p "query"
--append-system-prompt	附加到系统提示（仅与 --print 一起使用）	claude --append-system-prompt "Custom instruction"
--output-format	为打印模式指定输出格式（选项：text、json、stream-json）	claude -p "query" --output-format json
--input-format	为打印模式指定输入格式（选项：text、stream-json）	claude -p --output-format json --input-format stream-json
--verbose	启用详细日志记录，显示完整的轮次输出（在打印和交互模式中都有助于调试）	claude --verbose
--max-turns	在非交互模式下限制代理轮次数量	claude -p --max-turns 3 "query"
--model	使用最新模型的别名（sonnet 或 opus）或模型的全名为当前会话设置模型	claude --model claude-sonnet-4-20250514
--permission-mode	在指定的权限模式下开始	claude --permission-mode plan
--permission-prompt-tool	指定一个 MCP 工具来处理非交互模式下的权限提示	claude -p --permission-prompt-tool mcp_auth_tool "query"
--resume	通过 ID 恢复特定会话，或在交互模式下选择	claude --resume abc123 "query"
--continue	在当前目录中加载最近的对话	claude --continue
--dangerously-skip-permissions	跳过权限提示（谨慎使用）	claude --dangerously-skip-permissions

内置斜杠命令

命令	用途
/add-dir	添加额外的工作目录
/agents	管理用于专门任务的自定义AI子代理
/bug	报告错误（将对话发送给Anthropic）
/clear	清除对话历史
/compact [instructions]	压缩对话，可选择性地提供重点指令
/config	查看/修改配置
/cost	显示令牌使用统计（请参阅成本跟踪指南了解订阅特定详情）
/doctor	检查您的Claude Code安装的健康状况
/help	获取使用帮助
/init	使用CLAUDE.md指南初始化项目
/login	切换Anthropic账户
/logout	从您的Anthropic账户登出
/mcp	管理MCP服务器连接和OAuth身份验证
/memory	编辑CLAUDE.md内存文件
/model	选择或更改AI模型
/permissions	查看或更新权限
/pr_comments	查看拉取请求评论
/review	请求代码审查
/status	查看账户和系统状态
/terminal-setup	安装Shift+Enter键绑定用于换行（仅限iTerm2和VSCode）
/vim	进入vim模式以在插入和命令模式之间切换

键盘快捷键

通用控制

快捷键	描述	上下文
Ctrl+C	取消当前输入或生成	标准中断
Ctrl+D	退出 Claude Code 会话	EOF 信号
Ctrl+L	清除终端屏幕	保留对话历史
上/下箭头	导航命令历史	回调之前的输入
Esc + Esc	编辑上一条消息	双击 Esc 键修改
Shift+Tab	切换权限模式	在自动接受模式、计划模式和正常模式之间切换

多行输入

方法	快捷键	上下文
快速转义	\ + Enter	在所有终端中有效
macOS 默认	Option+Enter	macOS 上的默认设置
终端设置	Shift+Enter	在 /terminal-setup 之后
控制序列	Ctrl+J	多行换行符
粘贴模式	直接粘贴	用于代码块、日志

快速命令

快捷键	描述	注释
开头的 #	内存快捷键 - 添加到 CLAUDE.md	提示文件选择
开头的 /	斜杠命令	参见斜杠命令
开头的 !	Bash 模式	直接运行命令并将执行输出添加到会话中

Vim 编辑器模式

模式切换

命令	操作	从模式
Esc	进入 NORMAL 模式	INSERT
i	在光标前插入	NORMAL
I	在行首插入	NORMAL
a	在光标后插入	NORMAL
A	在行尾插入	NORMAL
o	在下方打开新行	NORMAL
O	在上方打开新行	NORMAL

导航（NORMAL 模式）

命令	操作
h/j/k/l	向左/下/上/右移动
w	下一个单词
e	单词末尾
b	上一个单词
0	行首
$	行尾
^	第一个非空白字符
gg	输入开头
G	输入末尾

编辑（NORMAL 模式）

命令	操作
x	删除字符
dd	删除行
D	删除到行尾
dw/de/db	删除单词/到末尾/向后
cc	更改行
C	更改到行尾
cw/ce/cb	更改单词/到末尾/向后
.	重复上次更改

Hooks 参考

配置

• ~/.claude/settings.json 用户设置
• .claude/settings.json 项目设置
• .claude/settings.local.json 本地项目设置（不提交）
• 企业管理策略设置

结构

{
    "hooks": {
        "EventName": [
            {
                "matcher": "ToolPattern",
                "hooks": [
                    { "type": "command", "command": "your-command-here" }
                ]
            }
        ]
    }
}

matcher 匹配工具名称的模式，区分大小写（仅适用于 PreToolUse 和 PostToolUse）

• 简单字符串精确匹配：Write 仅匹配 Write 工具
• 支持正则表达式：Edit|Write 或 Notebook.*
• 使用 * 匹配所有工具。您也可以使用空字符串（""）或留空 matcher。

hooks 当模式匹配时要执行的命令数组

• type：目前仅支持 "command"
• command：要执行的 bash 命令（可以使用 $CLAUDE_PROJECT_DIR 环境变量）
• timeout：（可选）命令应该运行多长时间（以秒为单位），在取消该特定命令之前。

项目特定的 Hook 脚本

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
{
    "type": "command",
    "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
}
        ]
      }
    ]
  }
}

可通过环境变量 CLAUDE_PROJECT_DIR 引用项目中的脚本，确保无论 Claude 当前目录如何都能正常使用（仅在生成 hook 命令时可用）

Hook 事件

PreToolUse

常见匹配器

• Task - 子代理任务（参见子代理文档）
• Bash - Shell 命令
• Glob - 文件模式匹配
• Grep - 内容搜索
• Read - 文件读取
• Edit、MultiEdit - 文件编辑
• Write - 文件写入
• WebFetch、WebSearch - Web 操作

在 Claude 创建工具参数之后、处理工具调用之前运行。

其它 Hook

Hook	描述
PostToolUse	在工具成功完成后立即运行。
UserPromptSubmit	当用户提交提示时、Claude 处理之前运行。这允许您根据提示/对话添加额外的上下文、验证提示或阻止某些类型的提示。
Stop	当主 Claude Code 代理完成响应时运行。如果停止是由于用户中断而发生的，则不会运行。
SubagentStop	当 Claude Code 子代理（Task 工具调用）完成响应时运行。

Notification

当 Claude Code 发送通知时运行。通知在以下情况下发送：

Hook	描述
Claude 需要您的权限来使用工具。	示例：“Claude needs your permission to use Bash”
提示输入已空闲至少 60 秒。	“Claude is waiting for your input”

​PreCompact

在 Claude Code 即将运行压缩操作之前运行。

匹配器

Hook	描述
manual	从 /compact 调用
auto	从自动压缩调用（由于上下文窗口已满）

SessionStart

当 Claude Code 启动新会话或恢复现有会话时运行（目前确实会在底层启动新会话）

匹配器

• startup - 从启动调用
• resume - 从 --resume、--continue 或 /resume 调用
• clear - 从 /clear 调用
• compact - 从自动或手动压缩调用。

对于加载开发上下文（如现有问题或代码库的最近更改）很有用。

SessionEnd

hook 输入中的 reason 字段将是以下之一

• clear - 使用 /clear 命令清除会话
• logout - 用户注销
• prompt_input_exit - 用户在提示输入可见时退出
• other - 其他退出原因

当 Claude Code 会话结束时运行。对于清理任务、记录会话统计信息或保存会话状态很有用。

Hook 输入

示例

Hooks 通过 stdin 接收包含会话信息和事件特定数据的 JSON 数据：

{
  // 通用字段
  session_id: string
  // 对话 JSON 的路径
  transcript_path: string  
  // 调用 hook 时的当前工作目录
  cwd: string              

  // 事件特定字段
  hook_event_name: string
  ...
}

PreToolUse 输入

tool_input 的确切模式取决于工具。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

PostToolUse 输入

tool_input 和 tool_response 的确切模式取决于工具。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

Notification 输入

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

UserPromptSubmit 输入

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

Stop 和 SubagentStop 输入

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

当 Claude Code 已经因为 stop hook 而继续时，stop_hook_active 为 true。检查此值或处理记录以防止 Claude Code 无限运行。

PreCompact 输入

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

对于 manual，custom_instructions 来自用户传递给 /compact 的内容。对于 auto，custom_instructions 为空。

SessionStart 输入

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

SessionEnd 输入

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

另见

• Claude 代码参考 (docs.anthropic.com)
• 送你一张Claude Code速查表 (weixin.qq.com)