第 03 章第一次对话

版本基准:2026-07-08 核对,Claude Code v2.1.202+。

3.1 结论先行:四件套 + 自然语言

CC 是状态化 REPL,它的交互语言不是菜单,而是四个前缀符号加上自然语言。掌握这四个前缀,就掌握了 80% 的日常用法:

前缀	名称	一句话作用	是否消耗对话轮
`@`	文件引用	把指定文件内容直接塞进当前上下文	否(随消息进入)
`!`	bash 前缀	在输入框直接执行 shell	否(不进 Agent 循环)
`#`	记忆	把一句话快速写入 auto memory	否(写入文件)
`/`	斜杠命令	调用内置或自定义命令	视命令而定

剩下 20% 是快捷键和编辑器模式,放在本章后半部分。本章版本基准:2026-07-08 / v2.1.202+。在此版本下,旧 /vim 命令已移除(见 GitHub issue),Vim 模式改走 /config → Editor mode 或 settings.json 的 editorMode: "vim" 字段。

这四个前缀背后有一条统一的设计哲学:让人保留对"上下文入口"的精确控制。CC 每轮推理的质量取决于上下文里有什么,而四个前缀分别控制了四类入口——文件内容(@)、shell 输出(!)、持久记忆(#)和命令调用(/)。自然语言负责描述意图,前缀负责精确投喂事实。理解了这一点,后面所有用法都是在回答"这个入口该什么时候开、开多大"。

3.2 交互模式:进入 REPL

在项目目录下启动:

bash

cd ~/work/my-project
claude

CC 会按层级读取配置(全局 ~/.claude/settings.json、项目 .claude/settings.json、本地 .claude/settings.local.json)和 CLAUDE.md,然后进入交互式 REPL。界面底部是输入框,光标停在那里等你说话。

你输入的是自然语言,CC 自己决定调用哪个工具(Read、Grep、Bash、Edit、Agent 等)。你不需要指定工具,但可以通过前缀影响它的行为。一个完整的 Agent 回合是:

text

用户目标 → 模型选择动作 → 工具调用 → 环境返回事实 → 模型更新计划 → 重复直到验证通过

模型本身不知道你的仓库状态,它只能通过工具返回建立事实。所以你的输入质量直接决定 CC 的动作质量:给具体路径,给验证命令,给约束边界。退出 REPL 用 Ctrl+C,或直接关闭终端。

第一次进入项目时,建议先跑三条内置命令摸清状态:

text

> /status
> /permissions
> /context

分别看会话状态、当前权限规则、上下文占用。这三条是只读的,不会改动任何东西。摸清状态后再开始干活,避免在不知道权限策略的情况下让 CC 跑出意料外的动作。

3.3 `@` 文件引用

@ 是最常用的前缀。在输入框里打 @,CC 会弹出文件路径补全;选择或继续输入路径后,该文件的完整内容会作为这条用户消息的一部分进入上下文。

基本用法

text

> 读取 @package.json 和 @src/index.ts,解释入口逻辑

CC 不需要再调用 Read 工具去读这两个文件——内容已经在上下文里了。它直接基于内容回答,省去了一次工具往返。

为什么不走 Read 工具

这是 @ 的关键设计差异:@ 引用的文件内容是作为用户消息的一部分进入上下文的,不经过工具调用通道。因此:

不触发 PreToolUse hook:如果你在 settings.json 里配了 PreToolUse 钩子拦截或审计 Read,@ 引用不会触发它。这在工程上有重要意义——你想审计"CC 读了哪些文件"时,@ 引用是审计盲区,需要单独处理。
不消耗一次工具调用轮次:CC 直接拿到内容,不需要先 Read 再回复,少一轮往返。
不产生工具调用记录:在 transcript 和 /context 里,@ 内容算作用户输入,不是工具结果。

与 Read 的区别与选择

维度	`@` 引用	Read 工具
触发者	用户主动塞入	CC 自主决定调用
PreToolUse hook	不触发	触发
消耗轮次	不消耗	消耗一次工具调用
适用场景	你明确知道要读哪个文件	让 CC 自己探索
大文件	全量塞入(注意 token)	可用 offset/limit 分段
审计可见性	不在工具日志里	在工具日志里

选择原则:你明确知道要读哪个文件、且文件不大时用 @;让 CC 探索未知代码库时,直接用自然语言描述需求,让它自己调 Read/Grep/Glob;大文件优先用 Read 的 offset/limit 分段精读。

失败边界

不存在的路径:手敲完整路径可能引用到不存在的文件,CC 会提示文件不存在,但不会阻塞对话。
超大文件:全量塞入会快速吃掉 token 预算。几千行的文件优先用 Read 工具分段,或先 Grep 定位行号再精读。
二进制文件:内容无法解析,CC 会提示。
审计盲区:若你的 PreToolUse 钩子负责记录所有文件读取行为(如合规审计),@ 引用绕过了这条通道。需要审计时,应让 CC 用 Read 工具而非 @。

3.4 `!` bash 模式

在输入框里以 ! 开头,CC 会把这一行直接当作 shell 命令执行,输出结果打印到终端,然后回到输入框等你下一条。关键特性:不消耗一轮对话——这条命令不进入 Agent 的思考循环,CC 不会基于它的输出决定下一步动作。

基本用法(示例)

text

> !ls -la
total 48
drwxr-xr-x   8 mba  staff   256 Jul  8 10:00 .
drwxr-xr-x  20 mba  staff   640 Jul  8 09:30 ..
-rw-r--r--   1 mba  staff  1234 Jul  8 10:00 package.json
drwxr-xr-x   5 mba  staff   160 Jul  8 10:00 src

text

> !git status --short
M src/index.ts
?? src/new-module.ts

适用场景

! 模式适合你作为人类想快速看一眼环境状态,但不想让 CC 介入分析的场景:

!ls / !tree -L 2:快速看目录结构
!git status / !git diff:看当前改动
!cat package.json:瞄一眼依赖
!node -v / !npm -v:确认运行时版本

这些命令的输出对 CC 来说信息量不大,但对你的决策有用。用 ! 避免浪费一轮 Agent 循环——如果直接说"看一下当前目录",CC 会调 Bash 工具执行 ls,然后分析输出、决定下一步,消耗一轮对话;而你只是想看一眼。

与让 CC 执行命令的区别

如果你直接说"运行 npm test",CC 会用 Bash 工具执行,然后分析输出、决定下一步——这消耗一轮对话,且 CC 会基于结果行动。

用 !npm test,命令直接执行,输出打印给你看,CC 不分析也不行动。你想让 CC 基于测试结果修复时,再在下一条消息里说"刚才的测试失败了,修复它"。

失败边界

权限约束:! 命令仍受权限系统约束。匹配 deny 规则会被拦截;匹配 ask 会弹确认。权限模型详见第 05 章。
输出不进入上下文:CC 看不到 ! 的输出。如果你希望 CC 基于输出行动,要么直接让 CC 执行,要么在下一条消息里把关键输出贴进去或让 CC 重新跑。
长命令阻塞:用 ! 跑长时间命令(如 npm test、npm run dev)会阻塞输入框,改用 Ctrl+B 后台化(见 3.7)。

3.5 `#` 记忆

# 是快速写入 auto memory 的快捷方式。在输入框里以 # 开头打一句话,CC 会把这句话写入当前项目的 memory 文件(~/.claude/projects/<project>/memory/),下次对话自动加载。

基本用法

text

> # 这个项目的生产数据库是 PostgreSQL 16,测试环境用 Docker 容器,连接串在 .env.test

CC 会确认写入,并归类为项目记忆。下次启动 CC 时,这条记忆自动出现在上下文里,你不用再重复说明。

什么该记

跨会话稳定的事实:技术栈版本、数据库类型、部署环境、团队约定。
非显而易见的约束:某个模块不能改、某个 API 有特殊鉴权、某个测试必须连真实数据库。
个人偏好:代码风格、命名习惯、禁止用的库。

什么不该记

临时任务:正在修的 bug、正在写的功能——这些是任务,不是记忆,写在对话或 task list 里。
代码里能直接看到的信息:函数签名、文件路径——CC 用 Read 就能看到,记下来是冗余。
敏感信息:密钥、Token、密码——auto memory 是明文文件,绝不能记。.env 和凭据按红线边界处理。
频繁变化的状态:今天的部署版本号、昨天的测试通过数——会很快过时。

与 CLAUDE.md 的分工

CLAUDE.md 是项目级指令,每轮都进上下文,适合放"团队共享的硬规则"。# 写入的 auto memory 是按需加载的(主索引 MEMORY.md 每次加载,具体记忆文件按相关性召回),适合放"背景信息和个人偏好"。

简单原则:团队共享的硬规则写 CLAUDE.md;个人偏好和项目背景写 # memory。CLAUDE.md 的完整写法与层级加载机制见第 04 章。

3.6 `/` 斜杠命令

/ 开头调用命令。内置命令是 CC 自带的,自定义命令指向 .claude/commands/ 下的 .md 文件(详见第 16 章)。本书严格区分内置与自定义,下表标注"内置"的命令无需安装即可使用。

内置命令速览

命令	作用	备注
`/help`	显示帮助	内置
`/init`	分析项目并生成初始 `CLAUDE.md`	内置
`/compact`	压缩当前对话上下文,释放 token	内置
`/clear`	清空对话,重新开始	内置
`/config`	打开配置界面(模型、权限、编辑器模式等)	内置
`/cost`	显示当前会话的 token 消耗与费用	内置
`/model`	切换模型	内置
`/effort`	调整推理强度	内置
`/memory`	查看/编辑 auto memory	内置
`/theme`	切换主题	内置
`/permissions`	查看当前权限规则	内置
`/context`	查看当前上下文占用	内置
`/status`	查看会话状态	内置
`/review`	代码审查当前改动	内置

注意:/bug 是 /feedback 的别名,用于报告 CC 自身问题,不是"自动修 Bug 模式"。/search、/explain、/dev 不是默认内置命令;代码搜索靠 CC 自主调用 Grep/Glob/Read 完成。遇到不确定的命令,以第 06 章命令真实性总表与附录 A 为准。

常用场景

对话变长、回答变慢时:

text

> /compact

压缩历史,保留关键信息。压缩后 CC 仍记得之前的任务,但 token 占用大幅下降。

换方向、不想被旧上下文干扰时:

text

> /clear

完全清空。/clear 后 auto memory 和 CLAUDE.md 仍会重新加载,真正持久化的信息不会丢。

初始化新项目:

text

> /init

CC 扫描 package.json、目录结构、CI 配置,生成初始 CLAUDE.md。不要保留泛泛而谈的模板,生成后立刻删掉无用段落,只留"长期有效的约束"。CLAUDE.md 的完整写法见第 04 章。

自定义命令

在 .claude/commands/ 下创建 .md 文件即可注册自定义命令。例如 .claude/commands/review-security.md 注册 /review-security,文件内容就是命令被调用时注入的 prompt。完整用法见第 16 章。

3.7 快捷键与 Vim 模式

核心快捷键

快捷键	作用
`Shift+Tab`	循环切换权限模式(default → plan → acceptEdits)
`Ctrl+B`	后台化当前任务(长命令不阻塞输入框)
`Ctrl+O`	verbose 模式,显示工具调用的完整输出
`Esc`	中断 CC 当前动作(不退出 REPL)
`Ctrl+C`	退出 REPL

Shift+Tab:权限模式切换

Shift+Tab 在三种模式间循环:

default:每个有副作用的工具调用都询问
plan:只读分析,禁止任何文件改动与有副作用命令
acceptEdits:自动接受工作区内编辑,其他命令仍询问

常见节奏:进入项目先按两次 Shift+Tab 切到 plan 模式做分析,看完再切回来改代码。这样能在不改动任何东西的前提下让 CC 先摸清现状,确认方案后再放手。权限模型的完整讲解见第 05 章。

Ctrl+B:后台化

长时间运行的命令(如 npm test、npm run dev)会阻塞输入框。按 Ctrl+B 把它后台化,输出转到后台日志,你可以继续输入下一条。CC 会在命令结束时通知你。这对"起服务 + 同时改代码"的工作流至关重要。

Ctrl+O:verbose

默认情况下 CC 会折叠工具调用的输出。按 Ctrl+O 展开,看到 Read 的完整内容、Bash 的完整 stdout。调试"CC 为什么这么做"时非常有用——你能看到它实际读到了什么、命令实际返回了什么。

Vim 模式

注意:旧版的 /vim 命令在 v2.1.x 已移除(见 GitHub issue)。现在通过两种方式启用:

方式一:交互式配置

text

> /config

在配置界面里找到 Editor mode,切换为 vim。

方式二:直接写 settings.json

在 ~/.claude/settings.json 或项目级 .claude/settings.json 里加:

json

{
  "editorMode": "vim"
}

启用后,输入框支持 Vim 风格的模态编辑:Esc 进 normal 模式,i 进 insert 模式,支持 hjkl 移动、dd 删行、yy 复制行等基本操作。不熟悉的用户保持默认 emacs 风格即可,不影响任何功能。

3.8 实战:从零跑通一个 Express 服务器

完整演示 理解需求 → 选择工具 → 执行 → 验证 的工作流。目标:在空目录下初始化一个 Express 服务器,添加 /api/users 路由,启动并验证。每步给命令、预期输出、验证方式与失败边界。

Step 1:准备工作目录

bash

mkdir ~/work/cc-demo && cd ~/work/cc-demo
claude

进入 CC 后,先用 ! 确认环境(示例):

text

> !node -v && npm -v
v20.11.0
10.5.0

验证:Node 18+ 即可。若版本过低,提示用户升级(不擅自改系统级配置,符合红线边界)。

Step 2:初始化项目

直接用自然语言下达任务,让 CC 自主选择工具:

text

> 在当前目录初始化一个 Node.js 项目,安装 express,创建一个 Express 服务器,
> 监听 3000 端口,根路由返回 { status: "ok" }。
> 不要安装 nodemon 等开发依赖,保持最小化。

CC 会调用 Bash 工具执行 npm init -y 和 npm install express,然后用 Write 工具创建 server.js:

javascript

const express = require('express');
const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

验证:

text

> !ls && cat package.json | grep express

预期输出(示例):

text

node_modules  package.json  package-lock.json  server.js
    "express": "^4.19.2"

Step 3:添加路由

text

> 添加一个 GET /api/users 路由,返回模拟的用户列表(字段:id, name)。
> 路由要放在 app.listen 之前。

CC 会用 Edit 工具在 app.listen 之前插入:

javascript

app.get('/api/users', (req, res) => {
  const users = [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
  ];
  res.json(users);
});

Step 4:启动并验证

让 CC 启动服务器并验证:

text

> 启动服务器(后台运行),然后用 curl 验证 /api/users 返回正确的数据。

CC 会执行:

bash

node server.js &
sleep 1
curl -s http://localhost:3000/api/users

预期输出(示例):

text

Server running on http://localhost:3000
[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]

验证:返回是合法的 JSON 数组,包含两条记录。用 !curl -s http://localhost:3000/ 再看根路由:

text

> !curl -s http://localhost:3000/
{"status":"ok"}

失败边界

端口被占用:3000 端口已被占用时,node server.js 报 EADDRINUSE。CC 会看到错误,修复路径是改端口或杀进程:

text

> 端口 3000 被占用了,把监听端口改成 3001,重新启动并验证。

或手动杀进程:

text

> !lsof -ti:3000 | xargs kill -9

依赖缺失:npm install 失败(网络问题、registry 不可达)时,node server.js 报 Cannot find module 'express'。修复:

text

> !npm install express --registry=https://registry.npmmirror.com

服务器没起来就 curl:CC 在 node server.js & 后没等服务器就绪就 curl,会得到 Connection refused。修复:加 sleep 1 或轮询端口。CC 通常自己处理,但如果没有,你说"先等服务器打印出 running 再 curl"。

Node 版本过低:Express 4.x 需 Node 14+,但部分新特性要 Node 18+。用 !node -v 确认。

工作流总结

这个案例展示了 CC 的典型工作流:

理解需求:自然语言下达,给具体约束(端口、路由、返回格式、不要哪些依赖)。
选择工具:CC 自主调用 Bash(安装)、Write(创建文件)、Edit(修改文件)。
执行:CC 按顺序执行,每步输出反馈给它决定下一步。
验证:启动服务器 + curl 验证,用可观察的输出判定对错。

关键原则:给具体路径,给验证命令,给约束边界。需求越具体,CC 的动作越精准;验证命令越明确,CC 的闭环越快。没有验证命令的 Agent,只是在高速生成猜测——这条原则贯穿全书,是工程篇(第 06 章起)所有工作流设计的起点。

上一章:02. 安装与订阅下一章:04. CLAUDE.md 与上下文入门

下一章:CLAUDE.md 与上下文入门 | 返回目录

第 03 章 第一次对话 ​

3.1 结论先行:四件套 + 自然语言 ​

3.2 交互模式:进入 REPL ​

3.3 @ 文件引用 ​

基本用法 ​

为什么不走 Read 工具 ​

与 Read 的区别与选择 ​

失败边界 ​

3.4 ! bash 模式 ​

基本用法(示例) ​

适用场景 ​

与让 CC 执行命令的区别 ​

失败边界 ​

3.5 # 记忆 ​

基本用法 ​

什么该记 ​

什么不该记 ​

与 CLAUDE.md 的分工 ​

3.6 / 斜杠命令 ​

内置命令速览 ​

常用场景 ​

自定义命令 ​

3.7 快捷键与 Vim 模式 ​

核心快捷键 ​

Shift+Tab:权限模式切换 ​

Ctrl+B:后台化 ​

Ctrl+O:verbose ​

Vim 模式 ​

3.8 实战:从零跑通一个 Express 服务器 ​

Step 1:准备工作目录 ​

Step 2:初始化项目 ​

Step 3:添加路由 ​

Step 4:启动并验证 ​

失败边界 ​

工作流总结 ​

第 03 章第一次对话

3.1 结论先行:四件套 + 自然语言

3.2 交互模式:进入 REPL

3.3 `@` 文件引用

基本用法

为什么不走 Read 工具

与 Read 的区别与选择

失败边界

3.4 `!` bash 模式

基本用法(示例)

适用场景

与让 CC 执行命令的区别

失败边界

3.5 `#` 记忆

基本用法

什么该记

什么不该记

与 CLAUDE.md 的分工

3.6 `/` 斜杠命令

内置命令速览

常用场景

自定义命令

3.7 快捷键与 Vim 模式

核心快捷键

Shift+Tab:权限模式切换

Ctrl+B:后台化

Ctrl+O:verbose

Vim 模式

3.8 实战:从零跑通一个 Express 服务器

Step 1:准备工作目录

Step 2:初始化项目

Step 3:添加路由

Step 4:启动并验证

失败边界

工作流总结