Claude Code 是 Anthropic 推出的终端 AI 编程代理工具。它与普通聊天式 AI 的最大区别在于：Claude Code 直接运行在项目目录所在的终端里，可以读取仓库文件、修改代码、执行命令、运行测试、提交 Git，并把每一步操作的结果回传给模型继续决策。换句话说，它不是一个“帮你贴代码”的工具，而是一个“在你的项目里替你干活”的代理。
围绕 Claude Code 的使用，目前热度最高的是 MCP、Agent Skill、Hook、图片、上下文处理、后台任务这六类话题。MCP 解决外部工具接入，Agent Skill 解决工作流沉淀，Hook 解决生命周期自动化，图片处理解决多模态输入，上下文处理解决长会话可维护性，后台任务解决长时间任务的效率问题。这篇文章按“是什么、为什么、怎么做、怎么查”的顺序，从安装开始，把这几项能力逐个跑通。
本文适合三类读者：第一次接触 Claude Code、想搞清楚基础用法的入门开发者；已经在用 Claude Code 但只是简单聊代码、还没有接入 MCP 和 Skill 的进阶用户；以及需要在团队里统一 AI 协作规范、想把 MCP 白名单、Hook 审计策略、Skill 模板沉淀下来的工程负责人。读完你会得到一套可以从零复现的实践路径，以及对应的排查清单。
1. 先理解 Claude Code 和六项核心能力的定位
1.1 Claude Code 到底是什么
Claude Code 是 Anthropic 推出的命令行编程代理（agentic coding tool）。它不是一个 IDE 插件，也不是一个网页聊天框，而是一个跑在终端里的“代理程序”。当你在项目根目录执行claude命令后，它会获得当前项目的文件读写能力、命令执行能力，以及调用外部工具的能力。
从工作方式上看，Claude Code 的核心循环是：读取任务、规划步骤、调用工具、观察结果、继续执行。比如你让它“给这个项目补充单元测试”，它可能会先列出测试目录，读取被测模块，分析代码里的分支和边界条件，然后生成测试文件，最后运行测试命令并把失败信息带回上下文继续修复。
这里的“代理”二字非常关键。普通聊天 AI 只负责生成文字，你能拿到的是代码片段；而 Claude Code 会主动操作系统，你能拿到的是“文件已经被修改、测试已经跑完”的真实结果。
1.2 六项能力各解决什么问题
在实际使用中，这六项能力并不是平行的，它们分别落在不同层面。
| 能力 | 解决的核心问题 | 使用层面 |
|---|---|---|
| MCP | 让 Claude Code 调用外部工具、数据库、浏览器、设计稿等资源 | 外部能力接入 |
| Agent Skill | 把高频工作流程沉淀成可复用的指令包 | 工程化与规范 |
| Hook | 在生命周期节点自动执行本地命令 | 自动化与控制 |
| 图片 | 让模型读取截图、设计稿、报错弹窗 | 多模态输入 |
| 上下文处理 | 管理上下文窗口，压缩和保留有效信息 | 会话维护 |
| 后台任务 | 让长时间任务与主对话并行运行 | 工作效率 |
理解这个分层很重要。MCP 和 Skill 一个管“接工具”，一个管“定流程”；Hook 管“自动化控制”；图片和上下文处理属于“输入与状态管理”；后台任务属于“并发与效率”。很多人把 MCP 和 Skill 混为一谈，实际上 MCP 提供的是工具能力，Skill 提供的是做事的方法，两者可以配合使用。
1.3 使用 Claude Code 需要建立的基本认知
第一，Claude Code 很强大，但它不是“免检工具”。它执行的每一条命令、修改的每一个文件，最终责任都在你身上。第二，它的效果高度依赖你提供的上下文。上下文越准确、越精炼，结果越好。第三，它支持扩展，但扩展也意味着安全边界的扩大。接入 MCP Server、配置 Hook 之前，都要先想清楚权限边界。带着这三条认知进入后续章节，你会少踩很多坑。
2. 安装与环境准备
2.1 环境要求
Claude Code 的安装要求并不复杂，但先列一个检查清单能省去后面的排错时间。
| 检查项 | 建议要求 |
|---|---|
| 操作系统 | macOS、Linux，Windows 建议使用 WSL2 |
| Node.js | 18 及以上，建议 LTS 版本 |
| 账号 | Claude 账号（订阅制）或 Anthropic API 密钥 |
| 终端 | bash、zsh、PowerShell 均可 |
| 网络 | 能正常访问安装源和官方服务即可 |
如果没有 Node.js，先去安装 Node.js LTS 版本。Windows 用户如果直接在 PowerShell 里遇到安装报错，常见原因是执行策略受限，优先考虑 WSL2 环境或者换用 npm 安装方式。
2.2 通过 npm 安装
npm 方式是跨平台最统一的方式：
npm install -g @anthropic-ai/claude-code安装完成后检查版本：
claude --version如果能输出版本号，说明安装成功。
2.3 通过官方安装脚本安装
macOS 和 Linux 可以使用官方安装脚本：
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell 用户可以参考官方提供的安装脚本方式：
irm https://claude.ai/install.ps1 | iex这里要注意：安装命令和脚本会随着版本更新而变化，落地前先到官方文档确认当前推荐方式。
注意：不要同时混用 npm 全局安装和脚本安装，否则可能出现两个版本的
claude互相覆盖，导致命令行为不一致。
2.4 首次启动与登录
在项目根目录执行：
claude首次启动会进入登录流程。登录方式一般有两种：一是通过浏览器完成 Claude 账号授权，二是使用 Anthropic API 密钥。订阅 Claude 的用户通常直接使用账号授权，需要按 API 计费的项目则使用 API 密钥。
登录成功后，Claude Code 会扫描当前目录，并告诉你它具备哪些能力。实际使用中，每次启动前最好先确认当前目录确实是目标项目根目录，因为 Claude Code 的所有文件操作都基于当前工作目录展开。
2.5 VS Code 集成
搜索热词里“vscode 配置 claude code”出现频率很高。如果你习惯在 VS Code 里工作，可以从扩展市场安装 Claude Code 官方扩展，然后在 VS Code 的终端中运行claude。扩展的优势是能识别当前打开的工作区，项目级的.claude配置也会被自动识别。
另一种轻量做法是不安装扩展，直接在 VS Code 内置终端里运行claude。对多数场景来说，内置终端已经足够，而且少了一层扩展的维护成本。
2.6 PowerShell 安装报错排查
Windows 上最容易遇到的是 PowerShell 报错，典型现象和对应处理方式如下。
| 现象 | 常见原因 | 处理建议 |
|---|---|---|
claude不是内部或外部命令 | Node.js 未安装，或 npm 全局目录不在 PATH | 安装 Node.js，检查npm prefix是否在 PATH |
| 安装时提示权限不足 | npm 全局目录无写权限 | 改用 nvm 管理 Node.js，避免直接改系统目录权限 |
| PowerShell 禁止执行脚本 | 执行策略限制 | 使用 npm 安装方式绕过 ps1 脚本 |
| 安装过程超时 | 网络不稳定或源下载慢 | 检查网络连接，必要时换用较稳定的 npm 镜像源 |
这些属于安装阶段的常规问题，排完后一般都能顺利进入登录流程。
3. 用 MCP 接入外部工具和服务
3.1 MCP 是什么
MCP 全称 Model Context Protocol，中文常译作“模型上下文协议”。它是 Anthropic 提出的开放协议，核心目的只有一个：统一 AI 应用与外部工具之间的接口。你可以把它理解成“AI 界的 USB 接口”。
在没有 MCP 之前，每个 AI 工具接入一个外部服务都要单独写一套适配代码。有了 MCP 之后，只要服务方实现一个 MCP Server，任何支持 MCP 的客户端都能直接使用。Claude Code 就是 MCP 客户端之一，而数据库、浏览器、设计稿平台、文件系统等都可以作为 MCP Server 暴露工具。
3.2 MCP Server 与 MCP 协议的两种形态
MCP 协议规定了客户端与 Server 之间的通信方式。实际部署时，MCP Server 通常分为两种形态。
| 类型 | 传输方式 | 典型场景 |
|---|---|---|
| 本地 MCP Server | stdio（标准输入输出） | 数据库、文件系统、本地命令行工具 |
| 远程 MCP Server | HTTP / Streamable HTTP | 团队共享服务、云端设计平台 |
本地 MCP Server 的特点是每次启动 Claude Code 时由它在本地拉起进程，输入输出通过管道传输；远程 MCP Server 则通过 URL 访问。理解这个区别是为了后面排查：本地 MCP 工具找不到时，先检查命令能否独立运行；远程 MCP 工具不通时，先检查 URL 和网络。
3.3 查看和管理 MCP 配置
在项目里查看已有的 MCP Server：
claude mcp list这是排查 MCP 问题的第一步。如果配置存在但没有生效，多半是作用域或者启动时机的问题。
3.4 添加一个本地 MCP Server
以官方 filesystem 示例为例：
claude mcp add --transport stdio demo-fs -- npx -y @modelcontextprotocol/server-filesystem /tmp/workspace这条命令的含义是把一个本地 MCP Server 注册到 Claude Code，名字叫demo-fs，由npx拉起对应的 Server 进程，并允许它访问/tmp/workspace目录。
MCP 配置可以存在两个层级：用户级配置和项目级配置。用户级配置对当前用户的所有项目生效；项目级配置写在项目根目录的.mcp.json中，随仓库共享给团队成员。
项目级.mcp.json的常见结构如下：
{ "mcpServers": { "demo-fs": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"] } } }如果接的是远程 MCP Server，则配置 URL：
{ "mcpServers": { "remote-api": { "type": "http", "url": "https://mcp.example.com/mcp" } } }要注意：不同版本的 Claude Code 对.mcp.json的字段要求略有差异。老版本可能没有type字段，新版本对本地和远程 Server 的标识更严格。落地前先以当前安装版本的claude mcp list输出为准。
3.5 快速验证 MCP Server 连通性
添加完成后，在交互会话里输入：
/mcp这个命令会展示当前会话关联的 MCP Server 列表和工具状态。也可以直接问 Claude：当前有哪些 MCP 工具可用。如果列表里能看到刚添加的 Server，说明链路已经通了。
3.6 构建一个最小 MCP Server
有些搜索热词提到“mcp 服务 demo”“bp 搭建 mcp 服务器”。如果找不到现成的 Server，自己搭一个最小 Server 也不难。下面用一个 TypeScript 版本的示例展示核心逻辑。
先初始化工程并安装依赖：
mkdir demo-mcp && cd demo-mcp npm init -y npm install @modelcontextprotocol/sdk zod写一个最小 Server：
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer({ name: "demo-calc", version: "1.0.0" }); server.tool( "add", "两个数字相加", { a: z.number(), b: z.number() }, async ({ a, b }) => ({ content: [{ type: "text", text: `${a + b}` }] }) ); const transport = new StdioServerTransport(); await server.connect(transport);编译后注册到 Claude Code：
npx tsc claude mcp add --transport stdio demo-calc -- node dist/index.js这个示例虽然简单，但覆盖了 MCP Server 的三个核心要素：定义 Server、注册工具、建立传输连接。日常项目中，你可以在这个结构上继续扩展数据库连接、文件读取、接口调用等能力。
如果你更熟悉 Python，也可以使用官方 Python SDK：
from mcp.server.fastmcp import FastMCP mcp = FastMCP("demo-calc") @mcp.tool() def add(a: float, b: float) -> float: """两个数字相加""" return a + b if __name__ == "__main__": mcp.run()安装依赖后运行：
pip install mcp python demo_calc.py3.7 常见 MCP 应用场景
MCP 在 Claude Code 生态里的应用已经非常广泛，这里列几个和搜索热词相关的常见方向。
| 场景 | 接入对象 | 典型价值 |
|---|---|---|
| 设计稿转代码 | 蓝湖 MCP、MasterGo MCP、Figma MCP | 让 Claude 直接读取设计稿属性和标注，生成还原度更高的前端代码 |
| 浏览器自动化 | Playwright MCP | 自动打开页面、点击、截图，适合做端到端验证 |
| 数据库读取 | 自建数据库 MCP Server | 让 Claude 查询表结构、执行只读 SQL，辅助生成数据层代码 |
| 文件系统访问 | filesystem MCP Server | 跨目录读写，适合处理大型仓库中的局部文件 |
搜索热词里“claude code 安装 mcp 读取数据库”关注度很高。这里有一个明确的安全建议：
重要：不要给 MCP Server 使用生产库的管理员账号。即使只是本机开发，也建议使用只读账号，并且不要在
.mcp.json里直接写数据库密码，尽量通过环境变量注入。
3.8 MCP 排查链路
MCP 工具不出现时，按以下顺序检查：
claude mcp list看配置是否已被加载。- 确认添加时用的是用户级还是项目级作用域，当前目录是否匹配。
- 本地 Server 单独在终端里运行一次，确认命令本身能正常启动。
- 检查 Server 日志中的 stderr 输出，Node 程序常见的报错会直接反映在终端。
- 新增配置后重启 Claude Code 会话，再通过
/mcp验证。
4. 用 Agent Skill 沉淀可复用的工作流
4.1 Skill 是什么
Agent Skill 是 Claude Code 中一种用文件形式封装的“能力包”。一个 Skill 的核心是一个SKILL.md文件，里面写清楚“这个能力适用于什么场景、执行步骤是什么、有哪些注意事项”。Skill 还可以附带脚本、模板、参考文档。
Skill 的价值在于沉淀。团队里常见的“如何生成 README”“如何补测试”“如何做代码评审”“如何按规范提交 Git 信息”等方法论，都可以写成 Skill。Claude Code 会根据当前会话内容自动匹配相关 Skill，不需要用户手动加载。搜索热词里“agent skill”“skills 官方文档”指向的正是这套机制。
4.2 Skill 与 Agent 的区别
搜索热词里“skill 和 agent 的区别”是一个高频问题。两者确实容易混淆，因为它们都服务于“让 AI 更专业地完成任务”这个目标。
| 维度 | Agent Skill | Agent（子代理） |
|---|---|---|
| 本质 | 教学方法和流程的知识包 | 可独立执行任务的运行单元 |
| 触发方式 | 模型根据会话内容自动加载 | 用户显式指派或按需创建 |
| 典型用途 | 固定流程、编码规范、模板 | 分工、并行执行、上下文隔离 |
| 文件形态 | SKILL.md加辅助脚本 | 独立的系统提示和工具配置 |
简单理解：Skill 是“教 Claude 怎么做事”，Agent 是“把一个完整任务派给一个独立助手去做”。两者可以配合，一个 Agent 的执行过程中也可以加载多个 Skill。
4.3 创建第一个 Skill
在项目根目录创建.claude/skills目录，一个 Skill 占一个子目录。以“生成 README”为例：
.claude/skills/generate-readme/ ├── SKILL.md └── scripts/ └── build-toc.shSKILL.md的结构如下：
--- name: generate-readme description: 为项目生成或更新 README.md，适用于需要补充项目说明、安装命令、目录结构、使用示例的场景 --- # 生成 README 当生成 README.md 时，按照以下步骤执行： 1. 列出项目根目录和主要子目录的结构。 2. 检查包管理文件（package.json、pyproject.toml、pom.xml 等），确认真实存在的安装命令。 3. 补全项目名称、简要说明、安装命令、使用示例。 4. 运行 scripts/build-toc.sh 生成目录锚点。 5. 将最终内容交给用户确认，不要直接覆盖已有 README。 ## 注意事项 - 不编造安装命令，以仓库实际配置为准。 - 生产项目不要在 README 中写入密钥、内网地址或未公开的接口信息。这里的关键是description字段。Claude Code 靠这个描述来判断“当前对话是否需要加载这个 Skill”。写得太宽泛，会在无关场景被调用；写得太窄，则很难被匹配到。
4.4 Skill 如何调用 MCP 工具
搜索热词里“skills 如何调用 mcp 工具”也是一个常见困惑。直接答案是：Skill 本身不需要也不负责配置 MCP。Skill 只是告诉模型“要完成这类任务时该按什么流程做”，而 MCP 工具列表是独立注册的。
如果 Skill 描述的工作需要查询数据库，模型在执行时自然会从已注册的 MCP 工具中选择合适的一个。前提是 MCP Server 已经通过claude mcp add或项目.mcp.json配置好。以“检查数据库表结构”为例：
--- name: db-schema-check description: 检查数据库表结构并生成变更说明，适用于涉及 DDL 变更评审的场景 --- # 数据库表结构检查 执行步骤： 1. 调用已配置的 database MCP 工具，执行只读 SQL，获取目标表结构。 2. 对比改动前后索引、字段类型、默认值等差异。 3. 输出变更说明，标注可能导致锁表或数据迁移风险的点。 ## 注意事项 - 只允许执行只读 SQL，禁止通过 MCP 工具执行写操作。可以这样理解：MCP 是“手”，Skill 是“操作手册”。手册里会提到要用手做什么，但手本身在更早的环节就已经接好了。
4.5 Skill 设计要点与常见误区
| 误区 | 现象 | 正确做法 |
|---|---|---|
| description 太宽泛 | 无关场景也加载 Skill，浪费上下文 | 写清触发条件和边界场景 |
| SKILL.md 内容太长 | 每次加载占用大量上下文 | 只写流程和关键规则，细节放辅助脚本 |
| 脚本没有异常处理 | 执行到一半静默失败 | 脚本要输出明确错误信息 |
| 把敏感信息写进 Skill | 项目共享后密钥泄漏 | 敏感信息一律用环境变量外部注入 |
| 把 Skill 当文档库 | 加载后没有可执行步骤 | 每个 Skill 都要有明确输入、步骤和输出 |
Skill 是团队 AI 工程化的核心载体。建议从一两个高频场景开始写，等模型匹配准确了再逐步扩展。
5. 用 Hook 在生命周期节点执行自动脚本
5.1 Hook 机制是什么
Claude Code 的 Hook 是生命周期钩子。当某个事件发生时，Claude Code 会自动执行你预先配置的本地命令。这里的“事件”包括用户发送消息、工具调用前后、Claude 回答结束、会话开始、上下文压缩前等节点。
Hook 的价值在于自动化控制。你可以在写文件前自动运行格式化器，在删除操作前执行备份，在会话结束时清理临时文件，在每条消息提交前追加团队规范。搜索热词里的“hook”指的就是这一机制，和游戏外挂、逆向工程里的“hook”完全是两回事。
常用事件如下：
| 事件名 | 触发时机 | 典型用途 |
|---|---|---|
| SessionStart | 会话开始时 | 加载环境变量、写入审计日志 |
| UserPromptSubmit | 用户消息提交前 | 追加规则，记录输入 |
| PreToolUse | 工具调用执行前 | 拦截危险操作，统一格式化 |
| PostToolUse | 工具调用执行后 | 检查产物，记录结果 |
| Stop | Claude 回答结束时 | 清理临时文件，发送通知 |
| PreCompact | 上下文压缩之前 | 保存关键摘要信息 |
不同版本的 Claude Code 对事件名的支持会有差异，配置前先查看当前版本的事件列表。
5.2 配置 Hook 的两种位置
Hook 配置在settings.json中。用户级配置文件位于~/.claude/settings.json，项目级配置文件位于.claude/settings.json。项目级配置可以随仓库共享，但也意味着仓库里的脚本会被本机执行，使用前要审查内容。
一个项目级配置示例：
{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "python3 .claude/hooks/validate-write.py" } ] } ], "SessionStart": [ { "hooks": [ { "type": "command", "command": "echo \"session started\" >> .claude/session.log" } ] } ] } }matcher用来匹配工具名或模式，只有匹配上的工具调用才会触发对应的 Hook。command就是要执行的本地命令。命令里的环境变量会由 Claude Code 注入，常见的有项目目录、工具名、文件路径等。
5.3 典型 Hook 场景
第一个场景是“写文件前统一格式化”。在 PreToolUse 中监听Write、Edit、MultiEdit，让 Claude 写入代码前先经过格式化工具：
{ "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "npx prettier --write" } ] } ] }第二个场景是“删除前备份”。监听Bash工具，匹配包含rm的命令，先复印文件到备份目录：
{ "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python3 .claude/hooks/backup-before-rm.py" } ] } ] }第三个场景是“异步任务完成通知”。当 Claude 进入空闲或任务结束时，用系统通知提醒你回来查看：
{ "Notification": [ { "hooks": [ { "type": "command", "command": "osascript -e 'display notification \"Claude 任务结束\" with title \"Claude Code\"'" } ] } ] }这里只做示例说明，具体命令要结合操作系统和团队场景调整。
5.4 Hook 调试与排查
Hook 不触发时，按下面的顺序排查：
- 检查
settings.json是否是有效的 JSON，缩进错误会导致整个配置失效。 - 确认配置在用户级还是项目级，当前会话有没有加载对应目录。
- 手动执行一次 Hook 里的 command，确认命令本身不报错。
- 命令尽量使用绝对路径，避免 PATH 不一致导致找不到可执行文件。
- 用
claude --debug启动，观察终端中是否有 Hook 相关的日志输出。 - 检查 matcher 是否和实际工具名匹配，正则错误是最常见的低级问题。
重要：项目级 Hook 会在你的机器上执行仓库内的本地命令。第一次使用他人提供的
.claude/settings.json前，要逐条审查命令内容，不要在未确认的情况下运行陌生脚本。
6. 图片处理与上下文管理
6.1 Claude Code 如何读取图片
Claude Code 支持把图片作为输入。在交互会话中，你可以直接把本地图片路径交给它，例如：
请分析这张截图，帮我找出布局问题：/path/to/screenshot.png也可以把图片 URL 提供给 Claude，让它读取网络图片。桌面版和部分终端环境还支持直接粘贴图片，但最稳定的方式是提供本地路径。
图片格式一般以常见的 png、jpg、webp 为主。超大图片会显著占用上下文，建议先压缩到合适尺寸再输入。
6.2 图片的典型使用场景
图片处理的核心场景有三个。
第一是前端还原。结合搜索热词里的“蓝湖 MCP”“MasterGo MCP”“Figma MCP”，Claude 可以读取设计稿属性，再配合界面截图对比还原效果。第二是报错排查。把终端报错截图、浏览器弹窗截图交给 Claude，它能识别错误信息并给出排查方向。第三是 UI 测试。使用 Playwright MCP 自动截图后，让 Claude 分析布局是否异常，再生成修复代码。
6.3 上下文窗口与 /context
上下文窗口是模型在一次会话中能同时看到的 token 总量。Claude Code 的会话里，系统提示词、工具定义、MCP 工具描述、历史对话、文件内容都会占用这个窗口。会话越聊越长，可用空间就越小。
使用/context可以查看当前上下文的占用情况和主要构成。当 Claude 开始“忘记”前面的指令，或者回答质量明显下降时，第一步不是重新提问，而是先看上下文是否接近上限。
6.4 用 /compact 和 /clear 管理上下文
/compact会对当前对话做一次压缩，把长历史归纳成摘要，释放上下文空间。适合“任务没做完但对话已经很长”的场景。
/clear会清空当前会话历史，相当于开启一个全新的会话。适合“已经换了一个任务，旧历史不再有用”的场景。
实际操作中，推荐顺序是：先用/context看占用，再用/compact压缩，最后才考虑/clear。不要一上来就清空会话，那样会丢掉前面有价值的信息。
6.5 上下文超限与额度提示
使用过程中，你可能会看到和用量限制相关的提示，类似“your limits are temporarily boosted. your weekly Claude Code limit is 50%”这样的通知。这类提示说明当前账号的周额度使用达到一定比例，或者属于 Anthropic 临时提升额度的提示信息。
遇到额度提示时，需要区分两种情况：如果提示只是通知，说明额度仍然可用，继续工作即可；如果提示限制，说明当前会话或周期内的使用量已经接近上限。处理建议是：先/compact压缩会话，把大任务拆分成多个小任务，减少一次性占用；再检查账号的用量页面，确认是否需要调整订阅或等待额度恢复。
6.6 减少无效上下文的实践
| 做法 | 效果 |
|---|---|
| 不要一次性粘贴整个文件全文 | 大幅降低上下文占用 |
| 用 grep 或项目工具精准定位再读取 | 只把关键代码段放入上下文 |
| 把稳定规范写进 SKILL.md | 避免每次重复粘贴长规则 |
| 长会话定期 /compact | 保持上下文健康 |
| 独立的小任务用一次性模式 | 不污染主会话历史 |
一次性模式示例：
claude -p "列出当前项目中所有测试文件的路径"-p模式适合单次提问，不进入交互式长会话，上下文压力最小。
7. 后台任务与长时间操作
7.1 后台任务机制
Claude Code 支持后台任务。在交互会话中，可以使用/background启动一个后台任务，然后回到主会话继续处理其他事情。后台任务运行期间，你不必一直等待。
这种机制解决的是一类非常实际的问题：Claude 执行长时间测试、批量生成文件、运行端到端流程时，如果你的对话被阻塞，效率会很低。引入后台任务后，可以同时推进多个相对独立的事情。
7.2 典型使用场景
| 场景 | 说明 |
|---|---|
| 运行完整测试套件 | 测试可能持续几分钟，不需要一直盯着 |
| 批量文件重构 | 大量文件替换和格式化可以在后台进行 |
| 生成项目脚手架 | 创建大量目录和模板文件，耗时较长 |
| 端到端浏览器流程 | Playwright MCP 执行完整页面流程时耗时明显 |
使用场景上，后台任务适合那些“不需要人工中途确认”的耗时操作。涉及删除生产文件、修改敏感配置等需要决策的操作，不建议放进后台任务。
7.3 后台任务的使用要点
第一，后台任务结果需要显式拉回主会话。后台任务完成后，用/bg查看任务状态和输出，再决定是否把关键结果注入当前上下文。第二，不要同时启动过多后台任务，否则资源占用会明显上升，也可能造成上下文混乱。第三，长时间后台任务要关注账号额度和上下文消耗，避免任务还没跑完额度先耗尽。
后台任务是一个效率工具，不是“甩手掌柜”工具。启动前要明确任务边界，启动后要检查结果。
8. 常见问题排查与最佳实践
8.1 常见问题排查清单
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
claude命令找不到 | Node.js 未安装或 PATH 不对 | node -v、npm -v、which claude | 安装 Node.js，修正 PATH |
| MCP 工具不出现 | 配置作用域错误或未重启会话 | claude mcp list、/mcp | 确认作用域，重启会话验证 |
| 本地 MCP Server 启动失败 | 依赖未安装或路径不对 | 单独在终端运行 Server 命令 | 安装依赖，检查命令路径 |
| Hook 不触发 | 事件名写错、matcher 不匹配 | claude --debug查看日志 | 校验 JSON，检查 matcher |
| 图片读取失败 | 路径错误或格式不支持 | 先手工打开图片 | 转成 png/jpg，压缩文件 |
| 上下文超限 | 会话过长或大文件反复读取 | /context | /compact或/clear |
| 额度提示频繁 | 会话占用过大 | 查看账号用量 | 压缩会话，拆分任务 |
| 后台任务无结果 | 任务仍在运行或结果未拉回 | /bg查看状态 | 等待完成，显式拉取结果 |
这张表覆盖了前面六个能力最常见的故障点。实际排查时，顺序很重要：先检查输入是否准确，再检查路径和版本，最后看日志。
8.2 学习环境与生产环境的差异
学习阶段建议在临时仓库里快速尝试，使用只读 MCP，Hook 只做日志记录，图片和上下文操作不必太在意成本。
进入生产环境后，需要额外考虑五件事。
第一，把.claude/skills/、.claude/settings.json纳入版本管理，让团队成员共享同一套规范和流程。第二，.mcp.json里的敏感参数不要直接写死，使用环境变量注入。第三，Hook 命令使用最小权限，不要在脚本里使用 root 或管理员权限。第四，MCP Server 尤其是数据库类 Server，必须使用只读账号。第五，建立审计机制，通过 Hook 记录关键会话的开始时间、提交的 prompt、产出的文件列表。
成本和安全是生产环境绕不开的话题。Claude Code 会消耗账号额度，长时间后台任务和频繁的大文件读取都会加速额度消耗。建议在团队内约定使用规范，明确哪些操作可以用，哪些操作必须人工执行。
8.3 与周边工具的选型视角
搜索热词里还有几组常被放在一起对比的概念，这里给出一个实用判断视角。
“computer use 和 MCP 的区别”：MCP 是工具接入协议，解决“AI 如何调用外部能力”；computer use 是让模型直接操作图形界面，通过截图分析、鼠标键盘控制完成操作。两者的目标是互补的，设计稿读取适合 MCP，桌面软件自动化适合 computer use。
“codex 和 Claude Code 的区别”：两者都是终端 AI 编码代理，选型时重点关注模型能力、MCP 生态、团队已有的基础设施和成本模式，没有绝对的最优解。
“claude code + cc switch + ollama”：这和本地模型切换有关。社区中有工具允许把 Claude Code 指向其他模型，包括通过 Ollama 运行本地模型。这类方案适合探索和成本控制，但兼容性和功能完整性需要以实际版本为准。
8.4 团队落地建议
如果要在团队里推广 Claude Code，建议先做三件事。
第一，整理一份团队 AI 协作规范，明确 MCP 白名单、Hook 审计策略、Skill 目录结构。第二，从三个高频场景开始沉淀 Skill，例如 Git 提交信息生成、测试补充、代码评审，验证模型匹配效果后再扩展。第三，建立安全审查流程，凡是进入.mcp.json的 Server 和进入.claude/settings.json的 Hook，都要经过代码审查。
8.5 下一步可以怎么走
这篇文章从安装开始，把 Claude Code 的六项核心能力逐一跑通：MCP 解决外部工具接入，Agent Skill 解决流程沉淀，Hook 解决自动化控制，图片解决多模态输入，上下文处理解决会话健康，后台任务解决执行效率。
如果你刚接触 Claude Code，下一步建议是：在一个临时仓库里创建一个最小项目，接入一个本地 MCP Server，写一个最简单的 Skill，配一个输出日志的 Hook，最后跑一次图片识别和后台任务。这六个步骤全部走完，你就完成了从“会启动”到“会工程化使用”的跨越。等这些基础稳定后，再逐步引入桌面版、computer use、本地模型切换等更外围的能力，结合自己的项目场景不断迭代这套工作流。
 全解)
