从工具生态到实战配置：Claude Code 深度使用指南

AI 编程工具生态、模型接入与 Claude Code 安装

1. 工具生态的四类交互方式

第二部分首先建立工具全景图。AI 编程工具不是同一种产品的不同名字，而是按交互模式分成不同类型。

类型	代表工具	使用特点
Agent 工具	Claude Code、Codex	能读写文件、运行命令、自主推进任务
IDE 集成型	Cursor、Windsurf、Copilot、Cline	嵌入编辑器，适合日常编码和补全
平台型 Agent	Qoder、Devin、Bolt.new	偏多 Agent 和项目级管理
对话式工具	ChatGPT、Claude.ai	适合学习、解释、方案讨论和代码片段生成

文档重点放在 Claude Code，因为它处在"任务执行型 Agent"层级：既不是只能补全代码，也不是纯聊天，而是可以直接操作真实项目。

---

2. AI 编程工具能力层级

工具能力可以从 L1 到 L5 理解：

L1 代码补全：补一行、补一个函数
L2 代码生成：根据描述生成代码块
L3 任务执行：能改文件、跑命令、修 Bug
L4 项目管理：多 Agent 协作、任务拆解
L5 自主工程：端到端自主完成项目

Claude Code、Cursor Agent、Codex 主要处于 L3，是目前日常开发最实用的层级。L4 和 L5 更强，但也更依赖流程规范、权限管理和结果审查。

---

3. 评估工具的八个维度

选择 AI 编程工具时，不要只看"模型是不是强"。文档建议从八个维度评估：

• 上下文能力：能理解多大代码库。
• 工具使用：能否操作文件和终端。
• 自主性：能否自己规划和执行。
• 准确性：生成代码是否正确。
• 速度：响应和执行是否顺畅。
• 成本：订阅费和 API 消耗。
• 扩展性：是否支持 Skill、插件、MCP。
• 中文支持：中文需求和中文文档处理是否稳定。

对初学者来说，最关键的是"能不能安全、可控地完成真实项目任务"。所以工具能力越强，越需要 Git、权限模式、规范文件和审查流程配合。

---

4. Claude Code 的本质：不是聊天框，而是 Agent

Claude Code 的重要能力包括：

• 读取项目代码。
• 修改文件。
• 运行命令。
• 安装依赖。
• 搜索代码。
• 理解项目结构。
• 根据结果继续修正。

它与 Claude.ai 的区别在于：Claude.ai 主要给文字答案，Claude Code 可以在授权后直接操作本地项目。也就是说，Claude Code 给了模型"手"。

文档强调 Claude Code 的核心机制是 LLM Loop：

你给目标 → AI 思考 → 调用工具执行 → 观察结果 → 再思考 → 继续执行 → 交付结果

这就是为什么同样使用大模型，Claude Code 比普通聊天工具更像"实习生程序员"：它不仅回答问题，还能围绕目标循环推进。

---

5. Agentic Search：Claude Code 如何理解代码库

Claude Code 不依赖预先把整个项目上传做向量索引，而是像人类工程师接手项目一样工作：

看目录 → 读关键文件 → grep 搜索 → 跟踪引用关系 → 理解局部代码 → 执行任务

这种方式适合活跃开发中的项目，因为它读取的是当前真实文件，不容易受过期索引影响。不过要注意：被 Claude Code 读取进上下文的代码片段仍会发送给模型服务，因此敏感代码依然要注意隐私和合规。

---

6. Harness：模型之外的工程脚手架

文档强调，Claude Code 表现不只取决于模型，还取决于围绕模型搭建的 Harness，也就是上下文、规则、工具权限和扩展体系。

七层扩展点可以这样理解：

层级	组件	作用
1	CLAUDE.md	项目说明书，自动加载上下文
2	Hooks	会话或文件事件触发自动操作
3	Skills	可复用任务方法论
4	Plugins	打包 Skills、Hooks、MCP 配置
5	LSP	提供跳转定义、查引用等 IDE 能力
6	MCP Servers	连接数据库、GitHub、文档系统等外部工具
7	Subagents	独立上下文的子代理，适合调研和专项任务

学习顺序应该是先掌握 CLAUDE.md、权限、Skills，再逐步接触 MCP、Subagents 等进阶能力。不要一上来就堆扩展，否则容易把问题复杂化。

---

7. Codex、Cursor 与其他工具的定位

Codex 是 OpenAI 的编程 Agent，常见形态包括 Desktop、CLI 和 VSCode 插件。CLI 开源，支持沙箱与审批机制，使用 AGENTS.md 记录项目规则，也可以接入 OpenAI 兼容模型。它与 Claude Code 的核心差异在于生态、配置方式、模型体系和安全模型不同。

Cursor 是 IDE 集成型工具，适合在编辑器中边看代码边让 AI 改代码，适合日常编码和前端交互式开发。它更像"坐在旁边的编程搭档"，而 Claude Code 更像"在终端里执行任务的远程程序员"。

选型思路：

• 想要终端 Agent 和强自主执行：Claude Code。
• 想要 OpenAI 账号生态和开源 CLI：Codex。
• 想要编辑器内实时改代码：Cursor / Windsurf。
• 想要多 Agent 平台化协作：Qoder / Devin 类工具。
• 想学习、解释、写 Prompt：ChatGPT / Claude.ai。

---

8. Claude Code 安装与验证

文档推荐基于第零部分安装好的 Node.js，使用 npm 安装 Claude Code：

npm install -g @anthropic-ai/claude-code

也可以使用官方原生安装器：

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

验证安装：

claude --version

如果输出类似 claude-code v1.x.x，说明安装成功。

国内网络不稳定时，可先配置 npm 镜像：

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

---

9. API 配置与多模型接入

Claude Code 需要 API Key 或登录方式才能使用。文档整理了常见环境变量：

环境变量	作用
ANTHROPIC_API_KEY	Anthropic 官方 API Key
ANTHROPIC_AUTH_TOKEN	第三方平台或兼容服务的 Key
ANTHROPIC_BASE_URL	覆盖默认 API 地址
ANTHROPIC_MODEL	指定默认模型
ANTHROPIC_DEFAULT_OPUS_MODEL	自定义 Opus 槽位模型
ANTHROPIC_DEFAULT_SONNET_MODEL	自定义 Sonnet 槽位模型
ANTHROPIC_DEFAULT_HAIKU_MODEL	自定义 Haiku 槽位模型
API_TIMEOUT_MS	设置请求超时时间

配置方式有三类：

1. 临时环境变量：当前终端有效，适合测试。
2. 永久环境变量：所有终端生效，适合个人固定使用。
3. settings.json：可分全局、项目级、个人本地配置，适合多项目管理。

配置优先级：

启动参数 > 环境变量 > settings.local.json > settings.json > 全局 settings.json

---

10. DeepSeek 与 cc-switch 的意义

文档专门提到 DeepSeek，因为它可以通过 Anthropic 兼容端点接入 Claude Code，适合国内用户和预算敏感场景。基本思路是设置兼容端点、认证 token 和模型名，让 Claude Code 的 Agent 框架使用 DeepSeek 模型驱动。

cc-switch 的作用是可视化管理多模型配置。对于经常在 Claude、DeepSeek、GLM、千问之间切换的用户，它能降低手动改环境变量和配置文件的成本。初学者可以先掌握手动环境变量，熟悉后再用可视化切换工具。

---

11. 本笔记复盘问题

1. Claude Code 和 Claude.ai 最大区别是什么？
2. 为什么说 Claude Code 是 Agent 而不是聊天机器人？
3. Agentic Search 与传统预索引检索有什么区别？
4. 为什么 Harness 会影响模型表现？
5. 什么时候选 Claude Code，什么时候选 Cursor 或 Codex？

---

Claude Code 深度使用、配置与工作流

1. 模型选择：不要所有任务都用最贵模型

Claude Code 支持多种模型和模型别名。文档中推荐：

模型	特点	适合任务
Haiku	快、便宜	简单修改、格式化、小任务
Sonnet	质量与速度平衡	日常功能开发，默认推荐
Opus	推理强、成本高	架构设计、疑难 Bug、复杂算法

切换模型有四种方式：

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

会话中也可以使用：

/model
/model sonnet
/model opus

也可以通过环境变量或配置文件设置：

export ANTHROPIC_MODEL="sonnet"

{
  "model": "sonnet"
}

优先级是：

--model 启动参数 > ANTHROPIC_MODEL 环境变量 > settings.json

实战原则：简单任务用低成本模型，日常开发用 Sonnet，复杂规划和疑难问题再切 Opus。否则不是质量更高，而是浪费钱。

---

2. 三层配置：settings.json、CLAUDE.md、记忆系统

Claude Code 的配置不是一个文件解决全部问题，而是多层叠加。

全局配置：~/.claude/settings.json
项目配置：项目/.claude/settings.json
项目上下文：项目/CLAUDE.md

settings.json 主要管权限、默认模型、上下文压缩阈值。例如：

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm *)",
      "Bash(git *)",
      "Bash(node *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "model": "sonnet",
  "autoCompactThreshold": 80
}

初学者不要一开始就放太宽权限，默认逐步确认更安全。

---

3. CLAUDE.md：项目说明书

CLAUDE.md 是 Claude Code 最重要的上下文文件，相当于写给 AI 的项目入职手册。它应该包含：

• 项目概述。
• 技术栈。
• 目录结构。
• 编码规范。
• 当前开发状态。
• 禁止修改的区域。
• 常用命令和测试方式。

一个好的 CLAUDE.md 不需要长篇大论，而要具体、准确、可维护。例如：

## 编码规范
- React 组件使用函数式组件和 Hooks
- API 统一返回 { success: boolean, data?: any, error?: string }
- 数据库操作统一通过 Prisma Client
- 不要修改 prisma/migrations/ 目录

CLAUDE.md 有三个层级：

层级	位置	适合内容
全局级	~/.claude/CLAUDE.md	个人偏好、沟通风格
项目级	项目根目录/CLAUDE.md	项目技术栈、规范、禁区
文件夹级	子目录/CLAUDE.md	模块专属规则

优先级是文件夹级 > 项目级 > 全局级。

---

4. Auto Memory 与自建参考文档

CLAUDE.md 是主动写给 AI 的明规则，Auto Memory 是 Claude Code 在使用中记录的隐规则。它可以记录用户偏好、反馈、项目决策和参考资源索引。通过 /memory 可管理记忆。

但不要把所有内容都塞进 CLAUDE.md。对于较长、较专业的资料，文档建议使用"渐进式披露"：

## 外部参考文档
- 修改视觉样式前，阅读 docs/brand-visual.md
- 写产品文案前，阅读 docs/copywriting-style.md
- 写 API 前，阅读 docs/api-conventions.md

这样 AI 只在需要时读取对应文档，既省上下文，又能保持任务准确。

还应使用 .claudeignore 排除无关或敏感内容：

node_modules/
.next/
dist/
*.log
.env

---

5. 高频命令与交互技巧

启动方式：

claude
claude --project-dir /path/to/your/project
claude --model sonnet
claude -p "请列出当前目录下所有 JavaScript 文件"

高频斜杠命令：

命令	用途
/help	查看帮助
/model	查看或切换模型
/context	查看上下文占用
/compact	压缩当前对话
/clear	清空当前会话
/memory	管理记忆
/status	查看状态
/cost	查看费用
/review	代码审查
/init	自动生成 CLAUDE.md
/plan	进入只读规划模式
/rewind	回滚 Claude Code 的修改
/resume	恢复历史会话

几个特别重要的用法：

• /compact：同一任务聊太久时压缩上下文。
• /clear：切换到完全不同任务时清空上下文。
• /rewind：回滚 Claude Code 改过的文件，但不能撤销已经执行过的终端命令。
• /context：发现回答变慢或质量下降时，先看上下文占比。

交互技巧：

!npm run dev              # 在 Claude Code 里进入 Bash 模式执行命令
@src/auth/login.ts        # 精准引用文件作为上下文
@docs/feature-spec.md     # 引用需求文档让 AI 按规范实现

提示词越短不一定越省钱。需求说得太模糊，AI 会花更多 Token 去探索项目；明确引用文件和需求，通常更准也更省。

---

6. 推荐工作流：Explore → Plan → Implement → Commit

Claude Code 的推荐开发循环是：

Explore：只读探索项目和相关文件
Plan：生成计划，你审核
Implement：按计划修改文件、运行命令
Commit：测试通过后提交代码

这套流程解决的是"AI 一上来乱改"的问题。复杂功能不要直接说"帮我实现"，而要先让它分析：

我想添加搜索功能。请先分析需要修改哪些文件，列出实现计划，等我确认后再开始改代码。

每轮任务结束后，使用 Git 存档：

git add .
git commit -m "完成搜索功能"

如果功能改坏了：

git checkout .

---

7. Prompt 编写的四条纪律

文档中的 Claude Code Prompt 写法可以总结为四条：

1. 任务具体，不要只说"做个登录功能"。
2. 引用已有代码，让 AI 模仿项目风格。
3. 先计划，确认后执行。
4. 一次只做一件事。

不推荐：

帮我同时添加搜索、标签、用户认证和导出功能。

推荐：

帮我先实现书签搜索功能：
- 在书签列表页添加搜索框
- 支持按标题和描述搜索
- 使用前端实时过滤
- 参考 @src/bookmarks/BookmarkList.tsx 的写法

---

8. 大型代码库最佳实践

对于大型项目，文档强调六件事：

1. 第一次进入项目先 /init 生成 CLAUDE.md 初稿。
2. 任务粒度要小，避免一次改太多文件。
3. 频繁使用 /clear 和 /compact 管理上下文。
4. 复杂任务从 /plan 起手。
5. 用 Skills 和 Subagents 卸载长调研任务。
6. 用 MCP / LSP 连接代码之外的工具，如 GitHub、数据库、Jira、Sentry。

经验值：每个任务最好控制在少量文件和有限改动范围内。大需求先拆小，再逐个实现。

在 monorepo 中，不要总是在仓库根目录启动 Claude Code；应进入要修改的子目录启动，减少上下文污染。

---

9. 新项目启动套件

文档给出一个新项目可复用的启动套件，核心是：

CLAUDE.md
.claude/settings.json
.gitignore
9 个 Slash Command / Skills

CLAUDE.md 负责项目规则，settings.json 负责放行安全操作和封锁危险操作，.gitignore 防止 AI 工具本地配置和密钥被提交，Slash Commands / Skills 把审查、提交、部署检查等流程标准化。

推荐做法：

• 全局放通用 settings 和 Skills。
• 每个项目单独维护 CLAUDE.md。
• AI 每犯一次可复现的错，就更新 CLAUDE.md 或 Skill。
• 每 3-6 个月审查配置，删除过时规则。

---

10. Plan Mode 与权限模式

Claude Code 有三种运行模式：

模式	行为	适合场景
Normal	修改文件和执行命令前需要确认	默认安全模式
Auto-Accept	自动接受编辑	已规划好的可信任务
Plan Mode	只读分析，不允许修改	复杂任务、陌生代码库、架构决策

进入 Plan Mode 的方式包括：

claude --permission-mode plan

也可以在会话中使用 /plan，或通过快捷键切换。Plan Mode 的价值是：AI 在动手前只能读文件、搜索和提方案，不会修改项目。它适合任何"一动牵全身"的任务。

---

11. 本笔记复盘问题

1. CLAUDE.md 和 settings.json 分别管什么？
2. /compact 和 /clear 什么时候用？
3. 为什么复杂任务要先 Plan Mode？
4. /rewind 和 Git 回退有什么区别？
5. 新项目启动套件为什么能减少重复解释成本？