Claude Code 命令行实战指南

Claude Code 是 Anthropic 官方的终端 AI 编程 agent。它的核心价值不是"在终端里聊天"，而是 agentic——能自己读写文件、执行 shell 命令、跑测试、改代码，把一个模糊需求一路推到可运行的结果。你负责判断方向和审查结果，它负责动手。

安装与首次启动

两种官方安装方式，选其一：

# 方式一：原生安装（官方推荐，自动管理二进制）
curl -fsSL https://claude.ai/install.sh | bash

# 方式二：npm 全局安装
npm install -g @anthropic-ai/claude-code

装完验证：

claude --version
claude /doctor

/doctor 会诊断安装路径、Node 版本、认证状态、MCP 配置等，有问题它会直接告诉你。

首次运行 claude 会引导你登录——用 Claude 订阅账号（Pro/Max）或 API key 都行。登录完成后，进入你的项目目录直接敲 claude 即可启动。

三种交互形态

1. 交互式 REPL

cd my-project
claude

这是最常用的形态。进去后你输入自然语言，它调工具干活；斜杠命令控制会话状态；Shift+Tab 循环切换权限模式。日常开发 90% 时间在这里。

2. 非交互 print 模式

# 简单查询
claude -p "解释 src/auth.ts 里的 token 刷新逻辑"

# 管道输入——把日志喂给它分析
cat error.log | claude -p "分析这个报错的根因，给出修复方向"

# 脚本化：JSON 输出便于解析
claude -p "列出这个仓库里所有未写测试的导出函数" \
  --output-format json \
  --permission-mode acceptEdits \
  --model sonnet

-p 模式的特点是：打印响应后立即退出，不进入 REPL。适合嵌进 CI、Makefile、git hook。配合 --output-format json 可以拿到结构化结果做后续处理。

3. 恢复会话

Claude Code 会自动保存会话历史。三种恢复方式：

claude -c                    # 加载当前目录最近一次会话，最常用
claude -r                    # 弹出选择器，挑一个历史会话
claude -r "feature-auth"     # 按名称恢复
claude -n "feature-auth"     # 给当前会话命名，方便以后 -r 恢复

实际用法：你上午在调一个 auth 模块的 bug，中午吃饭关了终端，下午回来 claude -c 直接接着干，上下文还在。如果你同时开多条线，给每个会话命名（-n），之后用 -r 按名恢复比翻选择器快。

斜杠命令：会话内的控制面板

在 REPL 里，以 / 开头的行会被识别为命令。输入 / 后接着打字母可以过滤列表。以下是最高频的命令：

五个关键命令的使用时机

/init——进项目第一件事。 它会扫描代码库结构、构建系统、测试命令，生成一份 CLAUDE.md。这份文件是 agent 理解你项目的"说明书"：构建怎么跑、测试怎么跑、代码风格约定是什么。设环境变量 CLAUDE_CODE_NEW_INIT=1 会走交互式多阶段流程，问得更细，生成的文件质量更高。

/compact——长会话续命。 会话越长，上下文窗口越满，响应变慢变贵。/compact 会压缩历史对话，保留关键信息、丢弃冗余。压缩后项目根的 CLAUDE.md 会重新注入，所以项目级指令不会丢。经验：感觉响应明显变慢时压一次。

/clear——换任务时用。 /compact 是压缩，/clear 是清空。当你从"修 bug"切换到"写新功能"时，旧上下文反而是噪音，直接 /clear 干净起步。

/rewind——agent 改崩了就回滚。 它会列出检查点（每次工具调用前自动创建），你可以选择只回滚对话、只回滚代码、或两者都回滚。agent 改了一堆文件把测试跑挂了？/rewind 回到改之前，换个思路重来。别名 /checkpoint、/undo。

/permissions——精细控制工具权限。 默认每次敏感操作都问你确认，久了会烦。你可以设规则：

# 允许 git log 免确认
allow: Bash(git log *)

# 永远禁止 rm -rf
deny: Bash(rm -rf *)

这些规则持久化在项目配置里，下次启动还在。

权限模式速查

Shift+Tab 在以下模式间循环切换：

日常开发建议在 default 和 acceptEdits 之间切：审查方案时用 default，确认方向后切 acceptEdits 让它放手改。plan 模式适合复杂任务的前期规划——先让它只读分析、出计划，你确认后再退出 plan 模式执行。

CLAUDE.md：让 agent 记住你的项目

每个会话开始都是全新的上下文窗口。跨会话携带知识靠两层记忆：CLAUDE.md（你写的指令）和 auto-memory（Claude 自己写的笔记）。

作用域层级

从宽到窄，后者拼接在前者之后，越靠近工作目录的越后读、优先级越高：

加载机制

从工作目录向上遍历目录树，把路径上所有 CLAUDE.md 和 CLAUDE.local.md 拼接进上下文（不是覆盖），从文件系统根向下排序。同级目录里 CLAUDE.local.md 排在 CLAUDE.md 之后。子目录的 CLAUDE.md 按需加载——只有 Claude 读到该目录下的文件时才触发。

@path 导入语法

在 CLAUDE.md 里用 @path/to/file 可在启动时把目标文件展开进上下文。相对路径相对包含导入的文件解析，最多递归 4 层。如果文本里恰好有 @README 这样的字样不想被导入，用反引号包裹：` @README `。

AGENTS.md 是其他工具的约定，Claude Code 不直接读，但你可以在 CLAUDE.md 里 @AGENTS.md 导入复用，避免维护两份。

写作三原则

1. 控制在 200 行内——上下文窗口是有限资源，长篇大论挤占有效注意力。
2. 具体可验证——写"用 2 空格缩进，不用 tab"，不写"格式化好代码"。
3. 避免矛盾指令——两条打架的规则会让 agent 随机选一条。

.claude/rules/ 按主题拆分

指令多了就拆到 .claude/rules/ 目录，每个文件聚焦一个主题。用 frontmatter 做 path-scoped 规则：

---
paths: ["src/api/**/*.ts"]
---
所有 API handler 必须用 zod 校验入参，错误响应统一返回 400。

只在 Claude 处理匹配文件时才加载，不占常驻上下文。

auto-memory

Claude 会自动记录构建命令、调试洞察、你的偏好，存于 ~/.claude/projects/<project>/memory/。启动时加载 MEMORY.md 的前 200 行 / 25KB。用 /memory 命令查看和管理。v2.1.59+ 支持。

实战示例

# 项目：支付网关

## 构建
- `pnpm install && pnpm build`
- 测试：`pnpm test --filter=core`

## 代码规范
- 2 空格缩进，不用 tab
- 函数名 camelCase，类型名 PascalCase
- 所有金额用整数分，不用浮点

## 架构约束
- 新增 API 必须在 `src/api/openapi.yaml` 登记
- 数据库迁移用 `pnpm db:migrate`，不手写 SQL

注意：CLAUDE.md 是上下文提示，不是强制配置。要硬性拦截某个操作，用 PreToolUse hook，别指望靠 CLAUDE.md 里的"禁止"两个字。/compact 后项目根的 CLAUDE.md 会重新注入，但子目录的不会自动重注入。

子代理：把脏活隔离在独立上下文

子代理在独立上下文窗口运行，有自定义系统提示、特定工具访问、独立权限。干完活返回摘要给主对话，不污染主上下文。

为什么用

• 保留上下文：探索代码、跑测试这种会产生大量中间输出的活，放子代理里干，主对话只收摘要。
• 强制约束：用白名单限制工具，比如只读不写。
• 成本路由：把脏活丢给 Haiku，主对话留给 Opus 做判断。
• 复用配置：定义一次，团队共享。

定义方式

Markdown 文件 + YAML frontmatter，body 是系统提示。放 .claude/agents/（项目级，入版本控制）或 ~/.claude/agents/（用户级）。用 /agents 命令管理，或直接手写文件。

完整示例：code-reviewer

---
name: code-reviewer
description: 审查 Git diff 中的代码变更，聚焦安全漏洞、逻辑错误和规范违反。在用户请求 code review 或提交前自动委派。
tools: ["Read", "Bash", "Grep"]
disallowedTools: ["Write", "Edit"]
model: haiku
maxTurns: 10
---

你是代码审查专家。收到 diff 后：

1. 逐文件检查安全漏洞（SQL 注入、未校验输入、硬编码密钥）
2. 检查逻辑错误（空指针、边界条件、竞态）
3. 对照项目 CLAUDE.md 里的规范检查违反项
4. 输出结构化报告：`[严重/警告/建议] 文件:行号 — 问题描述`

不要修改代码，只报告。如果 diff 为空，直接说"无变更"。

关键字段

• tools：白名单，只给子代理需要的工具。
• disallowedTools：黑名单，显式禁止某些工具。
• model：路由到 Haiku 省钱，或指定 Opus 做高质量判断。
• description：决定 Claude 何时委派，要写清楚触发场景。子代理只收到自己的系统提示 + 基本环境信息，不收完整 Claude Code 系统提示，所以 body 里该交代的背景要交代。

与 background agents 的区别

子代理是单会话内的并行单元，由 Task 工具（v2.1.63 起改名 Agent）调度。background agents（/background、/batch）是多会话并行，各自独立运行。别混淆。

MCP：接入外部工具与数据源

MCP（Model Context Protocol）让 Claude Code 调用外部工具——数据库查询、GitHub API、浏览器自动化、文件系统访问等。

加载与管理

# 启动时加载 MCP 配置
claude --mcp-config ./mcp.json

# 只用指定的 MCP 服务器，忽略其他来源
claude --mcp-config ./mcp.json --strict-mcp-config

会话内用 /mcp 命令查看状态、管理服务器。

mcp.json 示例

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"]
    }
  }
}

工具命名与拒绝

MCP 工具名形如 mcp__github、mcp__filesystem。要全局拒绝所有 MCP 工具：

claude --disallowedTools "mcp__*"

要拒绝特定服务器的工具，用 --disallowedTools "mcp__github"。

多模型与编排

模型切换

claude --model sonnet
claude --model opus
claude --model haiku

别名或完整名都行。Sonnet 是日常默认，Opus 留给复杂架构判断，Haiku 干批量脏活。

过载回退链

claude --model opus --fallback-model sonnet,haiku

Opus 过载时自动降级到 Sonnet，再不行降 Haiku，保证不中断。

子代理 model 路由

主对话用 Opus 做判断和规划，子代理用 Haiku 跑测试、读文件、生成模板代码。在子代理 frontmatter 里写 model: haiku 即可。这是最有效的省钱手段。

推理投入

/effort 命令调节推理深度。简单任务调低省 token，复杂调试调高让模型多想。

系统提示

• --append-system-prompt "..."：追加，保留默认工具和安全指引。大多数情况用这个。
• --system-prompt "..."：替换，覆盖默认。只在你要完全控制行为时用，会丢掉默认安全指引。

避坑实践

别在 bypassPermissions 下干生产活。

--dangerously-skip-permissions 适合本地实验或沙箱。生产环境用它等于把 rm -rf 的钥匙交给一个偶尔犯错的实习生。用 deny 规则或 plan 模式替代。

**长会话定期 /compact，换任务 /clear。**

上下文窗口满了之后性能下降明显。同一任务内用 /compact 压缩历史，切换到不相关任务时用 /clear 彻底清空。

**agent 改崩了用 /rewind，别手动回退。**

手动删改 agent 写的代码容易遗漏，/rewind 能回退到任意检查点，干净利落。

CLAUDE.md 写具体不写空话。

"写干净的代码"是废话，"函数不超过 50 行，嵌套不超过 3 层"是规则。空话浪费上下文还不被执行。

脏活路由到子代理 + Haiku。

跑测试、读日志、生成样板代码这些高 token 低判断密度的活，丢给 Haiku 子代理。主对话的 Opus 预算留给架构决策和调试推理。

敏感操作用 deny 规则硬拦，别指望 CLAUDE.md。

CLAUDE.md 里写"禁止删除数据库"是建议，deny 规则拦 Bash(rm:*) 是强制。安全靠机制不靠提示词。

-p 模式配 --output-format json 进 CI。

管道模式下输出 JSON，方便脚本解析退出码和结果。CI 里别用交互模式。

速查表