Claude Code 深度使用指南：安装集成、权限模式、MCP、Skill 与 SubAgent 实战

摘要：本文全面解析Claude Code CLI工具，涵盖安装与IDE集成、内置命令与记忆系统、权限模式详解、MCP工具开发配置、Skill技能使用，以及SubAgent多代理协作机制。适合需要高效使用Claude Code进行开发的程序员。

前言：为什么Claude Code值得关注

去年我开始用Claude Code写代码时，最大的感受是：这不是一个简单的问答工具，而是一个真正能理解项目、操作文件、执行命令的开发助手。它能直接在终端里读我的代码、改我的代码、跑我的测试——不用切换窗口，不用复制粘贴。

但刚开始用时，很多功能不知道怎么用。MCP怎么配置？Skill怎么调用？SubAgent能做什么？这些概念文档里写得抽象，实际用起来摸索很久才明白。

这篇文章把我摸索出来的经验整理成一份完整指南，从安装到高级功能，帮你快速上手并深入使用Claude Code。

一、Claude Code 安装与集成

1. 安装方式

Claude Code 官方现在提供原生安装方式，也支持 npm 安装。日常开发建议优先看官方文档里的最新安装方式，因为二进制分发、平台支持和升级策略变化比较快。

macOS / Linux 常见安装方式：

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

npm 方式：

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

安装后验证：

  claude --version
  claude

如果你之前用 npm 装过，又遇到权限、二进制缺失或升级异常，可以先运行：

  claude doctor

claude doctor 比自己猜路径靠谱，尤其是本机同时存在 npm 版本、原生版本、IDE 插件内置版本的时候。

2. 登录与项目初始化

进入项目根目录后启动：

  cd your-project
  claude

Anthropic对账号管理严格，国内用户注册的Claude账号容易出现，使用国内IP登录触发风控或付费订阅后账号仍被封等问题，因此我们不得不另辟蹊径。

方案一：通过API Key方式使用

使用官方API Key，避免账号登录。获取API Key：

注册Anthropic Console账号（https://console.anthropic.com）
在API Keys页面创建新Key
注意：需要通过海外渠道获取API Key（如使用海外支付方式）

方案二：借助第三方平台

国内多数用户是无法直接使用海外支付的，我们也可以借助第三方平台，比如：https://api.laozhang.ai，https://api.yixia.ai

配置文件设置方法 

创建或编辑配置文件：

  # 用户设置 (全局)
  ~/.claude/settings.json
  
  # 项目设置 (项目级)
  .claude/settings.json

配置文件示例：

  {
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.laozhang.ai",
        "ANTHROPIC_AUTH_TOKEN": "sk-*************",
        "ANTHROPIC_MODEL": "claude-sonnet-4-6"
      }
  }

方案三：配置国内大模型

如果你不是一个claude code的狂热追求者，还是可以使用国内的大模型的，模型能力上是存在一些差距，但日常写点软文、写点业务代码，国内大模型还是可以胜任的，毕竟有着巨大的成本优势，最主要的是稳定。

配置文件设置方法 

这里以阿里云百炼为例，模型可以设置成百炼平台支持的任意模型

  {
    "env": {
      "ANTHROPIC_AUTH_TOKEN": "sk-**********",
      "ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/apps/anthropic",
      "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3-coder-flash",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3-coder-plus",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5",
      "ANTHROPIC_MODEL": "glm-5",
      "ANTHROPIC_REASONING_MODEL": "qwen3-max"
    },
    "includeCoAuthoredBy": false
  }

也可以利用cc-switch这个工具配置，其最终也是修改的~/.claude/settings.json这个配置文件。

配置key之后，再次进入claude，就不会提示登录了。第一次进入一个仓库，我通常会先跑：

  /init

它会生成或补充 CLAUDE.md，把项目结构、常用命令、测试方式、编码约定写成 Claude 每次会读取的上下文。这个文件建议提交到仓库，类似“给 AI 看的开发手册”。

一个可用的 CLAUDE.md 不需要长，关键是具体：

  # Project Notes
  
  - Package manager: pnpm. Do not use npm or yarn.
  - Frontend app: packages/web
  - Backend app: packages/api
  - Run unit tests with: pnpm test
  - Run type checks with: pnpm typecheck
  - Before changing database schema, update docs/schema.md.
  - Do not edit generated files under src/generated/.

这里不要写“请保持代码优雅”这类空话。Claude 看了也会点头，但没有可执行含义。写“用 pnpm，不要用 npm”就清楚得多。

3. VS Code 集成

Claude Code 可以在 VS Code 里直接使用。安装 Claude Code 扩展后，你会得到一个图形化面板，可以在编辑器旁边对话、引用文件、查看 diff、切换权限模式。

VS Code 里几个常用动作：

使用 @文件名 引用文件或目录。
选中代码后让 Claude 基于当前选区解释或修改。
在输入框底部切换权限模式。
用 / 打开命令菜单。
用 /mcp、/permissions、/memory 管理 MCP、权限和记忆。

如果你更喜欢终端界面，也可以在 VS Code 设置里让扩展使用 terminal mode。

4. JetBrains 集成

JetBrains 系列 IDE 可以安装 Claude Code 插件。安装后，从 IDE 内置终端运行：

  claude

如果你已经在外部终端启动了 Claude Code，可以在会话里执行：

  /ide

这样 Claude Code 能连接到当前 IDE，读取选中代码、诊断信息等上下文。对 Java、Kotlin、Go 这类重 IDE 项目，这个集成很有价值，因为语言服务的错误信息比单纯 grep 文件更准确。

二、Claude Code 内置命令与记忆

Claude Code 的 / 命令不是装饰品，它是日常工作流的控制面板。

1. 高频内置命令

下面这些命令基本每天都会用到：

我的习惯是：大任务先 /plan，改完先 /diff，提交前跑 /code-review。这三个命令能显著降低“它改了很多，但你没看清”的风险。

2. `CLAUDE.md`：写给 Claude 的项目说明书

Claude Code 每个新会话都是新的上下文窗口，但它会加载项目里的 CLAUDE.md。这就是最基础、最稳定的记忆机制。

适合写进 CLAUDE.md 的内容：

项目结构。
构建、测试、格式化命令。
包管理器约定。
代码风格。
不能改的目录。
数据库、鉴权、部署等关键约束。
团队希望 Claude 始终遵守的工作方式。

不适合写进 CLAUDE.md 的内容：

大段 API 文档。
临时任务说明。
一次性排查过程。
复杂流程清单。

如果一个内容越来越像“步骤”，它更适合放进 Skill。如果它只是“事实和规则”，才适合放进 CLAUDE.md。

3. `CLAUDE.local.md`：只属于你的个人偏好

团队共享规则放 CLAUDE.md。个人偏好放 CLAUDE.local.md，并加入 .gitignore。

例如：

  # Personal Preferences
  
  - 回答我时默认使用中文。
  - 修改代码前先说明将要改哪些文件。
  - 涉及数据库迁移时先给我风险点，不要直接执行迁移命令。

这类偏好不一定适合整个团队，但对个人体验很有用。

4. Auto Memory：让 Claude 记住被你纠正过的东西

Claude Code 还有自动记忆。你说“记住这个项目测试必须先启动 Redis”，它可以把这个经验写入本地 memory。下一次会话开始时，Claude 会加载这些记忆摘要。

要注意一点：记忆是上下文，不是强制策略。也就是说，CLAUDE.md 和 auto memory 会影响 Claude 的行为，但不能替代权限规则。如果某个文件绝不能读，应该用 Read deny；如果某类命令绝不能跑，应该用 Bash(...) deny。

三、Claude Code 权限模式

权限模式决定 Claude Code 调工具时要不要问你。用得好，它是安全带；用不好，它会让你在“频繁点确认”和“放飞代理”之间来回横跳。

1. 常见权限模式

生产代码仓库里，我不建议长期使用 bypassPermissions。它的确省事，但省掉的是最后一道人工确认。更稳的做法是：给常用只读命令、测试命令、格式化命令配置 allow，把危险命令配置 deny。

2. 权限规则：allow、ask、deny

权限规则通常写在 .claude/settings.json 或 ~/.claude/settings.json：

  {
    "permissions": {
      "allow": [
        "Bash(pnpm test *)",
        "Bash(pnpm typecheck)",
        "Bash(git status)",
        "Bash(git diff *)",
        "WebFetch(domain:docs.anthropic.com)"
      ],
      "deny": [
        "Bash(rm -rf *)",
        "Bash(git push *)",
        "Read(.env)",
        "Read(**/.env)",
        "Edit(src/generated/**)"
      ]
    }
  }

规则判断顺序是 deny、ask、allow。只要 deny 命中，其他地方 allow 也没用。

3. MCP 和 SubAgent 也能被权限控制

MCP 工具名一般长这样：

  mcp__github__list_issues
  mcp__database__query

你可以允许整个 MCP 服务：

  {
    "permissions": {
      "allow": [
        "mcp__github__*"
      ]
    }
  }

也可以只允许某个工具：

  {
    "permissions": {
      "allow": [
        "mcp__database__query"
      ]
    }
  }

SubAgent 同样能管：

  {
    "permissions": {
      "deny": [
        "Agent(Explore)"
      ]
    }
  }

这对团队很重要。不是每个代理都应该能访问数据库，也不是每个任务都应该能启动浏览器或调用外部系统。

四、Claude Code MCP 工具开发及配置

MCP，全称 Model Context Protocol，可以理解为“让 Claude Code 接入外部工具的标准协议”。数据库、GitHub、Jira、浏览器、内部 API、日志平台，都可以通过 MCP 暴露给 Claude Code。

1. MCP 适合解决什么问题

适合做 MCP 的能力通常有三个特点：

第一，Claude 需要拿到实时信息。比如查 GitHub issue、查数据库 schema、查线上日志。

第二，操作有明确边界。比如“只能查询，不能删除”“只能创建草稿，不直接发布”。

第三，团队希望能力可复用。与其每次把 curl 命令贴给 Claude，不如封成 MCP 工具，让工具描述、参数校验、权限规则都固定下来。

2. 配置一个 MCP 服务

Claude Code 支持 HTTP、SSE、stdio 等 MCP 连接方式。现在远程服务优先使用 HTTP；SSE 在不少场景里已经不推荐作为首选。

添加 HTTP MCP：

  claude mcp add --transport http github https://api.example.com/mcp

添加本地 stdio MCP：

  claude mcp add --transport stdio local-tools -- node ./mcp-server.js

带环境变量：

  claude mcp add --transport stdio --env API_KEY=your_key internal-api -- node ./server.js

查看和管理：

  claude mcp list
  claude mcp get internal-api
  claude mcp remove internal-api

在 Claude Code 会话里可以用：

  /mcp

3. MCP 配置作用域

Claude Code 的 MCP 配置有几个常用作用域：

团队项目里推荐把无密钥、可共享的 MCP 写进 .mcp.json：

  {
    "mcpServers": {
      "docs": {
        "type": "http",
        "url": "https://docs.example.com/mcp"
      },
      "local-tools": {
        "command": "node",
        "args": ["./tools/mcp-server.js"],
        "env": {
          "PROJECT_ROOT": "${CLAUDE_PROJECT_DIR:-.}"
        }
      }
    }
  }

密钥不要提交。用环境变量注入：

  {
    "mcpServers": {
      "internal-api": {
        "type": "http",
        "url": "${INTERNAL_API_BASE_URL}/mcp",
        "headers": {
          "Authorization": "Bearer ${INTERNAL_API_TOKEN}"
        }
      }
    }
  }

4. 开发一个最小 MCP 工具

下面用 TypeScript 写一个最小 MCP server：提供一个 get_project_info 工具，返回项目名称、当前目录和时间。真实项目里可以把它扩展成查数据库、读内部服务、生成脚手架。

安装依赖：

  npm init -y
  npm install @modelcontextprotocol/sdk zod
  npm install -D typescript tsx @types/node

src/server.ts：

  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: "project-helper",
    version: "1.0.0"
  });
  
  server.registerTool(
    "get_project_info",
    {
      title: "Get project info",
      description: "Return basic information about the current Claude Code project.",
      inputSchema: {
        includeEnv: z.boolean().optional().describe("Whether to include selected environment keys.")
      }
    },
    async ({ includeEnv = false }) => {
      const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
      const result: Record<string, unknown> = {
        projectDir,
        server: "project-helper",
        generatedAt: new Date().toISOString()
      };
  
      if (includeEnv) {
        result.env = {
          NODE_ENV: process.env.NODE_ENV,
          CLAUDE_PROJECT_DIR: process.env.CLAUDE_PROJECT_DIR
        };
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    }
  );
  
  const transport = new StdioServerTransport();
  await server.connect(transport);

package.json 增加：

  {
    "scripts": {
      "mcp": "tsx src/server.ts"
    }
  }

接入 Claude Code：

  claude mcp add --transport stdio project-helper -- npm run mcp

进入 Claude Code 后：

  /mcp

确认服务连接正常，再问：

  调用 project-helper 的 get_project_info，告诉我当前项目信息。

5. MCP 设计建议

写 MCP 工具时，别急着暴露“万能执行器”。越万能，越难控。更好的设计是：

工具名清楚，例如 search_logs、get_pull_request、query_readonly_database。
参数用 schema 约束，别让模型随便拼字符串。
默认只读，写操作拆成“生成草稿”和“确认提交”两步。
输出不要太大，必要时分页。
工具描述里写清楚“什么时候用、不能做什么”。
对高风险操作保留人工确认或二次审批。

MCP 的价值不只是“连工具”，而是把组织知识变成 Claude 可调用、可审计的接口。

五、Claude Code Skill 技能使用

Skill 是 Claude Code 里非常值得认真用的能力。简单讲，Skill 是一个带说明的工作流文件，Claude 可以在需要时自动加载，也可以由你用 /skill-name 手动调用。

1. Skill 和 CLAUDE.md 的区别

CLAUDE.md 适合放长期规则。Skill 适合放可复用流程。举个例子：

“项目使用 pnpm”放 CLAUDE.md。
“发布前检查版本号、CHANGELOG、测试结果、构建产物”放 Skill。
“Controller 不直接访问数据库”放 CLAUDE.md。
“帮我做一次 PR review，并按风险等级输出”放 Skill。

Skill 的好处是按需加载。长流程不会每次会话都占上下文。

2. 创建一个 Skill

个人 Skill 放这里：

  mkdir -p ~/.claude/skills/review-pr

项目 Skill 放这里：

  mkdir -p .claude/skills/review-pr

.claude/skills/review-pr/SKILL.md：

  ---
  description: Review the current git diff and produce a practical pull request review focused on bugs, tests, and  
  maintainability.
  allowed-tools:
    - Bash(git diff *)
    - Bash(git status)
  ---
  
  ## Task
  
  Review the current uncommitted changes.
  
  ## Steps
  
  1. Run `git status`.
  2. Run `git diff HEAD`.
  3. Identify behavioral bugs, missing tests, risky refactors, and unclear naming.
  4. Output findings first, ordered by severity.
  5. If there are no blocking issues, say so clearly.
  
  ## Output format
  
  - Findings
  - Test gaps
  - Suggested commit message

调用：

  /review-pr

也可以直接说：

  帮我 review 当前改动，重点看有没有行为回归。

只要 description 写得清楚，Claude 就可能自动选择这个 Skill。

3. Skill 支持辅助文件

Skill 可以是一个目录，不只有 SKILL.md：

  .claude/skills/release-check/
  ├── SKILL.md
  ├── checklist.md
  ├── templates/
  │   └── release-note.md
  └── scripts/
      └── verify-release.sh

SKILL.md 里可以引用这些文件，让复杂流程保持整洁：

  ---
  description: Run the release checklist and prepare release notes.
  ---
  
  Follow @checklist.md.
  Use @templates/release-note.md as the release note format.
  Run @scripts/verify-release.sh if the user asks for verification.

4. Skill 的工具权限

Skill 可以在 frontmatter 里声明 allowed-tools，让相关工具在 Skill 活跃时少弹确认。例子：

  ---
  description: Generate a database migration review.
  allowed-tools:
    - Bash(git diff db/migrations/*)
    - Read(db/schema.sql)
  ---

但要记住：不要为了方便给 Skill 开太大权限。一个发布 Skill 如果直接允许 Bash(kubectl *)，迟早会让人心里发毛。更好的做法是让它生成命令和检查清单，真正执行时再确认。

5. Skill 运行在 SubAgent 中

如果某个 Skill 会占用很多上下文，比如“扫描整个仓库找潜在性能问题”，可以让它在隔离上下文中运行：

  ---
  description: Explore performance hotspots without polluting the main conversation.
  context: fork
  ---
  
  Explore the repository for likely performance bottlenecks.
  Return only a concise report with file paths, reasons, and suggested next steps.

这时主会话不会被大量搜索细节污染，只拿到 SubAgent 汇总结果。这个体验很像让同事去旁边查资料，最后回来讲重点。

六、Claude Code SubAgent

SubAgent 是 Claude Code 从“一个助手”走向“一个小团队”的关键能力。它可以有自己的系统提示词、模型、工具、权限和记忆，用来承担某类稳定角色。

1. SubAgent 适合什么场景

适合做 SubAgent 的任务：

代码审查。
安全审查。
测试补全。
文档整理。
大仓库探索。
迁移方案设计。
专门查日志或查数据库。

不适合做 SubAgent 的任务：

只需要一句回答的小问题。
需要你实时盯着每一步的高风险操作。
边界还不清楚的临时探索。

2. 创建一个代码审查 SubAgent

项目级 SubAgent 放在：

  .claude/agents/code-reviewer.md

示例：

  ---
  name: code-reviewer
  description: Use this agent to review code changes for bugs, regressions, missing tests, and maintainability risks.
  model: sonnet
  tools:
    - Read
    - Grep
    - Glob
    - Bash(git diff *)
    - Bash(git status)
  permissionMode: default
  color: blue
  ---
  
  You are a pragmatic senior code reviewer.
  
  Focus on concrete findings:
  - behavioral bugs
  - security issues
  - missing tests
  - compatibility risks
  - confusing or fragile implementation
  
  Do not rewrite the code unless asked.
  Put findings first, ordered by severity.
  Use file paths and line references when possible.
  If no serious issues are found, say that directly and mention residual risk.

使用方式：

  请用 code-reviewer 审查当前改动。

也可以让 Claude 自己判断是否调用：

  提交前帮我看一下这次改动有没有明显风险。

3. 创建一个只读探索 SubAgent

大仓库里，我很喜欢配一个只读探索代理。它不能改文件，只负责找信息。

.claude/agents/explorer.md：

  ---
  name: explorer
  description: Use this agent to inspect the repository, trace code paths, and answer architecture questions without modifying files.
  model: haiku
  tools:
    - Read
    - Grep
    - Glob
    - Bash(git grep *)
    - Bash(find *)
  permissionMode: plan
  color: cyan
  ---
  
  You investigate the codebase without editing files.
  
  Return:
  1. the shortest explanation that answers the question
  2. the most relevant files
  3. any uncertainty or missing context
  
  Do not make changes.
  Do not run write commands.

这种代理可以用更快的模型，成本低、速度快，而且不会把主会话弄得很长。

4. SubAgent 和 Skill 怎么搭配

一个简单判断：

Skill 是“流程”。
SubAgent 是“角色”。
MCP 是“工具”。
CLAUDE.md 是“长期背景”。
权限是“边界”。

比如你要做一次发布：

release-manager SubAgent 负责发布视角。
/release-check Skill 负责发布流程。
MCP 查询 CI、GitHub、包仓库状态。
权限规则禁止直接生产发布，只允许生成发布命令和草稿。

这套组合比一句“帮我发布”可靠得多。

5. SubAgent 的权限别偷懒

SubAgent 默认很容易被写成“什么都能做”。刚开始省事，后面麻烦。建议按角色收窄：

review agent：只读 + git diff。
test agent：允许跑测试，但不允许改发布配置。
docs agent：允许改 docs，不允许改 src。
database agent：只允许只读查询，不允许 DDL / DML。
release agent：允许生成命令，不自动执行生产变更。

Claude Code 的强大来自代理能行动；工程上的可靠也来自你知道它不能做什么。

七、推荐的一套团队落地结构

一个中大型项目可以这样组织：

  your-project/
  ├── CLAUDE.md
  ├── CLAUDE.local.md              # gitignored
  ├── .mcp.json
  ├── .claude/
  │   ├── settings.json
  │   ├── agents/
  │   │   ├── code-reviewer.md
  │   │   ├── explorer.md
  │   │   └── test-writer.md
  │   └── skills/
  │       ├── review-pr/
  │       │   └── SKILL.md
  │       ├── release-check/
  │       │   ├── SKILL.md
  │       │   └── checklist.md
  │       └── migration-review/
  │           └── SKILL.md
  └── tools/
      └── mcp-server/
          ├── package.json
          └── src/server.ts

团队协作时，建议把这些文件纳入 code review：

CLAUDE.md
.claude/settings.json
.claude/agents/*.md
.claude/skills/**/SKILL.md
.mcp.json

原因很简单：这些文件会影响 Claude 怎么读代码、怎么改代码、能调用什么工具。它们本质上已经是工程配置的一部分，不是个人笔记。

八、一些真实的使用建议

第一，不要一上来就让 Claude Code “重构整个项目”。先让它读、解释、列计划。你会很快看出它是否理解了边界。

第二，尽量让任务可验证。比如“修复登录 bug”不如“复现登录失败，添加回归测试，然后让测试通过”。

第三，少给大而空的目标，多给约束。Claude Code 对“不要改公共 API”“保留兼容性”“只改 service 层”这类约束响应更稳定。

第四，认真维护 CLAUDE.md。它不是摆设。你每次纠正 Claude 的重复错误，都应该考虑是否把规则沉淀进去。

第五，把危险能力交给权限系统，不要只交给提示词。提示词是方向盘，权限才是刹车。

第六，MCP 工具从只读开始。等团队信任工具输出、权限边界和日志审计后，再考虑写操作。

第七，让 SubAgent 做“窄角色”。一个优秀的 review agent，比一个什么都能干的万能 agent 更好用。

结语：Claude Code 真正改变的是工作接口

Claude Code 不是简单把聊天窗口搬进终端。它把“读代码、改文件、跑命令、接工具、记住项目习惯、分派子任务”放在了一套统一接口里。

用得浅，它是一个能写代码的聊天助手；

用得深，它会变成团队里的自动化开发层：有项目记忆，有工具边界，有专门技能，有不同角色的代理，还能通过 MCP 接进公司已有系统。

但越是自动化，越要工程化。安装和命令只是开始；真正决定体验上限的，是你怎样设计记忆、权限、MCP、Skill 和 SubAgent。把这些东西搭好，Claude Code 才会从“偶尔惊艳”变成“稳定可用”。

参考资料

Claude Code 官方文档

分享