Claude Code 使用指南

概述

Claude Code 是 Anthropic 推出的智能体编程工具（agentic coding tool），在终端运行，能阅读整个代码库、编辑文件、运行命令、操作Git，支持终端 CLI、VS Code、JetBrains、桌面应用和浏览器五种使用方式。

AI编程工具三年演变：Copilot（补全）→ Cursor（对话）→ Claude Code（终端Agent）。变的不是技术先进程度，而是人和AI之间的关系——从输入法到结对伙伴，再到独立工程师团队。

💡 核心认知
Claude Code不是在帮你写代码，它在帮你构建产品。传统工具解决代码生产效率，Claude Code 解决产品构建效率：从想法到能跑的东西。

Boris Cherny（Claude Code创建者）用Opus 4.5之后47天中有46天在用，最长单次session跑了1天18小时50分钟。GA后6个月达到10亿美元年化收入。Netflix、Spotify、DoorDash、Notion、Vercel都在内部大规模使用，团队平均提效2-5倍。

快速上手

安装

1
2
3
4
5
6
7
8
9
10
11

# Windows PowerShell（推荐，自动后台更新）
irm https://claude.ai/install.ps1 | iex

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

# Homebrew
brew install --cask claude-code

# WinGet
winget install Anthropic.ClaudeCode

Windows用户需先装Git for Windows（winget install Git.Git）。国内网络需配代理：export HTTPS_PROXY=http://127.0.0.1:7890。

首次运行 claude 会提示登录 Anthropic 账号。付费三档：Pro（$20/月，个人开发者）、Max 5x（$100/月，重度用户）、Max 20x（$200/月，团队）。建议从Pro开始。

斜杠命令速查

在会话中键入 / 查看全部命令：

CLI 常用参数

-p 模式用于非交互式单次查询：claude -p "解释这段代码"、cat error.log | claude -p "分析这些错误"。

核心工作流

五步工作循环

描述需求 → 审查方案 → 确认执行 → 验证结果 → 迭代改进。不管项目大小，底层模式都是这五步。

第一个实用技巧：说「先别急着写代码，给我一个实现方案」让Claude先想清楚再动手。

Plan模式：先想清楚再动手

按 Shift+Tab ×2 进入Plan模式。Claude只规划不执行：读文件但不修改，给方案但不写代码，来回讨论直到方案确认。

Boris推荐流程：Plan模式讨论 → 用编辑器（Ctrl+G）写详细执行指令 → 切换执行模式开启Auto-accept一气呵成。

💡 判断标准
需要跟同事解释才能让他做的任务，值得用Plan模式。一句话能说清的，直接做。

Auto模式：AI替你审批

93%的权限请求被用户直接批准——审批疲劳让安全机制形同虚设。Auto模式用AI分类器两层防御：

• 输入层：Prompt Injection探测器扫描所有内容
• 输出层：Transcript分类器两阶段评估风险（误报率0.4%）

会拦截：范围升级（模糊”清理”指令删了远程分支）、凭证探索（自动搜索其他token）、绕过安全检查（--skip-verify）、数据外泄（自行创建公开GitHub Gist）。

⚠️ > 对于”过度主动行为”，分类器仍有17%漏检率。操作生产数据库、云基础设施建议手动确认。

权限管理三层

/permissions 支持通配符：Bash(npm run *)、Edit(/docs/**)。规则保存到 .claude/settings.json 提交Git。Boris的做法：不用Auto也不跳过权限，精心配置白名单check进git共享。

Shift+Tab 循环切换模式：默认 → acceptEdits → Plan → Auto → 默认。

Git操作

Claude理解版本控制状态。一句话commit和PR：「提交当前的改动，写一个有意义的commit message」「创建一个PR」。

Git Worktrees：claude --worktree 自动创建隔离工作目录，不影响当前分支。Boris同时运行5个Claude Code实例，每个在不同worktree中。配合Tmux：claude --worktree --tmux。

Computer Use：AI长了眼睛和手

Claude能看到屏幕截图并操控鼠标键盘。零配置，Pro/Max用户自动可用。最适合测试Web UI（像用户一样点击页面、填表单）、操作无API的桌面软件、自动化重复GUI操作。

⚠️ > 当前限制：慢、精细操作不靠谱、不适合需要快速反应的场景。定位为”耐心但手速慢的测试员”。

Voice Mode

/voice 进入语音模式，按住空格说话松开发送。支持20种语言含中文。最适合脑暴、描述空间概念。建议语音启动任务 + 键盘输入精确细节混用。

会话管理

⚠️ > Shrivu特别提醒：不要依赖 /compact，它不透明且容易出错。需要重启时用 /clear。

六个常见坑

1. 一个会话什么都塞 — 修bug加功能重构全在一个会话，上下文被塞满。做完就 /clear
2. 反复纠正越改越偏 — 纠正两次不行果断 /clear 重来
3. 看着像对的就接受了 — 每轮改动都实际运行验证
4. 过度微操 — Claude每写一个文件都要看，关注最终结果
5. 需求模糊 — 给具体可验证的需求：”首页加载4秒，瓶颈在Dashboard一次获取所有用户数据，改成分页加载每页20条”
6. 不写CLAUDE.md — 见下一节

CLAUDE.md：给AI一张地图

为什么它是最重要的文件

Claude Code每次启动新会话第一件事就是读CLAUDE.md。项目结构、代码风格、测试命令、常见陷阱都从这里了解。Shrivu Shankar（Abnormal AI的AI战略VP）称它为agent的”宪法”。

从护栏开始，别写手册

Boris团队管理Claude Code产品本身的CLAUDE.md只有约2500 tokens（~100行）。

💡 核心方法
从小开始，Claude每次犯错就加一条规则。不要试图预先写完整手册。

飞轮效应：Claude犯错 → 记录到CLAUDE.md → 下次不再犯 → 错误率持续降低

该写什么

判断标准：Claude能从代码里读出来的不要写，Claude猜不到的必须写。

该写：自定义构建脚本、非标准代码风格、测试命令、架构决策、环境变量坑、常见陷阱。

不该写：标准语言规范（Claude已知）、详细API文档（给链接）、频繁变化的信息、”写整洁代码”这类废话。

常见反模式

• 不要用 @ 引用大文档——会被完整嵌入吃上下文。正确做法是提到路径告诉Claude什么情况下去读
• 不要只写”永远不要做X”——提供替代方案：”不要用 --foo-bar，改用 --baz“
• 复杂命令先写bash包装器再记录包装器

层级结构

~/.claude/CLAUDE.md（全局级）→ ./CLAUDE.md（项目级，check进git）→ ./src/CLAUDE.md（子目录级）

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# MyApp

## 架构
- Next.js 15 + TypeScript + Tailwind CSS
- 数据库：PostgreSQL + Drizzle ORM
- 认证：Better Auth
- 状态管理：Zustand（不要用Redux）

## 开发命令
- 启动：pnpm dev
- 测试：pnpm test（Jest + React Testing Library）
- 类型检查：pnpm typecheck
- Lint：pnpm lint

## 代码风格
- 组件用函数式，不用class
- 样式用Tailwind，不要写CSS文件
- 数据获取用server component，不用useEffect
- 错误处理用error.tsx边界

## 常见陷阱
- Drizzle迁移后必须跑 pnpm db:generate
- 环境变量改了要重启dev server
- session检查在middleware，不要在页面组件里重复检查

## 不要做
- 不要安装新依赖除非我明确同意
- 不要修改 drizzle.config.ts
- 不要在client component中直接调数据库

不到300字，每一行都有价值。

⚠️ > 不要直接复制这个示例。好的CLAUDE.md是从你的项目中”长出来”的。空文件开始，犯一次错加一条，三个月后就是定制护栏。

Auto Memory

Claude自动记忆个人偏好，存储在 ~/.claude/projects/<项目>/memory/。与手写CLAUDE.md并行工作：手写适合团队共享和检入git，Auto Memory适合个人偏好自动维护。

迭代飞轮

第一周空文件，Claude犯很多错 → 第二周护栏初现，错误率下降 → 第一个月20-30条规则，质量明显提升 → 持续迭代。Mitchell Hashimoto（HashiCorp联合创始人）描述过一模一样的过程。

进阶对话技巧

三条原则

具体化：不说”做个登录功能”，说”在src/auth/目录下新增Google OAuth登录，用Better Auth库，参考现有的GitHub登录实现方式”。

指向已有模式：”看src/components/UserWidget.tsx的实现方式，照着做一个CalendarWidget”。范本比十行描述有效。

描述症状，不要猜原因：不说”token刷新逻辑有问题”，说”用户在session超时后登录失败，请检查src/auth/下的token刷新流程”。

Context Engineering

信息不是越多越好。Anthropic工程团队发现上下文太多模型表现反而变差。Shrivu的monorepo实测：新会话光加载基础配置就吃掉约20k tokens，剩下180k才是干活空间。

主动管理上下文：@ 引用文件、粘贴截图、Pipe数据（cat error.log | claude）、给URL。

让Claude采访你

大功能开发前先说：「我想做一个支付功能，在动手之前，先采访我，问清楚所有你需要知道的事情。」Claude会像产品经理一样问问题，至少一半是你没考虑过的。

采访结束后让Claude整理成Spec，然后关键一步——开全新会话把Spec喂给新Claude执行。采访积累的对话历史长，新会话从干净Spec开始更专注。

多轮对话策略

• 紧密反馈循环：Claude写了10行说”不对”成本几乎为零，写完整个功能再推倒重来浪费tokens
• 两次纠正不行就换条路：/clear 清掉上下文，更好的初始prompt重来
• 换任务就清上下文：不同任务有不同上下文需求
• 用subagent做调研：调研结果返回主会话，中间思考过程不污染主上下文

Effort级别

💡 > High是默认值，Boris从不调低。想得更深，返工更少，总体效率更高。

扩展能力：Skills、Hooks与MCP

三种机制互补：Skills教Claude怎么做事，Hooks在关键节点强制检查，MCP连接外部世界。

Skills

在 .claude/skills/<名称>/SKILL.md 创建，Claude自动按上下文加载。/skill-name 手动调用。

两种类型：知识型告诉Claude怎么做（API规范、编码风格），工作流型告诉Claude按什么步骤执行（/fix-issue、/review-pr）。

💡 > 一件事每天做超过一次就该变成skill。

工作流型skill加 disable-model-invocation: true 防止自动触发。Boris的高频skills可一行安装：curl -L -o ~/.claude/skills/boris/SKILL.md https://howborisusesclaudecode.com/api/install

Hooks

Skills是建议，Hooks是强制。在生命周期节点触发Shell脚本，Claude无法跳过。

不需要从零写hooks，直接告诉Claude：「Write a hook that runs eslint after every file edit」。

MCP

MCP（Model Context Protocol）相当于Claude Code的USB接口。配置在 .mcp.json，可check进git。claude mcp add 添加，claude mcp list 查看。

推荐MCP：Slack（自动同步进度/回复问题）、数据库（直接查询）、Figma（设计转代码）、Sentry（自动定位线上bug）、GitHub（自动化项目管理）。

Boris经典用法：Slack MCP接收bug报告 → Skill标准流程修复 → Hook自动跑测试 → Slack MCP通知修复结果。

敏感token用环境变量引用，不要硬编码。

Slash Commands

Commands在 .claude/commands/ 目录，可含内联Bash预计算。Skills是”知识和能力”，Commands是”宏”——需要Claude”知道什么”用skill，需要Claude”做一串事”用command。

多Agent协作

并行session

Boris日常：本地5个Claude Code实例（独立git checkout）+ 5-10个云端网页会话。只开一个session大部分时间在等，开5个等待时间降到零。关键：每个session在自己的worktree中运行。

Subagents

.claude/agents/ 下定义专家agent，独立上下文不消耗主session。推荐组合：security-reviewer + verify-app，覆盖”写得对不对”和”跑得起来吗”。

Agent Teams

Writer/Reviewer模式：Writer写代码 → Reviewer审代码 → Writer修改。两个agent互相盯着，产出质量明显提升。

Coordinator Mode四阶段：Research（多个worker并行调查代码库）→ Synthesis（coordinator综合生成规格说明）→ Implementation（worker按规格修改）→ Verification（验证结果）。

Fan-out批处理

claude -p + shell循环并行执行，/batch 命令自动规划+并行执行+汇总结果。适合大规模重构、代码迁移。

异步工作

• Remote Control：手机远程管理本地session
• claude.ai/code：浏览器运行
• /schedule：云端定时任务，电脑关机照样跑
• /loop：本地无人值守最多3天

实用经验

1. 从2个session开始，一个主任务一个辅助
2. 每个session给明确角色：前端/后端/测试
3. 用git分支隔离一切，通过PR合并
4. 每隔15-20分钟扫一眼各session进度

💡 > 把并行工作想象成管理一个远程团队。你的工作从写代码变成了做项目管理。

完整产品实战

从采访开始，别从代码开始

大功能的第一步不是写代码，是让Claude采访你。采访完生成SPEC.md，然后开新session执行——采访过程积累的长对话历史会污染执行上下文。

开发节奏

Phase 1：项目初始化 + CLAUDE.md配置。Phase 2：Plan模式聊架构 → 逐步实现，每做一个模块验证一次。不要等Claude写完所有代码再测，连续写5个文件后发现第2个就写错了。Phase 3：截图反馈 + UI迭代。Phase 4：Skills + MCP + Hooks。Phase 5：一句话部署Vercel + CI/CD。

五条核心经验

1. 需求拆小，每次只给一步。先做登录→确认能跑→再加数据存储→再核心逻辑→最后UI
2. 先跑通最小功能再一步步加。小猫补光灯第一个版本只有一个功能：屏幕变白亮度拉满
3. 验证比开发更重要。Claude一小时能写2000行，不验证的问题后面以更大成本爆发
4. 不要在一个session里做太多不相关的事。分session：初始化→后端→前端→测试→部署
5. 产品感知才是最大的杠杆。AI能让执行速度提升10倍，但方向错了只是10倍速度走向错误

开发常见陷阱

心智模型

三层模型

Prompt层 → Context层 → Harness层

💡 最重要的一句话
把时间花在构建Context和Harness上，而不是优化Prompt。

Claude Code内部机制

TAOR循环：Think → Act → Observe → Repeat。Claude不是从输入到输出的直线程序，而是不断试探和调整的循环体。这解释了为什么它有时”绕弯路”——给明确的验证标准能加速收敛。

技术栈：Bun运行时 + React Ink渲染终端UI + 严格模式TypeScript + Zod v4验证。40+工具归结为4个原语：Read、Write、Execute、Connect。Bash是万能适配器。

上下文压缩：有损操作。每压缩一次损失一些细节，几次后最早上下文只剩模糊影子。重要约束写进CLAUDE.md——对话会被压缩但CLAUDE.md每次重新读取。

权限系统：三层模式 + ML驱动风险分级 + 受保护文件列表 + 路径穿越攻击防御。每次权限弹窗的解释是LLM实时生成的。

身份转变

从”怎么写”到”写什么”。Claude Code解决了”怎么写”，”写什么”需要你自己判断。

演进方向

平均每2个月一个大功能。2024.11 MCP → 2025.02 Beta → 2025.05 GA → 2025.07 SubAgents → 2025.09 Hooks → 2025.10 Skills → 2026.02 Agent Teams → 2026.03 Computer Use + Voice Mode。

三条不变线索：自主性持续增强、上下文窗口持续扩大、协作模式持续丰富。每月花30分钟浏览changelog即可，真正该关注的是方向而非具体功能。

附录：51万行代码的启示

2026年3月31日，Claude Code v2.1.88因 .npmignore 漏排 .map 文件导致约1900个TypeScript文件共51万行代码泄露。

技术栈发现：Bun运行时（不是Node.js）+ React Ink终端UI + 严格模式TypeScript + Zod v4。工具系统29,000行，查询引擎46,000行。

权限系统内部：三层模式 + ML驱动风险分级 + 受保护文件列表（/etc/passwd、/.ssh、/.aws/credentials）+ unicode/大小写/反斜杠注入防御。每次权限弹窗解释是LLM实时生成的。

Feature Flags中的未来：KAIROS（后台助手，监听webhook主动介入）、ULTRAPLAN（云端深度规划，最长30分钟思考）、Coordinator Mode（四阶段多Agent编排）、BUDDY（AI宠物系统，18物种）。

引发争议的设计：Undercover Mode（Anthropic员工自动隐藏AI参与痕迹）、Anti-Distillation（注入伪造工具定义防数据蒸馏）、情绪检测（正则检测用户负面情绪调整语气）。