Claude Code 使用手册

§1快速开始

Claude Code 是 Anthropic 出品的命令行 AI 编程助手。在终端里直接跟它对话,它能读你项目、改你文件、跑你命令、调你 API,像坐在你旁边的资深工程师。

1.1 安装与启动

官方安装(推荐)

curl -fsSL https://claude.ai/install.sh | bash

⚠️ 不要用 npm i -g @anthropic-ai/claude-code、brew install、pip install —— 走错路径,后续升级会有兼容问题。

国内访问:用 Cloudflare Worker 镜像(参见 cloudflare-mirror/):

curl -fsSL https://claude.ai/install.sh | \
  sed 's|https://downloads.claude.ai/claude-code-releases|https://claude-version.717800.workers.dev|g' | \
  bash

启动

cd your-project
claude                            # 进项目启动,自动读 CLAUDE.md(如果有)

第一次会要你登录 Anthropic 账号(浏览器跳一次,后续免登录)。

1.2 第一次对话

启动后直接打字:

> 这个项目是干啥的?给我讲讲架构

Claude 会自己 ls、Read 关键文件、然后给你总结。不用你贴代码、贴文件路径。

让它做事的 prompt 例子:

> 帮我加个 /api/health 端点,返回 {"status":"ok","time":<now>}
> 跑一下 npm test,看哪几个挂了
> 解释下 go-backend/main.go 的中间件链

§2核心机制

一次对话的内部循环:

你的 prompt
   ↓
[模型思考] ← thinking_mode 决定想多深
   ↓
[选择工具] 决定调 Read / Bash / Edit / ...
   ↓
[执行工具] 跑出结果
   ↓
[再思考] 看结果,决定下一步
   ↓
[产出回复] 文字 + 工具调用结果

你可以随时打断(Esc)、追加指令、纠正方向。Claude 会保留上下文。

2.1 工具集

工具失败/结果不对,Claude 自己会重试,不用你手动干预。

2.2 思考深度

Claude 回你前会先在内部想一通(看不到的 thinking 块)。思考深度的 3 个档:

想让 Claude 这次特别认真,直接说 "ultrathink"、"think step by step"、"仔细想想"。CLI 命令 /effort 可设全局档位。

2.3 上下文窗口

每次对话有一个 token 限制(目前 ~200K)。对话越长,旧内容会被压缩或截断。几条经验:

• 长任务用 /tasks 建 todo,确保不丢关键步骤
• 频繁切换主题用 /clear 重开会话
• 重要结论(架构决定、踩过的坑)存到 CLAUDE.md 或 memory,不被压掉

2.4 Memory 系统

Claude 有跨会话的"自动记忆",存在本地文件:

~/.claude/projects/<hash>/memory/
├── MEMORY.md           # 索引,每次启动自动加载
├── user-role.md        # 用户身份
├── feedback-xxx.md     # 你的偏好/反馈
└── project-xxx.md      # 项目状态

MEMORY.md 是索引,每次 session 开始自动进上下文,所以下个 session 不用重复交代你是谁、你的偏好。

手动管理:/memory 命令。

自动存什么:用户身份、反复出现的反馈、项目背景、外部参考链接。

不存:代码细节(代码本身是真相)、git 历史(已记录)、纯一次性的对话内容。

§3Slash Commands 速查

输入 / 触发的命令。每个都有专门用途,熟练能省一半时间。

3.1 /init · /debug · /verify · /run

/init 输出的 CLAUDE.md 是关键文件,Claude 每次启动都读,所以要把项目结构、关键命令、踩过的坑都写进去。

3.2 /code-review · /simplify · /security-review

这些 review 命令都是 solo(单 agent 自己看),如果想多 reviewer 对抗,用 ultracode 模式(见 §4)。

3.3 /memory · /skills · /mcp · /plugin

/skills 列出来的都是"内嵌能力",比如 deep-research / update-config / keybindings-help / verify 等。Claude 在合适场景会自己调,你可以显式 /skill-name args 触发。

3.4 /deep-research · /loop

/deep-research 适合"我需要一个**带引用 + 互相验证过**的答案",不适合"这个命令是干啥的"这种一句话能答的问题。问题太模糊时它会先问你 2-3 个澄清问题。

3.5 /effort · /tasks · /clear

/effort max + 在 prompt 里写"ultrathink"是双重保险,后者只影响这一次回答。

§4高级用法:多 Agent 编排

单个 Claude 处理不了的复杂任务,Claude Code 可以开多个 Claude 实例(Agent)同时干。

4.1 Workflow 工具

一个 Claude("主")可以调度多个 Claude("子 agent")并发跑不同子任务,最后合成结果。常见模式:

4.2 Ultracode & Ultrathink

两个独立的"高消耗开关",常一起用:

什么时候开

• 开 ultracode:架构选型、深度调研、大规模重构、安全审计、code review 想要多 reviewer 对抗
• 不开 ultracode:聊代码、问问题、改单文件、debug 单点 bug

4.3 Plan 模式(EnterPlanMode)

对于非平凡的改动(动多个文件、改架构、加依赖),先让 Claude 提方案、你批准,再动手:

> EnterPlanMode
> 我想给 mobile-app 加个 in-app 反馈入口,改成新结构

Claude 会输出一份方案(改哪些文件、新增什么、风险点),你确认后才会改代码。适合:跨文件改动、不确定怎么做、想看几个方案对比。

§5提示词技巧:写好 Prompt

同样一个问题,prompt 写得好 vs 写得差,质量能差 10 倍。

5.1 写好 Prompt 的 7 条铁律

1. 给上下文:别只说"修这个 bug",说"用户在升级 app 时点了 立即升级 按钮没反应,我看 logcat 没报错"。
2. 给具体例子:与其说"输出要美观",不如贴"我希望是这个样子的:🎉 v1.1.12 更新 · 🛠 ..."。
3. 指明文件/路径:别描述"那个登录的组件",说"src/components/AuthForm.tsx 第 42 行"。
4. 给约束:"不要改 schema.sql"、"不要动 mobile-app/src/lib/auth.ts"、"只用 Go 标准库"。
5. 说"不要":容易忽略的事直接列黑名单(不要 cat SSH 私钥、不要 commit 密钥)。
6. 让 Claude 思考:"think step by step"、"ultrathink"、"先别动手,告诉我你的方案"。
7. 明确成功标准:"改完跑 npm test 全绿"、"curl 返 200 且 Content-Type 是 application/json"。

5.2 给具体例子

例子 > 描述。"我要美观"是描述,贴个截图或代码示例是例子。

反例:

> release notes 写得美观专业些

正例:

release notes 我要这种风格:

  🎉 v1.1.12 更新  ·  🛠 升级时安装器无法弹出  ·  🛠 部分机型无法自动安装  ·  ⚡ 失败自动尝试备用方案

特点:
- 单行,用 `  ·  `(两侧反引号)分隔
- emoji 分类
- 不超过 5 个要点
- 不放技术术语(FLAG_ACTIVITY_NEW_TASK 这种内部名字不出现)
- 第一项带版本号

全文案规范见 mobile-app/RELEASE_NOTES_TEMPLATE.md,照着改 systemd env 里的 APP_RELEASE_NOTES。

正例一次到位,反例来回往返 5 次。

5.3 让 Claude 思考

几个常用句式(按强度递增):

复杂决策前永远用"先列方案,再动手"。Claude 默认倾向"先给个能跑的答案",你要它认真想就得明说。

§6实战模式:你的工作流速查

结合你的实际项目(维修工单系统 / Go + Expo / Cloudflare 全栈),给几个常用模式的 prompt 模板。

6.1 修一个 Bug

/debug

# 上面的命令会打开 debug 日志,先复现问题

我刚升级 mobile-app 到 v1.1.11,用户反馈:
"点立即升级按钮没反应,没下载也没弹安装器"

adb logcat -c && adb logcat | grep UpdateBanner

请你:
1. 先 Read mobile-app/src/components/UpdateBanner.tsx 看 handleUpdate 逻辑
2. 找出可能的根因(列 3 个)
3. 修最可能的那个,改完跑 npx tsc --noEmit 确认类型
4. 给我一个 RELEASE_X.Y.Z_RUNBOOK.md 的草稿,告诉我怎么发版验证

6.2 加一个功能

我想给 mobile-app 工单列表加个"按 SN 搜索"的功能。

要求:
- 工单列表页加搜索框,跨字段匹配
- 后端 GET /api/tickets?keyword= 已经有了,直接调
- 搜索框 debounce 300ms
- 空结果显示 "未找到匹配的工单"

先 EnterPlanMode 给我方案,不要直接改代码。

6.3 部署发布

我要把 v1.1.12 部署到生产。

服务器: 124.220.58.252,SSH keys/shanghai.pem
步骤按 mobile-app/RELEASE_1.1.12_RUNBOOK.md 走:
1. npx tsc --noEmit
2. npx eas build --profile production --platform android
3. 下载到 releases/维修工单-v1.1.12.apk
4. scp 到 /opt/maintenance-app/app-updates/
5. 改 systemd env(用 /etc/systemd/system/maintenance.service.d/v1.1.12.conf 走 drop-in)
6. daemon-reload + restart
7. curl 验证 /api/app-update

跑完每步给我状态。改 systemd env 是生产变更,等我确认再动。

6.4 深度调研

/deep-research 2026 年 Expo + EAS Build 的发展现状

我想知道:
- SDK 56 还会维护多久,值得现在锁定吗
- EAS Build 跟 EAS Update 跟 local build 的取舍
- 国内访问 EAS 的速度,有没有自建 runner 的可能

报告要带引用,关键判断标置信度。

§7故障排查

7.1 Claude 卡住/不响应

• Esc 打断当前生成
• Ctrl+C 强退 CLI
• 网络问题看 ~/.claude/debug/ 里最新的 *.txt

7.2 工具权限被拒

第一次跑某条命令,Bash 会问 "Allow this command?"。回答:

• Yes:本次允许
• No:本次拒绝
• Always:这类命令以后都允许(写进 settings.json)

想撤回所有授权:/permissions 清空 allowlist。

7.3 上下文爆了

对话变长会触发自动压缩,但有时关键信息被压掉。预防:

• 关键结论实时存 CLAUDE.md / memory
• 主题切换 /clear
• 大文件让 Claude 用 Grep 找关键段,不要全读

7.4 Claude 给的答案明显错

• 直接怼回去:"这个不对,正确应该是 X"
• 让它给引用:给我看看 docs 里原文
• 用 /deep-research 走对抗验证

7.5 误改生产环境

§8速查卡

8.1 全部 Slash Command

8.2 工具权限速记

8.3 跟你的项目搭配的常见命令

# Go 后端
cd go-backend && go run .                    # 本地起
go test ./...                                # 跑测试
go build -o server .                         # 出二进制

# Web 前端
cd web && pnpm dev                           # dev
pnpm build && pnpm start                     # prod 模拟

# Mobile
cd mobile-app && npm run start               # Expo dev
npx eas build --profile production           # 出 APK
npx tsc --noEmit                             # 类型检查(发布前必跑)

# Cloudflare Worker
npx wrangler deploy                          # 部署
npx wrangler tail                            # 看日志
npx wrangler dev                             # 本地调试

# 服务器
ssh -i keys/shanghai.pem ubuntu@124.220.58.252
sudo systemctl restart maintenance
sudo journalctl -u maintenance -f
curl http://124.220.58.252/api/app-update | jq .

8.4 配置 Claude Code 行为

三处配置文件(从全局到本地):

~/.claude/settings.json                        # 全局
<project>/.claude/settings.json                # 项目级
<project>/.claude/settings.local.json          # 本地(不 commit)

常用项:permissions.allow(允许的命令白名单)、env(环境变量)、hooks(生命周期钩子)。

{
  "permissions": {
    "allow": [
      "Bash(npx tsc*)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff*)"
    ]
  }
}