Claude Code 终端AI编程智能体实操：MCP/Skill/Hook全解析

这次我们来看 Claude Code——Anthropic 官方推出的终端 AI 编程智能体。它不是在 IDE 里做个补全插件而是在终端里直接读项目、改文件、跑命令、操作 Git遇到外部系统还能通过 MCP 调工具。现在网上相关的教程不少但大多停在“怎么安装、怎么聊天”。真正影响日常开发效率的其实是 MCP、Agent Skill、Hook、图片读取、上下文处理和后台任务这六个能力点。这篇文章会按从 0 到 1 的顺序把这些能力全部过一遍先装好 Claude Code 并初始化项目然后逐个验证 MCP 工具接入、Skill 技能封装、Hook 生命周期钩子、图片读取、上下文压缩与清理、后台任务和批量任务。最后补上性能观察、常见排查和最佳实践。先给结论Claude Code 不需要本地 GPU 和显存模型推理在云端完成本地只需要一个 Node 环境和网络。它支持无头模式适合批量任务和 CI 接入有完整的.mcp.json和 skills 目录规范也有 Hook 安全机制。无论你是第一次装还是已经用了几天想系统整理这篇都可以直接照着操作。1. Claude Code 核心能力速览能力项说明项目类型终端 AI 编程智能体CLI Agent开发方Anthropic 官方核心能力代码编辑、命令执行、Git 操作、MCP 工具调用、Agent Skill、Hook、图片读取、后台任务支持平台macOS、Linux、WindowsWindows 推荐配合 WSL 或 PowerShell 使用安装方式npm 全局安装模型接入Claude 账号订阅登录或配置 ANTHROPIC_API_KEY显存 / GPU不需要本地 GPU 和 CUDA推理在云端完成启动方式终端执行claude也可通过 VS Code 扩展接入接口能力支持-p/--print无头模式可脚本化、可接入 CI批量任务支持可通过无头模式循环任务或用/bg跑后台任务数据安全项目文件会发送到云端模型服务敏感代码需先做脱敏和授权评估从这张表能直接看出来Claude Code 的门槛不在硬件而在环境配置和使用方法。接下来先讲它能用在哪、哪些场景应该避开。2. 适用场景与使用边界Claude Code 适合这几类场景多文件重构改一个接口连带更新调用方、测试和文档。测试编写与修复按需求写单测跑完把失败信息甩给它继续修。Git 操作commit message、分支整理、冲突排查。项目勘误和排查定位报错、搜索上下文、给出修复方案。接入外部工具通过 MCP 连数据库、浏览器、设计稿平台让 Agent 能直接读外部数据。例行任务自动化用后台任务和 Hook 把重复劳动做成固定流程。不适合的场景也要说清楚完全离线环境跑不起来所有推理都依赖 Anthropic 服务。涉及公司私有代码、未脱敏的用户数据时要慎重。代码会发送到云端模型如果你所在团队有保密要求需要先走合规评估。需要人工严格审批的高风险操作比如生产环境删数据、强制推送不能直接交给 Agent 自动执行。图片识别和文档解析有基本限制复杂表格、公式类 PDF 建议用专业 OCR 工具。边界问题上凡是要处理的素材涉及人脸、声音、版权设计稿、用户隐私都必须确认授权后再放进对话。这是本地 Agent 工具的基本红线。3. 环境准备与安装部署3.1 检查 Node 环境Claude Code 以 npm 包形式分发先确认本机 Node 版本。从官方安装说明看Node.js 18 或更高版本是基础要求。node -v npm -v如果node命令不存在先去安装 Node.js。建议用 nvm 管理版本避免系统目录权限问题。3.2 全局安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后验证版本claude --versionmacOS / Linux 如果遇到全局安装权限不足可以用 nvm 安装 Node或者在命令前加sudo但不推荐直接改系统目录权限。Windows 下如果 PowerShell 报“执行策略限制”以管理员身份执行一次Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重新打开终端。3.3 登录或配置 API Key首次运行claude会进入登录引导可以选择用 Claude 订阅账号登录适合个人开发者。配置 Anthropic API Key适合脚本化、CI、团队共享机器。配置 Key 的方式是设置环境变量# Linux / macOS export ANTHROPIC_API_KEYsk-ant-写入你的Key # Windows PowerShell # $env:ANTHROPIC_API_KEY sk-ant-写入你的Key启动服务claude看到交互式提示符后输入/help能确认当前版本和可用命令。安装遇到网络卡顿可以先把 npm 源切到镜像源再装npm config set registry https://registry.npmmirror.com4. 基础使用流程初始化、CLAUDE.md 与 Agent 模式4.1 进入项目并初始化在项目根目录运行claude然后用/init生成 CLAUDE.md。这个文件会被 Claude Code 在每次对话开始时自动读取相当于项目的“长期记忆”。cd your-project claude /initCLAUDE.md 里写什么最有价值项目技术栈和目录结构。代码风格约定、命名规范。测试命令和构建命令。常见坑和规避方式。4.2 记忆文件的管理Claude Code 的记忆文件分两层层级路径作用项目级./CLAUDE.md跟随当前项目进仓库团队共享用户级~/.claude/CLAUDE.md全局偏好所有项目生效对话中输入/memory可以快速查看和编辑记忆文件。规范、约束、常用命令都建议写进 CLAUDE.md而不是每次口头重复。4.3 Plan 和 Act 模式Claude Code 默认有 Plan 和 Act 两种模式Tab 键切换。Plan 模式只分析、出方案不执行命令不改文件。Act 模式可以执行命令、写文件、跑测试。第一次跑任务建议先切到 Plan让它给出执行计划确认无误后再切成 Act 执行。这能减少 Agent 突然乱改文件的风险。4.4 完成第一个任务进入项目后直接提需求例如请分析 src/ 目录下的模块依赖关系找出循环依赖并输出重构建议。观察它的执行步骤确认 Diff 后再接受修改。这里要养成习惯任何自动改动都必须先看 Diff尤其涉及批量替换时。5. MCP 接入与配置5.1 MCP 是什么MCPModel Context Protocol模型上下文协议是 Anthropic 提出的开放协议用来把外部工具和数据源接入 AI Agent。MCP server 提供 toolsClaude Code 在对话中按需调用这些 tools从而读写数据库、操作浏览器、访问设计稿平台。用一句话区分MCP 是“让 Agent 能做事”的工具通道Agent Skill 是“让 Agent 知道怎么做好”的方法沉淀。后面第 6 节详细讲 Skill。5.2 项目级配置.mcp.json在项目根目录创建.mcp.json这个文件会随仓库共享给协作者{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] }, memory: { command: npx, args: [-y, modelcontextprotocol/server-memory] } } }配置示例里用了两个常见 serverplaywright 负责浏览器自动化memory 提供持久化记忆。实际使用按需添加不要一次性挂太多每个工具都会增加模型的选择成本。5.3 命令行管理 MCP不写文件时可以用命令行直接管理# 添加一个 MCP server claude mcp add memory -- npx -y modelcontextprotocol/server-memory # 查看已配置的 server 列表 claude mcp list # 查看某个 server 的详细配置 claude mcp get memory # 移除不再需要的 server claude mcp remove memoryclaude mcp add支持通过--scope指定作用域user / project / local建议项目级配置一律走.mcp.json避免全局污染。5.4 验证 MCP 是否生效重启会话后在对话里输入你现在能使用哪些工具列出 MCP 工具的名称和用途。如果配置成功可以看到类似mcp__memory__...格式的工具名。再让模型实际操作一次比如“把 这几条任务记录保存到 memory”然后查看返回结果确认 server 真的在工作。排查顺序claude mcp list看配置是否存在再看启动日志确认 server 是否拉起最后看对话内容确认工具是否被调用。6. Agent Skill把经验封装成可复用技能6.1 Skill 和 MCP、Agent 的区别社区里经常混淆 Skill、MCP、Agent 这三个概念。它们不是同一层的东西维度MCPAgent SkillAgent本质外部工具/数据通道方法、经验、流程文档自主执行任务的智能体表现形式server tools目录 SKILL.md可以是一个对话实例解决什么让 Agent 能调用外部能力让 Agent 按规范完成任务把任务拆解为执行动作示例查数据库、开浏览器代码评审清单、发布检查手册Claude Code 本身Skill 不写代码逻辑它写的是“怎么做的步骤”。模型读到 SKILL.md 后会在执行相关任务时按里面的流程走。适合把团队规范和踩坑经验沉淀下来。6.2 Skill 目录结构Skill 本质是一个包含SKILL.md的目录放在项目级.claude/skills/skill-name/SKILL.md用户级~/.claude/skills/skill-name/SKILL.md目录里除了 SKILL.md还可以放参考文档、示例代码、模板文件。6.3 编写一个简单 Skill以“前端页面评审”为例--- name: frontend-review description: 当用户要求做前端页面评审、UI 还原度检查时使用关注布局、间距、响应式和可访问性。 --- # 前端页面评审 ## 执行步骤 1. 先读取页面截图或线上 URL。 2. 按清单逐项检查 - 布局是否和设计稿一致 - 间距、字号、颜色是否统一 - 是否适配移动端 - 可访问性alt、对比度、焦点状态 3. 输出问题清单标记严重级别并给出修复建议。保存后重新进入会话输入/skills查看技能是否被加载。描述写得越具体模型越容易在合适时机调用。Skill 命名用短横线小写路径里不要有中文和空格。6.4 Skill 与 MCP 配合同一个任务可以同时用到 Skill 和 MCP。例如前端评审时Skill 负责给出评审流程和清单MCP 负责启动浏览器截图。Skill 可以描述“先调用 playwright 截图再按清单评审”这样模型就有了完整的工作流。7. Hook生命周期钩子注入自动化7.1 Hook 是什么Hook 是 Claude Code 在关键生命周期事件上执行本地脚本的机制。常见用途是安全护栏、自动通知、日志记录、内容检查。例如在模型准备执行 Bash 命令前拦截危险命令在任务结束后发通知。7.2 常用 Hook 事件不同版本支持的事件名可能略有差别以当前版本官方文档为准。常见事件包括事件触发时机用途示例PreToolUse工具调用前拦截危险命令、校验参数PostToolUse工具调用后记录命令输出、做审计日志UserPromptSubmit用户发送提示词后敏感信息过滤、检查输入合法性StopAgent 任务结束时桌面通知、汇总任务状态SubagentStop子 Agent 结束时记录子任务结果PreCompact上下文压缩前保存关键信息SessionStart会话启动时注入环境信息SessionEnd会话结束时清理临时文件7.3 配置 HookHook 写在settings.json中。用户级是~/.claude/settings.json项目级是.claude/settings.json想不进仓库用.claude/settings.local.json。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node .claude/hooks/check-bash.mjs } ] } ], Stop: [ { hooks: [ { type: command, command: node .claude/hooks/notify.mjs } ] } ] } }7.4 示例拦截危险命令下面这个脚本用PreToolUse拦截包含高危操作的 Bash 命令import { readFileSync } from node:fs; const event JSON.parse(readFileSync(0, utf-8)); const command event.tool_input?.command ?? ; const danger [rm -rf, git push --force, curl | sh]; if (danger.some((d) command.includes(d))) { console.log( JSON.stringify({ decision: block, reason: 该命令包含高风险操作已被本地 Hook 拦截请人工确认。 }) ); process.exit(2); } process.exit(0);注意Hook 脚本通过 stdin 接收 JSON 事件数据输出 JSON 和控制退出码的协议会随版本变化写之前先查当前版本的事件格式。Hook 脚本里不要硬编码密钥也不要依赖不存在的路径否则会静默失败或拖慢每次工具调用。8. 图片处理截图、设计稿与文档识别8.1 支持的图片读取方式Claude Code 支持读取图片主要有三种方式对话中直接粘贴图片路径例如“读取screenshot.png”。交互模式下直接拖拽图片到终端。使用/img命令打开图片编辑器。支持的常见格式包括 PNG、JPEG、GIF、WebP 以及 PDF。PDF 会按页转成图片读入页数和体积有限制。单张图片大小通常有上限超过限制需要压缩后再传入具体要求以官方文档为准。8.2 读取图片的验证流程以“截图分析”为例准备一张页面截图放项目目录下。在 Claude Code 对话里输入读取 screenshot.png分析页面布局问题 - 导航栏元素是否有重叠 - 卡片间距是否统一 - 文字对比度是否正常 - 是否存在明显样式错乱 输出问题清单和对应修复位置。预期结果是模型按图片内容给出具体问题描述并指向代码文件。判断成功的标准它提到的元素和布局特征与截图一致修复建议能对应到具体项目代码。8.3 适合和不适合的图片场景适合前端页面截图评审。错误弹窗和日志截图排查。架构图、流程图解释。设计稿还原成基础代码。不适合高精度表格识别、公式识别建议用专业 OCR 模型。模糊、低分辨率、被压缩过度的图片识别效果会明显下降。涉及人脸、证件、个人隐私的图片确认授权前不要上传。9. 上下文处理压缩、清理、记忆与续聊9.1 上下文窗口问题Claude 模型的上下文窗口通常按 200K token 级别设计但长对话、大文件、多轮工具调用都会快速消耗上下文。Claude Code 会在接近上限时提示剩余空间并自动压缩历史对话。9.2 常用上下文命令命令作用/compact压缩当前对话历史保留关键信息释放上下文/clear清空当前会话重新开始/context查看当前上下文引用的文件删除不需要的引用/cost查看 token 消耗和费用/status查看当前模型、会话状态和上下文剩余情况9.3 跨会话续聊终端退出后可以用以下命令恢复# 继续最近一次会话 claude --continue # 选择历史会话恢复 claude --resume--continue适合中断后接着干活--resume适合在多任务会话之间切换。9.4 上下文管理最佳实践上下文变长后先/compact再继续避免后半程模型“忘记”前面的约束。无关文件不要一次性拖进对话只引用需要的部分。项目规范写进 CLAUDE.md而不是每次贴一遍。长任务拆成短任务每段结束用/clear重新开始稳定性和成本都可控。10. 后台任务与批量任务10.1 用 /bg 跑后台任务Claude Code 支持把任务放到后台执行交互界面可以继续做别的事。在对话中发起/bg 请扫描 src/ 目录下所有 TODO 注释按模块汇总成 todo.md后台任务执行时可以用/bgs查看所有后台任务列表和状态。需要重新接入某个后台任务用/bg continue选择对应任务继续。后台任务方式适合需要长时间跑的批量操作比如全仓库重构、批量文档生成、自动化测试修复。10.2 Boot 模式后台任务在发起时可以设置 Boot Prompt。设置后以后打开终端直接运行claude --boot 日常巡检任务就会自动执行预先设定的后台任务适合做成每天开工后的例行流程。这个功能把“手动提需求”变成“开机即跑”是批量工作流里比较实用的一环。10.3 无头模式把 Claude Code 当接口用Claude Code 提供-p/--print无头模式直接把提示词作为参数传入输出结果打印到终端。这是批量任务和 CI 集成的关键接口。单次调用示例claude -p 读取 docs/readme.md提取三个核心要点 --output-format text希望拿到结构化结果用 JSON 输出claude -p 分析 src/ 目录的代码结构返回模块列表 --output-format json循环批量处理文件for f in docs/*.md; do claude -p 总结 $f 的核心内容输出 3 条要点 --output-format text summaries.txt done用 Python 调用也无非是 subprocess 包裹上面的命令或者直接用 Anthropic API 走模型接口。批量任务建议加日志、限流和失败重试避免一次跑挂了全部重来。10.4 后台任务的注意事项后台任务会持续消耗 API token注意每周用量限制。大量并发无头调用容易触发限流建议控制并发数并加退避重试。后台任务结果要落盘不要只留在终端缓冲区。定期用/bgs清理已完成的后台任务避免进程残留。11. 性能观察、成本与限制11.1 本地资源占用Claude Code 本地只是一个 Node 进程不需要显卡和显存。本地进程的内存占用一般从几十 MB 到几百 MB 不等取决于会话长度、缓存的临时文件和插件数量。观察方式Linux / macOS 用htop或ps查 node 进程。Windows 用任务管理器按进程名查找。真正消耗的是云端推理和 token 配额本地通常不会有明显卡顿。11.2 成本观察对话中输入/cost查看 token 消耗输入/usage查看 API 用量。影响消耗的主要因素上下文长度每次交互都会带上历史。图片数量图片 token 消耗远大于文本。MCP 工具调用每次工具结果都会进入上下文。频繁重试和大步数批量任务和自动修复会成倍增加调用次数。如果订阅账号出现类似“weekly limit”的提示说明本周用量额度已经用完或接近上限需要降频或更换方案。团队使用建议走 API 计费并按项目隔离 Key。11.3 本地模型与兼容端点社区有把 Claude Code 接到其他兼容端点或本地模型的工具比如 cc-switch 配合 Ollama。这类方案不是官方能力模型能力、上下文窗口、工具调用质量和稳定性都会明显下降。只建议在测试环境探索生产环境还是以官方模型为准。12. 常见问题与排查方法问题现象可能原因排查方式解决方案npm 全局安装失败Node 版本过低或权限不足执行node -v、检查 npm 日志升级 Node、用 nvm 管理版本或使用镜像源claude命令找不到npm 全局 bin 目录不在 PATH执行npm prefix -g查看路径把 bin 目录加入 PATH或重装 Node登录 / API Key 报错Key 无效、环境变量未生效执行echo $ANTHROPIC_API_KEY重新设置环境变量并重启终端提示 weekly / rate limit订阅或 API 用量超限用/cost查看用量降低调用频率等待额度恢复或升级订阅MCP server 连接失败配置错误或 server 未拉起执行claude mcp list查看状态检查.mcp.json路径和 npx 可用性重启会话Skill 不生效目录结构或 frontmatter 错误用/skills查看加载列表检查SKILL.md路径和name/description字段Hook 不执行settings 路径错误或事件名不对查看启动日志、手动跑脚本修正settings.json路径脚本加可执行权限图片读取失败格式不支持或体积超限查看错误提示压缩图片、转成 PNG/JPEG 再试上下文过长被截断对话历史太长查看/status剩余空间执行/compact或/clear后再继续后台任务丢失会话中断或进程被杀执行/bgs查看用/bg continue重新接入长期任务建议落盘日志部分版本提供claude doctor诊断命令可以先跑一遍检查安装状态、登录状态和环境变量再根据输出定位问题。13. 最佳实践与使用建议第一次使用先小任务验证。不要一上来就让它重构整个项目先用一个文件、一个函数验证交互方式和 Diff 习惯。保留一套最小可运行配置。.mcp.json只放最常用的 serverCLAUDE.md 只写必要规范减少模型选择成本。文件和目录分清楚。模型文件、输入素材、输出结果分开存放批量任务按目录处理避免路径混淆。批量任务必须加日志和失败重试。无头循环里建议记录每个文件的输入输出路径和退出码失败时能定位到具体文件。接口服务注意访问范围。如果你封装了 Claude Code 无头命令作为内部服务要限制调用来源避免被外部滥用。Diff 必须人工审。Agent 自动改代码越来越快但 review 环节不能省尤其涉及批量替换和权限操作时。Hook 里不塞密钥。settings.local.json 不进仓库脚本里敏感信息用环境变量注入。敏感数据先脱敏。处理前先判断内容是否包含密钥、私密代码、用户隐私必要时用本地脚本预处理。商用或发布前做复核。AI 生成的结果要人工确认不能直接上线。14. 总结与下一步Claude Code 值得尝试的点很多但最关键的是它把“AI 编程助手”从单文件补全变成了真正的终端 Agent。安装好之后建议按这个顺序验证安装并初始化CLAUDE.md。跑一个真实小任务确认 Plan/Act 模式和 Diff 审查流程。接一个 MCP server验证工具调用链路。写一个 Skill把团队规范沉淀成可复用流程。给关键操作加 Hook做好安全护栏。最后再尝试/bg后台任务和-p批量模式。最容易踩的坑有三个MCP server 配置没生效就盲目让模型调用工具Hook 路径和事件名写错导致静默失败长对话不清理导致上下文耗尽、模型“失忆”。这三个问题都能通过本节给出的排查方式定位。后续可以继续扩展的方向包括把常用工作流固化为 Skill用 Boot 模式做每日例行任务把无头模式接入 CI 实现自动代码评审或者把设计稿平台通过 MCP 接入打通设计到代码的链路。这篇教程可以当作本地速查手册遇到功能点直接翻对应章节建议收藏备用。