阶段 0 · 地基校准——理解引擎与交互基础

1. Agent Loop：三阶段迭代引擎#

官方文档把 agent loop 描述为三个相互融合的阶段：收集上下文 → 采取行动 → 验证结果，然后循环，直到任务完成。

1
你的提示
2
   ↓
3
[收集上下文] → 读文件、搜索代码、理解结构
4
   ↓
5
[采取行动]   → 编辑文件、运行命令、调用工具
6
   ↓
7
[验证结果]   → 跑测试、读输出、检查错误
8
   ↓
9
根据结果决定下一步 → 继续循环 or 完成

循环深度由任务复杂度决定。一个”解释这个函数”的问题可能只触发”收集上下文”就结束；修复一个有依赖链的 bug 可能循环十几次，每次都用上一步的工具返回值来决定下一步。

驱动循环的两个组件：

• 模型（Model）：负责推理，决定”下一步做什么”。当文档说”Claude 选择”或”Claude 决定”，指的是模型在推理。
• 工具（Tools）：负责行动，让模型的决策变成实际操作。每次工具调用返回结果，反馈进循环，告知下一个决策。

五类内置工具：

此外还有用于生成 subagent、询问用户、编排任务的工具。

你也是循环的一部分。 任何时刻都可以中断并重新引导。这是 Claude Code 区别于”一次性 AI 工具”的核心设计——它在设计上就预期你会在过程中介入。

2. 会话与上下文窗口#

会话持久化：每条消息、每次工具调用及其返回值都写入 ~/.claude/projects/ 下的 JSONL 文件。文件编辑前会对原始内容快照，方便回滚。

会话独立性：每个新会话从空白上下文窗口开始，没有前一个会话的对话历史。跨会话的持久化靠两个机制：

• CLAUDE.md：你手动维护的项目/全局规则
• 自动内存（Auto Memory）：Claude 自动保存的学习内容，每个会话开始时加载前 200 行或 25KB

上下文填满时的行为：Claude Code 先清除较旧的工具输出，再对对话做总结。关键代码片段和请求被保留，对话早期的详细说明可能丢失。持久规则放 CLAUDE.md，别依赖对话历史。用 /context 可视化当前上下文占用。

3. 交互模式 vs -p 一次性模式#

交互模式（claude 直接启动）：

• 完整的 REPL 环境，支持多轮对话
• 所有斜杠命令、快捷键、@/!/# 前缀均可用
• 会话自动保存，可用 --continue / --resume 恢复

-p 一次性模式（Print 模式）：

• 执行完毕即退出，适合脚本/CI/管道
• 通过 --output-format 控制输出格式：text（默认）、json、stream-json
• 支持 --max-turns 限制循环轮数，--max-budget-usd 限制花费上限
• 支持 --no-session-persistence 不写磁盘（适合无状态 CI）

典型场景对照：

1
# 交互模式：进入 REPL，适合探索性工作
2
claude
3

4
# 一次性模式：脚本化调用，获取纯文本结果
5
claude -p "总结 src/auth/ 下的认证流程"
6

7
# 管道输入：把标准输入喂给 Claude（PowerShell）
8
Get-Content .\logs\error.log | claude -p "分析这些错误，找出根因"
9

10
# 等价的 bash 写法（通过 Bash 工具或 WSL）
11
cat logs/error.log | claude -p "分析这些错误，找出根因"
12

13
# JSON 格式输出（适合脚本解析）
14
claude -p "列出 src/ 下所有 TODO 注释" --output-format json
15

16
# 继续上一个会话再以 -p 方式追加
17
claude -c -p "现在把刚才的修复也覆盖到测试文件"

--bare 模式：跳过 hooks、skills、plugins、MCP、自动内存和 CLAUDE.md 自动发现，启动更快，适合对性能敏感的脚本化调用：

1
claude --bare -p "用一句话描述这个函数的作用"

4. 斜杠命令全集#

在会话内输入 / 查看所有可用命令；输入 / 后接字母筛选。命令分三类来源：

• 内置命令：硬编码在 CLI 中
• Bundled Skills：以 Skill 形式捆绑，行为与自定义 skill 相同（标记为 [Skill]）
• MCP prompts：由连接的 MCP server 贡献，格式为 /mcp__<server>__<prompt>

高频内置命令速查（按场景分组）：

上下文管理

会话导航

模型与模式

代码审查

记忆与项目

工具与扩展

快问与侧边

诊断

自定义命令入口：自己写的 skill（markdown 文件放在 .claude/commands/ 或 ~/.claude/commands/）会出现在 / 菜单中，与内置命令并列。关于 skill 的创作见 03-customization-and-extensions.md。

5. @ 文件/目录提及#

在提示中输入 @ 触发文件路径自动补全，将文件内容注入上下文：

1
帮我重构 @src/auth/token.ts，参考 @src/auth/session.ts 的写法

可以提及目录，Claude 会遍历其中的文件：

1
@src/payments/ 这里的支付流程有没有遗漏错误处理？

@ 提及比”请读取文件 X”更精确——它明确告诉 Claude 哪些文件是上下文的一部分，减少 Claude 自行决定读哪些文件带来的不确定性。在大型项目中，主动 @ 关键文件比依赖 Claude 搜索更省 token、更可预期。

6. ! 前缀：直接执行 Shell#

在提示开头输入 ! 进入 Shell 模式，绕过 Claude 直接运行命令，命令及输出会被加入对话上下文：

1
! git status
2
! npm test
3
! Get-Content .\src\config.ts

Shell 模式的特性：

• 命令输出实时显示
• 执行结果进入对话上下文，Claude 后续可以引用
• 支持 Ctrl+B 将长时间运行的命令移到后台
• 支持基于历史的 Tab 补全（从当前项目的历史 ! 命令中补全）
• 用 Escape、Backspace 或空提示上 Ctrl+U 退出 Shell 模式
• 将以 ! 开头的文本粘贴到空提示时自动进入 Shell 模式

典型用法：在 Claude 分析代码前先用 ! 运行一遍测试，让失败输出直接进入上下文：

1
! npm test
2
现在帮我修复上面失败的测试

7. # 快速写入记忆#

在提示开头输入 # 将当前内容快速存入 CLAUDE.md（项目级或全局级，取决于你的配置）：

1
# 这个项目的 API 客户端统一在 src/api/client.ts，不要直接用 fetch

这是在对话中随手积累规范的最快路径。比直接 /memory 打开编辑器快，适合”刚发现一个惯例，顺手记下来”的场景。

注意：# 写入的是记忆文件，与对话历史分开。下一个会话开始时这条规则就会生效。

8. Esc 中断与双击 Esc 回溯#

单击 Esc：立即中断 Claude 正在进行的响应或工具调用。Claude 停止，等待你的下一条指令，已完成的工作保留。适合”跑偏了，我来重定向”的场景。

双击 Esc（Esc + Esc）：

• 如果提示框有内容：清除输入草稿，草稿保存到历史（按 Up 可找回）
• 如果提示框为空：打开回退菜单，可以从上一个检查点恢复代码和对话状态

这两个行为经常被混淆。记住：有内容时是”清草稿”，空提示时才是”回滚”。

9. /rewind：检查点回滚#

/rewind（别名 /checkpoint、/undo）把对话和代码回滚到上一个操作点。具体行为：

• 可以选择性地只回滚代码，或同时回滚对话
• 也可以从选定消息开始做总结（而非完全丢弃）
• 检查点是会话本地的，独立于 git
• 影响远程系统的操作（数据库、API、部署）无法检查点

/rewind 和双击 Esc 的区别：/rewind 更精细，可以指定回滚到哪个点；双击 Esc 是快速回到上一个状态的快捷手势。

10. 权限模式与 Shift+Tab#

Shift+Tab 循环切换四种权限模式：

启动时可用 --permission-mode 直接指定：

1
# 以 plan 模式启动，先规划再执行
2
claude --permission-mode plan
3

4
# 自动接受编辑，减少询问（适合已信任的任务）
5
claude --permission-mode acceptEdits

11. 常用键位速查#

通用控制

文本编辑

多行输入（Windows Terminal 开箱即用）

12. 管道与组合用法#

PowerShell 管道输入：

1
# 把文件内容通过管道送给 Claude 分析
2
Get-Content .\src\utils.ts | claude -p "找出这个文件里所有可能的边界情况"
3

4
# 读取日志文件的最后 100 行分析
5
Get-Content -Tail 100 .\logs\app.log | claude -p "这些错误的根因是什么？"
6

7
# 把 git diff 送给 Claude 做代码审查
8
git diff HEAD~1 | claude -p "审查这次提交，找出潜在问题"
9

10
# 把命令输出送给 Claude
11
npm test 2>&1 | claude -p "哪些测试失败了，原因是什么？"

与其他工具组合：

1
# 让 Claude 生成内容并写入文件
2
claude -p "为 src/auth/token.ts 写单元测试" | Out-File -Encoding utf8 .\src\auth\token.test.ts
3

4
# 结合 jq 处理 JSON 输出（需要安装 jq）
5
claude -p "列出 API 端点" --output-format json | jq '.[]'
6

7
# 脚本中检查返回码（-p 模式成功返回 0）
8
claude -p "检查 src/ 下有没有 console.log 遗留" --output-format text
9
if ($LASTEXITCODE -ne 0) { Write-Host "检查失败" }

stream-json 输出格式（适合实时处理）：

1
# 流式输出，每个 token 单独一行 JSON
2
claude -p "重构 src/db/query.ts" --output-format stream-json --verbose

后台运行长任务：

1
# 启动后台 agent，立即返回 session ID
2
claude --bg "对整个代码库跑全量测试并生成报告"
3

4
# 查看后台会话状态
5
claude agents
6

7
# 附加到后台会话
8
claude attach <session-id>

示例 1：完整的”分析→修复→验证”循环#

1
# 第一步：把测试失败输出直接带入上下文
2
claude

进入交互模式后：

1
! npm test 2>&1

等测试输出显示后：

1
帮我修复上面所有失败的测试。先不要修改代码，把你的修复计划说一下。

审核计划后：

1
好，按计划执行。

修完后验证：

1
! npm test

示例 2：用管道做快速日志分析#

1
# 取最后 200 行错误日志直接分析
2
Get-Content -Tail 200 .\logs\error.log | claude -p "分类汇总这些错误，按频率排序，给出最可能的根因"

示例 3：@ 文件提及精准定位上下文#

1
@src/payments/checkout.ts @src/payments/types.ts
2
这两个文件里，持有过期卡的用户走到哪一步会出错？

示例 4：结合 /btw 不打断主线任务#

1
帮我把 src/api/ 下所有的 fetch 调用改成用统一的 apiClient

（Claude 工作中，突然想查个事儿）

1
/btw apiClient 的超时时间现在是多少？

Claude 从已有上下文回答，不影响正在进行的重构任务。

示例 5：/rewind 撤销一次跑偏的修改#

Claude 改了一批文件但方向不对：

1
/rewind

在回退菜单里选择回滚到修改前的检查点，代码恢复，对话也回到该点。然后给出更明确的指令重新开始。