一、什么是Claude Code？

Claude Code​ 是 Anthropic（Claude 的开发商）推出的终端（Terminal）原生 AI 编程助手。它不仅仅是代码补全，更是一个能读懂你整个项目、帮你自动执行命令的“Agent”（智能体）

二、Claude Code和Cursor的区别

Cursor 是“带 AI 的编辑器”（副驾驶），Claude Code 是“会写代码的终端 Agent”（代驾），用 Cursor​ 写日常业务逻辑，用 Claude Code​ 处理批量任务（如全库升级、自动生成 API 层）

维度	Cursor​	Claude Code​
本质​	基于 VS Code 的 IDE（图形界面）	命令行智能体（CLI，无界面）
工作模式​	人机协作：你写代码，AI 辅助补全、解释、局部重构	Agent 代理：你下指令，AI 自动读文件、改代码、跑命令
擅长场景​	日常编码、快速原型、代码库问答	大型重构、多文件修改、自动化脚本
交互方式​	图形界面、快捷键、侧边栏聊天	终端命令行、自然语言对话
学习成本	低，开箱即用	中，需要学习指令

三、安装前准备

1、 Claude 账号

Claude 账号：确保拥有有效的 Anthropic Claude 账号，访问 claude.ai 注册一个账号

2、 命令行工具

macOS/Linux：系统自带终端（Terminal/iTerm2）

Windows：推荐使用 PowerShell（管理员权限）或 WSL2（Ubuntu）

Node.js：部分安装方式需要（如 npm）

四、终端安装/卸载Claude Code

1、macOS、Linux、WSL

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

// 卸载
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

2、Windows PowerShell

// 安装
irm https://claude.ai/install.ps1 | iex

// 卸载
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

3、Windows CMD

// 安装
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

// 卸载
del /f /q "%USERPROFILE%\.local\bin\claude.exe"
rmdir /s /q "%USERPROFILE%\.local\share\claude"

4、Homebrew

// 安装
brew install --cask claude-code

// 卸载
brew uninstall --cask claude-code

5、WinGet

// 安装
winget install Anthropic.ClaudeCode

// 卸载
winget uninstall Anthropic.ClaudeCode

6、使用 npm 安装

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

// 卸载
npm uninstall -g @anthropic-ai/claude-code

7、验证安装是否成功

终端输入 claude --version，输出版本号即成功

五、VS Code 安装 Claude Code

如果不喜欢使用 Claude Code 的命令行，我们可以在 VS Code 编辑器中安装 Claude Code

六、首次配置（登录与鉴权）

# 启动登录流程
claude auth login

# 按提示在浏览器中完成 OAuth 授权
# 授权后，检查状态
claude auth status

常见问题：

• 权限错误：Windows 下若提示执行策略限制，运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

• 网络问题：若在国内环境，确保网络能正常访问 Anthropic 服务

七、内置核心前缀

在 claude交互式会话中，这些前缀是高效操作的关键，这些符号直接打在输入框里，Claude 会自动识别并切换模式

前缀	模式	作用与示例	本质
/​	Command （命令模式）	执行内置或自定义操作。 例：/review（代码审查）、/model opus（切换模型）	调用 CLI 功能
@​	Context （上下文注入）	引用文件/目录/代码，将其内容作为上下文附加到消息中。 例：@src/main.py @README.md	文件级 RAG
!​	Bash （执行模式）	直接运行终端命令，stdout/stderr 自动注入上下文。 例：!npm install、!git log -3	终端代理
#​	Memory （记忆写入）	将内容持久化写入 CLAUDE.md（项目记忆），跨会话生效。 例：# 项目编码规范：使用 TypeScript	长期记忆
&​	Async （异步任务）	后台/云端异步执行，不阻塞当前会话，可在 web 端查看进度。	后台任务
\+ Enter​	Multiline （多行输入）	换行不发送，用于编写长需求描述（一次性写完发送）。	编辑模式
(无)​	Natural Language （自然语言）	普通对话，Claude 会结合当前上下文进行推理和回复。	默认模式

八、基本命令

1. 基础会话与管道

命令	作用	示例
claude	启动交互式会话	claude
claude "xxx"	带初始提示启动	claude "帮我重构这个项目"
claude -p "xxx"	非交互模式（跑完即退出，适合脚本）	claude -p "检查src/目录下的类型错误"
cat file | claude -p	管道输入（分析日志/文件）	cat error.log | claude -p "分析错误"
claude -c	继续当前目录的最近对话	claude -c
claude -r <id/name>	恢复特定会话（按ID或名称）	claude -r "auth-refactor"
claude --from-pr <PR>	恢复链接到 GitHub PR 的会话	claude --from-pr 123

2. 账户与版本管理

命令	作用	示例
claude auth login	登录账户	claude auth login --email user@xx.com
claude auth logout	登出账户	claude auth logout
claude auth status	查看认证状态	claude auth status --text
claude update	更新 CLI 版本	claude update
claude --version	查看版本	claude -v
claude setup-token	生成 CI/脚本用的长期 OAuth Token	claude setup-token

3. 高级配置与扩展

命令	作用	示例
claude agents	列出所有已配置的 subagents	claude agents
claude mcp	配置 Model Context Protocol (MCP) 服务器	claude mcp list
claude plugin	管理插件（安装/卸载）	claude plugin install code-review
claude remote-control	启动远程控制服务器（供 Claude.ai 控制）	claude remote-control --name "My Project"
claude auto-mode defaults	打印内置自动模式规则（JSON）	claude auto-mode defaults

4. 关键启动参数（Flags）

参数	作用	示例
--add-dir <path>	添加额外工作目录（跨项目访问）	claude --add-dir ../shared-lib
--worktree <name>	在隔离的 git worktree 中启动	claude -w feature-auth
--model <name>	指定模型（如 sonnet, opus）	claude --model opus
--effort <level>	设置推理努力级别（low/medium/high/max）	claude --effort high
--tools <list>	限制可用工具（如 Bash,Edit,Read）	claude --tools "Bash,Edit"
--dangerously-skip-permissions	跳过所有权限提示（慎用）	claude --dangerously-skip-permissions
--system-prompt-file	从文件加载自定义系统提示	claude --system-prompt-file ./rules.txt
--output-format json	输出为 JSON（用于脚本解析）	claude -p --output-format json "query"

九、斜杠命令（交互式会话内使用）

在 claude进入交互界面后，输入 /查看所有可用命令。

1. 会话与上下文管理

命令	作用	示例
/clear	清空对话历史（释放上下文）	/clear
/exit	退出会话	/exit
/resume <session>	恢复指定会话（列表选择）	/resume
/rename <name>	重命名当前会话	/rename auth-refactor
/fork	创建当前对话的分支	/fork
/export	导出对话为文本文件	/export log.txt
/compact	压缩对话（节省 Token）	/compact

2. 模型与配置

命令	作用	示例
/model <name>	切换模型（如 sonnet, opus）	/model opus
/effort <level>	设置推理努力级别	/effort high
/config	打开设置界面（主题/模型/输出样式）	/config
/permissions	管理工具权限（允许/拒绝规则）	/permissions
/memory	编辑项目记忆文件（CLAUDE.md）	/memory

3. 代码与工程操作（Skills）

命令	作用	示例
/batch <instruction>	批量重构：将大改动分解为并行任务	/batch migrate to TypeScript
/debug	开启调试日志，分析会话问题	/debug
/diff	查看未提交的代码差异（Git）	/diff
/plan <desc>	直接进入“计划模式”	/plan fix the auth bug
/review	代码审查（需安装插件）	/review
/security-review	分析当前分支的安全漏洞	/security-review

4. 工具与诊断

命令	作用	示例
/doctor	诊断安装和设置问题	/doctor
/cost	显示 Token 使用统计	/cost
/context	可视化上下文使用情况（Token 分布）	/context
/copy <N>	复制第 N 条回复到剪贴板	/copy 2
/ide	管理 IDE 集成状态	/ide
/mcp	管理 MCP 服务器连接	/mcp

十、交互模式

Claude Code 的交互模式（Ask / Plan / Edit）决定了 AI 在任务中是“动口”还是“动手”。这其实是一个从分析到规划再到执行的渐进式协作流程。

模式	角色定位	核心行为	适用场景	典型指令示例
Ask (询问)	代码侦探 （只读分析）	✅ 读代码、解释逻辑 ❌ 不改文件 ❌ 不跑命令	• 刚接手新项目 • 看不懂代码逻辑 • 定位 Bug 原因 • 不确定要不要改	帮我看看这个函数是干嘛的 为什么这里会报空指针？
Plan (规划)	架构师 （出方案）	✅ 拆解步骤、评估风险 ❌ 不改文件（仅输出 TODO） ❌ 不跑命令	• 新增核心功能模块 • 重构复杂业务 • 涉及多文件改动 • 引入新技术栈	计划一下怎么加缓存 重构这个模块的步骤是什么？
Edit (编辑)	执行者 （写代码）	✅ 生成​ Diff（代码差异） ✅ 修改文件（需你确认） ⚠️ 可能请求执行命令	• Bug 修复（知道怎么改） • 代码优化（目标明确） • 按 Plan 方案落地	修复这个登录逻辑的 Bug 把接口返回值改成标准格式

1、模式切换与触发

自动判断：在终端中，你不需要手动输入模式命令，Claude 会根据你的 Prompt（指令内容）​ 自动判断进入哪种模式

• 指令含糊（如“这是干嘛的”）→ 进入 Ask

• 指令涉及复杂改动（如“怎么重构”）→ 进入 Plan

• 指令明确具体（如“修这个 Bug”）→ 进入 Edit

手动切换：如果是在 VS Code 插件打开claude code，可以通过点击状态栏的按钮手动切换模式

十一、CLAUDE.md 使用指南

CLAUDE.md 是 Claude Code 的 “项目记忆文件”，你可以把它理解为写给 AI 的 “新员工入职手册”。告诉它这个项目是什么、遵循什么规范、有哪些注意事项，让它每次都能以符合项目要求的方式工作，而不是每次对话都重新解释

1、存放位置

位置	路径	作用范围	是否提交 git	优先级
项目根目录	{项目根目录}/CLAUDE.md	当前项目所有会话	✅ 推荐提交，团队共享	高
项目本地	{项目根目录}/.claude/CLAUDE.md	当前项目所有会话	❌ 加入 .gitignore，仅个人使用	最高
子目录	{任意子目录}/CLAUDE.md	Claude 打开该目录下的文件时自动加载	✅ 适合多模块仓库	中
全局用户级	~/.claude/CLAUDE.md	当前用户的所有项目	❌ 个人配置，不提交	低

2、文件内容结构

CLAUDE.md 是一个普通的 Markdown 文件，没有强制的格式要求，但良好的结构能帮助 Claude 更快找到关键信息。一个高效的 CLAUDE.md通常包含以下模块

# 项目名称

## 项目概述
- **一句话定位**：这是什么类型的应用（如：Next.js 电商后台）。
- **核心业务逻辑**：关键流程（如：用户下单 -> 扣库存 -> 发消息）。

## 技术栈 (Tech Stack)
- **前端**：React 18 + TypeScript + Tailwind
- **后端**：Node.js + Express
- **数据库**：PostgreSQL
- **包管理器**：`pnpm`（**必须明确指定**，避免混用 npm/yarn）

## 目录结构 (Structure)
- `src/app/`：页面路由
- `src/components/ui/`：通用 UI 组件
- `src/lib/`：工具函数（**禁止**在组件中写裸逻辑）
- `legacy/`：**此目录代码只读，禁止重构**

## 开发规范 (Rules)
- **代码风格**：使用 2 空格缩进；组件必须用 `const` 函数式写法。
- **提交规范**：Commit 信息遵循 Conventional Commits。
- **安全红线**：**禁止**提交任何硬编码的 API Key 或密码。

## 常用命令 (Scripts)
- 启动：`pnpm dev`
- 测试：`pnpm test:watch`
- 构建：`pnpm build`

## 注意事项

3、自动生成

在项目根目录运行：

claude -p "/init"

Claude 会自动分析你的 package.json和代码结构，生成一个基础版的 CLAUDE.md草案，你只需微调即可

4、路径限定规则（精准控制）

在 .claude/rules/目录下，你可以创建针对特定文件类型的规则。例如创建 api-rules.md，只有当 Claude 处理 src/api/下的文件时，这些规则才会被激活，节省上下文 Token

---
paths: ["src/api/**/*.ts"]
---
# API 层专属规则
- 所有端点必须包含输入验证（Zod）。
- 错误响应必须使用统一格式。

5、导入外部文档

你可以在 CLAUDE.md中直接@引用现有的项目文档，避免重复编写

# 项目说明
- 架构设计请参考 @docs/architecture.md
- 可用脚本见 @package.json

十二、自动记忆Auto Memory

Auto Memory（自动记忆）是 Claude Code 的 “智能笔记本”。它让 Claude 能自动记住你在项目中摸索出的经验（如构建命令、调试技巧），并在下次会话中自动回忆，无需你反复解释。

它与 CLAUDE.md是互补关系，CLAUDE.md是你写的“宪法”，Auto Memory​是 Claude 写的“日记”

1、自动记忆 和 CLAUDE.md区别

维度	CLAUDE.md（你写的）	Auto Memory（Claude 写的）
作者​	开发者（你/团队）	Claude（AI）
内容​	项目架构、硬性规范、脚本	调试经验、你的偏好、有效命令、架构决策
共享性​	提交到 Git，团队共享​	存储在本地 ~/.claude/，仅本人可见​
控制力​	主动、精确（你说了算）	被动、学习型（AI 判断）
典型场景​	“必须用 pnpm install”	“上次解决这个报错是用 --force参数”

2、查看与编辑

输入 /memory 会打开一个记忆管理面板，你可以进行以下操作

操作	说明	用途
查看列表​	显示所有已加载的 CLAUDE.md和 Auto Memory 文件	确认 Claude 当前“记住”了什么
编辑文件​	选择任意文件（如 MEMORY.md），会在默认编辑器中打开	直接删除错误记忆或补充细节
开关功能​	一键开启或关闭当前项目的 Auto Memory	临时禁用自动记录（如调试敏感代码时）
打开目录​	直接跳转到 ~/.claude/projects/.../memory/文件夹	进行批量文件管理

十三、配置外部工具（MCP）

Model Context Protocol（模型上下文协议），MCP = AI 的"万能接口"，让 Cursor 连接外部工具/数据源（如浏览器、数据库、接口平台，团队文档、查 GitHub等），扩展 AI 能力，不只局限本地代码。它的核心价值是把 “只会聊天的模型” 变成 “能调用真实工具和数据的助手”

1、通过文件配置MCP

作用域	配置文件路径	适用场景
全局 (User)​	~/.claude.json或 ~/.claude/settings.json	个人常用工具（如 GitHub、数据库），所有项目通用
项目 (Project)​	项目根目录/.mcp.json	团队共享（推荐提交 Git），如项目统一的文件系统权限
本地 (Local)​	~/.claude.json中的 projects字段	仅当前项目可用，私密配置（如个人 API Key）

{
  "mcpServers": {
    "project-fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
    }
  }
}

2、通过命令配置MCP

claude mcp add <插件名> -- <启动命令>

--必须加：这是分隔符，告诉终端“后面是插件自己的命令”
作用域范围：用 -s user（全局）或 -s project（仅当前项目）控制插件生效范围

范围	用途	配置命令示例	优先级
-s local（默认）	仅当前项目可用，私密配置（如敏感密钥）	claude mcp add -s local ...	高
-s project（仅当前项目）	团队共享（存储在.mcp.json，可提交版本库）	claude mcp add -s project ...	中
-s user（全局）	所有项目可用（个人全局配置）	claude mcp add - user ...	低

3、常用命令

命令	作用
claude mcp add	添加一个 MCP
claude mcp list	查看所有已配置MCP
claude mcp get <name>	查看某个MCP详情
claude mcp remove <name>	删除MCP
/mcp	在 Claude Code 中查看MCP状态

4、示例

插件	作用	安装命令
文件系统​	读写、管理本地文件（基础必装）	claude mcp add fs -s user -- npx -y @modelcontextprotocol/server-filesystem ~/你的项目路径
GitHub​	管理 Issue、PR、仓库	claude mcp add gh -s user -- npx -y @modelcontextprotocol/server-github
数据库​	查询、分析 SQLite/MySQL	claude mcp add db -s project -- npx -y @modelcontextprotocol/server-sqlite ./data.db
浏览器​	自动化测试、截图 (Playwright)	claude mcp add pw -s user -- npx -y @executeautomation/playwright-mcp-server

十四、配置子代理（Subagents）

Claude Code 的 Subagents（子代理）​ 功能，本质上就是给 Claude 组建一个“专家团队”。主 Claude 是“项目经理”，负责统筹；子代理是“技术专家”，负责处理特定任务

1、子代理是什么？

主代理（Main Claude）：你平时直接对话的那个，负责核心业务逻辑和决策

子代理（Subagent）：你专门“招聘”的特长生（如代码审查员、测试工程师、日志分析师）

• 独立办公：它有自己独立的“办公室”（独立上下文），干活产生的中间过程（如搜索记录、日志）不会污染你的主聊天窗口

• 专精一事：只做一件事（如只查 Bug、只写测试），行为更可控

• 自动派单：设置好后，Claude 遇到特定问题会自动派发给对应的专家处理

2、内置子代理

名称	职责	特点
Explore​	代码库探索、搜索	使用 Haiku 模型，只读，速度快，专门帮你找代码。
Plan​	制定计划前的调研	在“计划模式”下自动运行，收集项目上下文。
General-purpose​	复杂多步骤任务	继承主对话权限，适合需要“边看边改”的复杂重构。

3、命令行创建子代理

在 Claude Code 聊天框输入 /agents，会打开可视化界面，按提示填写字段（和子代理文件字段一致）：

字段	是否必填	说明
name	必填	代理的唯一标识，也是显式调用时的名称。命名格式必须为小写字母加连字符，例如 code-reviewer。
description	必填	决定 Claude 是否以及何时自动调用该代理的核心字段。务必详细、清晰地描述该代理的具体使用场景、触发条件和预期行为。
tools	可选	工具白名单。设置此项后，该代理只能使用列出的工具，未列出的工具（包括 MCP 工具）将被排除，无法调用。
disallowedTools	可选	工具黑名单。该代理会继承主对话的全部可用工具，但会自动排除列出的工具（注意：MCP 工具不受此限制，默认保留）。
model	可选	指定该代理使用的模型。可填写 haiku、sonnet、opus或完整的模型 ID。默认为 inherit，表示继承主对话的模型设置。
permissionMode	可选	控制代理的权限行为模式
memory	可选	定义代理的持久记忆范围。可选值为 user（用户级）、project（项目级）或 local（本地级）。
background	可选	布尔值。设为 true时，该代理将在后台运行，执行任务时不阻塞主对话的继续交互。
isolation	可选	运行环境隔离设置。设为 worktree时，代理将在临时的 git worktree 中运行，与主仓库代码库完全隔离，避免污染主分支。
skills	可选	在该代理启动时自动加载的 Skills 列表。用于预置代理具备的特定能力或上下文。
hooks	可选	生命周期钩子函数配置。允许在特定事件发生时插入自定义逻辑，支持的事件包括 SubagentStart、SubagentStop、PreToolUse、PostToolUse。

4、手动创建子代理文件

存放位置	作用范围	优先级
CLI --agents 标志	仅当前会话	最高
.claude/agents/	当前项目	高
~/.claude/agents/	所有项目（全局）	中
插件 agents	插件作用域	最低

---
name: 代码审查员
description: 专门审查代码质量和安全漏洞
tools: ["Read", "Grep"]  # 只给读权限
model: sonnet
---
你是一个严格的代码审查员，只关注代码坏味和安全问题...

5、tools 与 disallowedTools 的区别

配置方式	行为	典型场景
两者均不设置	继承主对话全部工具，含 MCP 工具	通用代理，不需要限制
仅设置 tools	只能使用白名单内的工具，MCP 工具被排除	只读分析代理、严格约束场景
仅设置 disallowedTools	继承全部工具，排除黑名单工具，MCP 工具保留	保留 MCP 能力但禁止写操作
两者同时设置	先应用 disallowedTools，再从剩余工具中按 tools 筛选	精细控制工具访问

6、权限行为模式permissionMode 

模式	行为	适用场景
default	正常权限提示，每次操作前询问用户	通用场景，推荐默认值
acceptEdits	自动接受文件编辑，无需每次确认	频繁改动文件的代理，减少交互中断
dontAsk	自动拒绝未授权操作，不中断执行流程	严格只读场景，操作失败时静默跳过
bypassPermissions	跳过所有权限检查，直接执行	仅限完全可信、受控的自动化环境
plan	只读规划模式，不执行任何写操作	方案制定、架构分析

7、生命周期钩子（Hooks）

钩子事件	触发时机	典型用途
SubagentStart	子代理启动时	记录启动日志、初始化环境
SubagentStop	子代理任务完成时	记录结果、触发下游任务、发送通知。包含 agent_id 和 agent_transcript_path 字段
PreToolUse	工具调用前	校验操作合法性，脚本退出码为 2 时可阻止该工具调用
PostToolUse	工具调用后	格式化输出、生成变更记录

十五、配置技能（Skills）

Skill 可复用的"AI 操作手册" — 把特定领域的知识、工作流程打包成独立模块，让 AI 在需要时自动调用，目标是让同类任务更稳定、更统一，而不是每次都从零解释。比如 Vue3 功能开发、代码评审、生成 commit message等

Skill触发方式通常是你的需求命中该 Skill 的描述关键词，Agent 会自动读取并按规范执行。

1、Skill 文件格式

每个 Skill 是一个文件夹，一个完整的技能文件夹可能包含以下内容，核心是 SKILL.md 文件

<skill-name>/       # 文件夹名称需与SKILL.md中定义的name一致
├── SKILL.md        # 必需：技能的主文件
├── reference.md    # 可选：详细说明
├── examples.md     # 可选：示例
├── scripts/        # 可选：脚本
└── assets/         # 可选：静态资源

一个标准的SKILL.md文件由两部分组成（frontmatter元数据和skill内容主体）

Frontmatter 元数据：位于文件最顶部，用 --- 包裹，用于定义技能的核心属性

字段	必填	说明
name	否	Skill 显示名称，默认使用目录名，仅支持小写字母、数字和短横线（最长 64 字符）
description	推荐	技能用途及使用场景，Claude 根据它判断是否自动应用
argument-hint	否	自动补全时显示的参数提示，如 [issue-number]、[filename] [format]
disable-model-invocation	否	设为 true 禁止 Claude 自动触发，仅能手动 /name 调用（默认 false）
user-invocable	否	设为 false 从 / 菜单隐藏，作为后台增强能力使用（默认 true）
allowed-tools	否	Skill 激活时 Claude 可无授权使用的工具
model	否	Skill 激活时使用的模型
context	否	设为 fork 时在子代理上下文中运行
agent	否	子代理类型（配合 context: fork 使用）
hooks	否	技能生命周期钩子配置

Markdown 主体：Frontmatter 之后的部分，用 Markdown 编写具体的操作指南、规范、步骤和示例。为了让AI高效理解，建议指令清晰、多用示例、避免解释基础概念

---
name: "技能名称"
description: "一句话描述，AI根据此描述来判断何时触发该SKILL"
---
 
# 技能标题
 
## 何时使用
- 场景1
- 场景2
 
## 执行步骤
1. 步骤1
2. 步骤2
 
## 规则约束
- 规则1
- 规则2
 
## 质量检查清单
- 检查项1
- 检查项2

Skills 支持在内容中插入动态变量

变量	说明
$ARGUMENTS	调用 Skill 时传入的所有参数
$ARGUMENTS[N]	按索引访问参数，如 $ARGUMENTS[0]
$N	简写方式，如 $0 表示第一个参数
${CLAUDE_SESSION_ID}	当前会话 ID，用于日志、临时文件、关联输出

2、Skill 存放位置

用域	文件路径	优先级	适用场景
项目级​	项目根目录/.claude/skills/<skill-name>/SKILL.md	最高​	团队协作首选。技能文件与项目代码一起提交到 Git 仓库，确保团队所有成员使用完全一致的技能定义，如项目特有的代码规范、部署流程。
用户级​	~/.claude/skills/<skill-name>/SKILL.md	次高	个人偏好与全局工具。存放开发者个人常用的、跨项目的技能，如个人代码风格检查、通用调试脚本。不在团队间共享。
插件市场​	~/.claude/plugins/marketplaces/<source>/skills/	动态加载	扩展生态。通过 claude plugins命令安装的第三方技能集，会下载到此目录。调用时需指定插件源和技能名，如 /document-skills:pptx。

十六、配置插件（Plugin）

Claude Code 的 Plugin（插件），本质上是“能力全家桶”。它把零散的 Skills（技能）、Subagents（子代理）、MCP（外部工具）打包成一个可安装、可版本化、可团队共享的扩展包

1、Plugin 与本地配置的区别

维度	项目本地配置 (.claude/)	Plugin (插件)
复用性​	仅限本项目/本机	跨项目、跨团队共享​
管理​	手动复制粘贴	版本控制、一键安装​
来源​	自己写	官方市场、团队私有仓库
场景​	实验阶段、个人偏好	稳定后打包分发

2、Plugin文件格式

my-plugin/
├── .claude-plugin/
│   └── plugin.json     # 插件清单（必需）
├── commands/           # 斜杠命令
├── agents/             # 子代理
├── skills/             # Skills
├── hooks/              # 钩子
├── .mcp.json           # MCP 配置
└── .lsp.json           # LSP 配置

关键文件：插件清单（plugin.json）

{
  "name": "my-first-plugin", // 插件名称：唯一标识 + 命令命名空间
  "description": "A greeting plugin to learn the basics",  // 描述：插件市场中展示
  "version": "1.0.0", 、// 版本：语义化版本控制
  "author": { "name": "Your Name" } // 作者信息：可选，归属说明
}

3、推送自定义plugin到GitHub

将你的插件文件夹（包含 .claude-plugin/plugin.json）初始化为一个 Git 仓库，并推送到 GitHub

cd my-plugin
git init
git add .
git commit -m "feat: first release"
git branch -M main
git remote add origin https://github.com/yourname/my-plugin.git
git push -u origin main

团队成员或用户通过以下命令安装

# 安装最新版（main分支）
claude plugin install https://github.com/yourname/my-plugin.git

4、使用插件市场的plugin

1. 添加插件市场（应用商店）

# 注册一个插件源（如官方市场或公司内网仓库）
claude plugins add my-market --url https://github.com/company/claude-plugins

2. 安装插件（下载应用）

# 从指定市场安装插件
claude plugins install code-review-toolkit@my-market

3. 使用

安装后，插件内的 Skills 会自动生效，Commands 会出现在斜杠命令中

5、插件管理常用命令

命令	作用	用法示例	说明
/plugin​	打开插件管理器​	在聊天框输入 /plugin，然后回车。	这是一个交互式界面 (TUI)，您可以用方向键浏览官方/团队市场的插件列表，查看详情，并选择安装。
/plugin install​	安装插件​	/plugin install code-review /plugin install https://github.com/owner/repo.git	可以直接从已添加的市场中按名称安装，也可以通过 GitHub 仓库 URL 安装。支持指定版本，如 code-review@v1.2。
/plugin uninstall​	卸载插件​	/plugin uninstall code-review	从您的环境中移除指定插件。文档未提及等效的 remove和 rm写法，但为保持一致性，claude plugin命令行工具支持这两种写法。​
/plugin enable​	启用插件​	/plugin enable code-review	开启一个已被禁用的插件，使其功能重新可用。
/plugin disable​	禁用插件​	/plugin disable code-review	临时关闭一个插件的功能，但不会卸载它，可以随时重新启用。
/plugin marketplace add​	添加市场源​	/plugin marketplace add my-market --url https://github.com/company/claude-plugins	添加一个自定义的插件市场（如公司内网仓库），之后就可以从这个市场搜索和安装插件。
/plugin marketplace remove​	移除市场源​	/plugin marketplace remove my-market	删除一个已添加的插件市场源。文档未提及，但根据命令结构推断，rm写法应该也支持，与 remove等效。​
/reload-plugins​ (相关命令)	重载插件​	/reload-plugins	安装、卸载或修改插件配置后，无需重启 Claude Code 会话，执行此命令即可让新配置立即生效。
/plugin update​ (相关命令)	更新插件​	/plugin update code-review	检查并更新指定插件到其源中的最新可用版本。

十七、权限模式

Claude Code 的权限系统通过 模式（怎么管）、规则（管什么）​ 和 沙箱（底层锁）​ 三个维度进行配置，旨在平衡自动化效率与代码安全。

优先级口诀：规则的 deny（拒绝） > ask（询问） > allow（允许） > Mode（模式）

1、权限动作

动作	效果	适用场景	优先级
"allow"	无需审批，直接自动运行	低风险、高频操作，如 git status、npm run build	低
"ask"	弹出审批提示，由你决定是否允许	有一定风险的操作，如文件写入、危险命令执行	中
"deny"	直接阻止，不会执行也不会提示	明确不允许的危险操作，如 git push、rm -rf	高

 2、规则语法（Rules）：精确控制工具访问

规则采用工具名(匹配条件)的格式，支持通配符 *，规则写在配置文件.claude/settings.json的 allow（允许）、deny（拒绝）、ask（询问）三个列表中，规则的优先级永远高于模式

工具	规则示例	作用
Bash​ (命令)	Bash(npm run *)	匹配以 npm run开头的命令。
Read​ (读文件)	Read(./.env)	匹配读取 .env文件。
Edit​ (写文件)	Edit(src/**/*.ts)	匹配修改 src下的 TypeScript 文件。
WebFetch​ (网络)	WebFetch(domain:github.com)	匹配抓取 GitHub 域名。

{
  "permissions": {
    "allow": [
      "Read(./*)",           // 允许自动读项目文件
      "Bash(npm run *)"      // 允许自动运行 npm 脚本
    ],
    "deny": [
      "Bash(rm -rf *)",      // 绝对禁止删除命令
      "Bash(sudo *)",        // 绝对禁止提权
      "Read(./secrets/*)"    // 绝对禁止读敏感目录
    ],
    "ask": [
      "Edit(./*)",           // 修改文件前必须问我
      "Bash(git push *)"     // 推送代码前必须问我
    ]
  }
}

3、权限模式（Mode）：决定 AI 的自主权

模式控制 Claude 在执行操作前是否需要弹窗询问你，是兜底策略。决定了“那些没被规则明确规定的操作”该怎么处理

模式	描述	最适用场景
default	标准行为：首次使用每个工具时提示权限	入门学习、敏感工作需要完全监督
acceptEdits	自动接受会话的文件编辑权限，受保护目录除外	迭代正在审查的代码
plan	Plan Mode：Claude 可以分析但不能修改文件或执行命令	探索代码库、规划重构
auto	自动批准工具调用，并进行后台安全检查（研究预览）	长时间运行的任务、减少提示疲劳
dontAsk	自动拒绝工具调用，除非通过权限规则预先批准	锁定环境、CI 管道
bypassPermissions	跳过权限提示，但对受保护目录的写入仍会提示	仅隔离容器和 VM

4、切换权限模式

会话期间切换：

按 Shift+Tab 循环切换 default → acceptEdits → plan → auto

启动时指定模式：

claude --permission-mode plan
claude --permission-mode bypassPermissions

设置为默认模式（.claude/settings.json）：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

5、沙箱（Sandbox）：操作系统级隔离

沙箱提供比规则更底层的防护（仅限 Bash 命令），防止命令越权访问系统文件。

配置项	作用	示例值
sandbox.enabled​	启用沙箱隔离。	true
sandbox.filesystem.allowWrite​	允许写入的路径（白名单）。	["/tmp"]
sandbox.filesystem.denyRead​	禁止读取的路径（黑名单）。	["/etc/passwd"]

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["./build"],  // 只允许写 build 目录
      "denyRead": ["~/.ssh"]      // 禁止读 SSH 密钥
    }
  }
}

6、常用权限命令

命令	作用
/permissions​	打开权限管理界面，查看生效规则
/reload-settings​	热重载权限配置，无需重启会话
/sandbox​	打开沙箱配置菜单