Claude 效率全家桶:从浏览器到终端的 AI 工作流
一个重度用户的日常实践分享
文档说明:本文档中的原理部分基于 Claude Code 官方文档整理。官方文档参考:
- Claude Code: https://code.claude.com/docs/en/overview
- MCP 协议: https://modelcontextprotocol.io
目录
1. Claude Web 端
概述
Claude Web 端是最轻量的使用方式,适合日常问答、调研分析和数据处理。支持联网搜索、文件上传、Projects 知识库等功能。
核心功能
| 功能 | 说明 | 适用场景 |
|---|---|---|
| 联网搜索 | 实时获取互联网信息 | 市场调研、竞品分析、新闻追踪 |
| 文件上传 | 支持 PDF、Excel、图片等 | 数据分析、文档总结、图表解读 |
| Projects | 创建专属知识库 | 长期项目、领域知识积累 |
| Artifacts | 实时预览代码/文档 | 代码生成、文档撰写 |
技术原理
flowchart TB
subgraph Input["输入层"]
A[用户提问] --> B{是否需要外部信息?}
B -->|是| C[上传文件/联网搜索]
B -->|否| D[直接对话]
end
subgraph Process["处理层"]
C --> E[Claude 分析处理]
D --> E
E --> F{是否需要迭代?}
end
subgraph Output["输出层"]
F -->|是| G[追问/补充需求]
G --> E
F -->|否| H[生成结果]
H --> I[Artifacts 预览]
H --> J[文本回复]
end
工作原理说明:
- 输入解析:Claude 首先分析用户输入,判断是否需要外部信息(联网搜索或文件内容)
- 上下文构建:将用户问题、上传文件、搜索结果整合为完整上下文
- 推理生成:基于 Transformer 架构进行多轮推理,生成响应
- Artifacts 渲染:对于代码、文档等结构化输出,使用独立的 Artifacts 面板实时预览
调研分析工作流
flowchart LR
subgraph Step1["1.定义需求"]
A1[明确调研目标] --> A2[列出关键问题]
end
subgraph Step2["2.信息收集"]
A2 --> B1[启用联网搜索]
B1 --> B2[多轮追问补充]
B2 --> B3[上传相关文档]
end
subgraph Step3["3.分析整理"]
B3 --> C1[交叉验证信息]
C1 --> C2[结构化整理]
C2 --> C3[生成报告]
end
subgraph Step4["4.输出"]
C3 --> D1[Markdown 文档]
C3 --> D2[表格数据]
C3 --> D3[思维导图]
end
数据分析整理工作流
flowchart TB
subgraph Upload["上传阶段"]
A[上传 Excel/CSV 文件] --> B[Claude 解析文件结构]
B --> C[展示数据预览]
end
subgraph Analyze["分析阶段"]
C --> D[描述分析需求]
D --> E{分析类型}
E -->|数据清洗| F1[去重/填充/格式化]
E -->|统计分析| F2[汇总/分组/计算]
E -->|可视化| F3[生成图表代码]
E -->|转换格式| F4[重组数据结构]
end
subgraph Output["输出阶段"]
F1 --> G[生成处理后的数据]
F2 --> G
F3 --> G
F4 --> G
G --> H[下载结果文件]
end
演示:Excel 数据整理与分析
场景示例:处理回测数据表,生成天、周、月度净值和汇总报告
Prompt 模板:
1请帮我分析这份回测数据,生成以下的Excel表格:
21. 按天、周、月份计算NAV,包含时间、净值、收益率、交易次数信息
32. 计算Key Statistics(收益率、回撤、胜率等信息)、Monthly Performance(每月收益率和年度收益率)
43. 计算Sharpe Ratio、Sortino Ratio、Calmar Ratio(无风险利率为 4.0%)
54. 手续费为单笔万分之五。
2. Claude Chrome 插件
概述
Chrome 插件将 Claude 的能力延伸到浏览器中,可以直接操作网页、填写表单、提取信息,并能与本地 Claude Code 联动实现更复杂的自动化流程。
核心功能
| 功能 | 说明 | 适用场景 |
|---|---|---|
| 页面分析 | 读取当前网页内容 | 文章总结、信息提取 |
| 浏览器自动化 | 模拟点击、输入、导航 | 表单填写、批量操作 |
| 截图分析 | 捕获页面视觉信息 | UI 分析、视觉内容理解 |
| Claude Code 联动 | 与本地终端协作 | 复杂工作流、代码生成 |
架构原理
flowchart TB
subgraph Browser["浏览器环境"]
A[Chrome 插件] --> B[MCP Server]
B --> C[页面 DOM 访问]
B --> D[截图能力]
B --> E[网络请求监控]
end
subgraph Claude["Claude 服务"]
F[Claude API]
end
subgraph Local["本地环境"]
G[Claude Code CLI]
H[本地文件系统]
I[终端命令]
end
A <-->|API 调用| F
A <-->|MCP 协议| G
G --> H
G --> I
技术原理详解:
1. MCP (Model Context Protocol) 通信机制
sequenceDiagram
participant Plugin as Chrome 插件
participant MCP as MCP Client
participant Server as MCP Server
participant Tool as 外部工具
Plugin->>MCP: 初始化 MCP 连接
MCP->>Server: JSON-RPC 握手
Server-->>MCP: 返回可用工具列表
MCP-->>Plugin: 工具能力描述
Plugin->>MCP: 调用工具 (tool_name, params)
MCP->>Server: 封装 JSON-RPC 请求
Server->>Tool: 执行实际操作
Tool-->>Server: 返回结果
Server-->>MCP: JSON-RPC 响应
MCP-->>Plugin: 解析并返回结果
2. DOM 快照与元素定位原理
flowchart LR
subgraph Capture["捕获阶段"]
A[页面加载完成] --> B[构建 DOM 树]
B --> C[生成元素引用 ref_id]
C --> D[可访问性树解析]
end
subgraph Process["处理阶段"]
D --> E[Claude 分析页面结构]
E --> F[识别交互元素]
F --> G[生成操作计划]
end
subgraph Execute["执行阶段"]
G --> H[通过 ref_id 定位元素]
H --> I[模拟用户交互]
I --> J[验证操作结果]
end
关键技术点:
- 元素引用 (ref_id):每个 DOM 元素被分配唯一标识符,确保精确定位
- 可访问性树:利用浏览器的 Accessibility Tree 获取语义化的页面结构
- 视口管理:自动处理滚动、等待加载、动态内容更新
浏览器自动化流程
flowchart TB
subgraph Init["初始化"]
A[用户发起指令] --> B[插件获取页面快照]
B --> C[构建页面 DOM 树]
end
subgraph Plan["规划阶段"]
C --> D[Claude 分析页面结构]
D --> E[制定操作计划]
E --> F[用户确认计划]
end
subgraph Execute["执行阶段"]
F --> G{执行操作}
G --> H[点击元素]
G --> I[输入文本]
G --> J[页面导航]
G --> K[等待加载]
H --> L{操作完成?}
I --> L
J --> L
K --> L
L -->|否| G
L -->|是| M[返回结果]
end
与 Claude Code 联动流程
sequenceDiagram
participant User as 用户
participant Plugin as Chrome 插件
participant CC as Claude Code
participant FS as 文件系统
participant Web as 网页
User->>Plugin: 发起复杂任务
Plugin->>Web: 提取网页数据
Web-->>Plugin: 返回数据
Plugin->>CC: 通过 MCP 发送数据
CC->>FS: 保存/处理数据
CC->>CC: 执行本地命令
CC-->>Plugin: 返回处理结果
Plugin->>Web: 执行后续操作
Plugin-->>User: 任务完成
演示:简历优化 & 投递助手
工作流程:
flowchart LR
subgraph Optimize["简历优化"]
A1[上传简历 PDF] --> A2[分析简历内容]
A2 --> A3[提取 JD 要求]
A3 --> A4[生成优化建议]
A4 --> A5[输出优化版简历]
end
subgraph Apply["投递助手"]
A5 --> B1[打开招聘网站]
B1 --> B2[自动填写表单]
B2 --> B3[上传简历附件]
B3 --> B4[用户确认提交]
end
操作步骤:
-
准备阶段
- 将简历上传至 Claude Web 进行优化
- 根据目标岗位 JD 调整关键词
-
自动填写
- 打开招聘网站职位页面
- 插件识别表单字段
- 自动填充个人信息
- 用户确认后提交
3. Claude Code(核心)
基于官方文档:https://code.claude.com/docs/en/overview
概述
Claude Code 是 Anthropic 官方的 Agentic 编码 CLI,运行在终端中。它被设计为遵循 Unix 哲学原则的可组合、可脚本化工具。
核心能力
| 能力 | 说明 |
|---|---|
| 从描述构建功能 | 将自然语言规格转换为带规划和验证的工作代码 |
| 调试和修复问题 | 分析代码库、识别问题并实现修复 |
| 导航任何代码库 | 以项目全局意识提供深思熟虑的答案 |
| 自动化繁琐任务 | 处理 lint 问题、合并冲突、发布说明生成 |
关键架构原则
- 终端原生:在开发者已经工作的地方工作,不是单独的聊天窗口或 IDE
- 采取行动:直接编辑文件、运行命令、创建提交
- Unix 哲学:可组合和可脚本化 - 支持管道和 CI 集成
- 企业就绪:内置安全、隐私和合规性
集成生态
flowchart TB
subgraph Core["Claude Code 核心"]
A[CLI 终端] --> B[对话管理器]
B --> C[工具调用系统]
end
subgraph Integrations["集成点"]
D[Claude Code Web]
E[桌面应用]
F[Chrome 插件]
G[VS Code / JetBrains]
H[GitHub Actions / GitLab CI]
I[Slack]
end
subgraph Extensions["扩展机制"]
J[SubAgent 子代理]
K[MCP 协议]
L[Skills 技能]
M[Hooks 钩子]
N[Plugins 插件]
end
Core --> Integrations
Core --> Extensions
部署选项
| 平台 | 说明 |
|---|---|
| Claude API | 默认 |
| AWS (Amazon Bedrock) | 企业部署 |
| Google Cloud (Vertex AI) | 企业部署 |
| Microsoft Foundry | 企业部署 |
Unix 哲学示例
1# 日志分析 + AI 异常检测
2tail -f app.log | claude -p "如果发现异常就 Slack 通知我"
3
4# CI 中的自动翻译工作流
5claude -p "如果有新的文本字符串,将它们翻译成法语并为 @lang-fr-team 创建 PR 审查"
整体架构
flowchart TB
subgraph Core["Claude Code 核心"]
A[CLI 入口] --> B[对话管理器]
B --> C[工具调用系统]
C --> D[文件操作 Read/Write/Edit]
C --> E[Bash 执行]
C --> F[搜索 Glob/Grep]
end
subgraph Extensions["扩展机制"]
G[SubAgent] --> C
H[MCP Servers] --> C
I[Skills] --> B
J[Hooks] --> A
J --> C
K[Plugins] --> G
K --> H
K --> I
K --> J
end
subgraph External["外部资源"]
L[GitHub/Jira/Sentry]
M[数据库 PostgreSQL/Supabase]
N[浏览器 Playwright]
O[自定义 API]
end
H --> L
H --> M
H --> N
H --> O
项目目录结构与关系
本项目 (everything-claude-code) 的目录结构反映了 Claude Code 的扩展机制层次:
1everything-claude-code/
2├── agents/ # SubAgent 定义(独立上下文的专业代理)
3├── commands/ # 用户命令(已废弃,迁移至 skills)
4├── contexts/ # 上下文模板(预设提示词片段)
5├── hooks/ # 事件钩子(自动化触发脚本)
6├── plugins/ # 插件打包(整合上述组件的分发单元)
7├── rules/ # 规则约束(行为准则和最佳实践)
8├── skills/ # 技能定义(可调用的工作流模板)
9├── mcp-configs/ # MCP 服务器配置示例
10└── examples/ # 使用示例
目录关系图
flowchart TB
subgraph User["用户交互层"]
U[用户输入]
end
subgraph Triggers["触发机制"]
SK[Skills
主动调用 /skill-name]
HK[Hooks
事件自动触发]
end
subgraph Agents["执行层"]
AG[Agents/SubAgent
独立上下文执行]
end
subgraph Context["上下文层"]
CT[Contexts
预设提示词片段]
RL[Rules
行为约束规则]
end
subgraph External["外部连接"]
MCP[MCP Servers
外部工具/数据]
end
subgraph Package["打包分发"]
PL[Plugins
整合打包]
end
U --> SK
U --> HK
SK --> AG
HK --> AG
AG --> CT
AG --> RL
AG --> MCP
PL -.->|包含| SK
PL -.->|包含| HK
PL -.->|包含| AG
PL -.->|包含| MCP
各目录详解
| 目录 | 作用 | 调用方式 | 存储位置 |
|---|---|---|---|
| agents/ | 定义专业 SubAgent,具有独立上下文和工具权限 | Claude 自动委托或 Task 工具调用 | ~/.claude/agents/ |
| commands/ | 用户可调用的斜杠命令(已废弃,迁移至 skills) | /command-name |
~/.claude/commands/ |
| contexts/ | 可复用的提示词片段,用于设置对话上下文 | 在对话中引用 | 项目内 |
| hooks/ | 事件驱动的自动化脚本,响应 Claude 生命周期事件 | 自动触发 | settings.json 配置 |
| plugins/ | 打包 skills + agents + hooks + MCP 的分发单元 | 整体安装 | ~/.claude/plugins/ |
| rules/ | 行为准则和约束,Claude 遵循的最佳实践 | 自动加载 | ~/.claude/rules/ |
| skills/ | 可调用的工作流模板,扩展 Claude 能力 | /skill-name 或自动触发 |
~/.claude/skills/ |
| mcp-configs/ | MCP 服务器配置示例 | 配置到 ~/.claude.json |
用户配置 |
演进关系
flowchart LR
subgraph Legacy["旧版(已废弃)"]
CMD[commands/]
end
subgraph Current["当前版本"]
SKL[skills/]
AGT[agents/]
HKS[hooks/]
MCP[mcp-configs/]
end
subgraph Future["打包分发"]
PLG[plugins/]
end
CMD -->|迁移至| SKL
SKL --> PLG
AGT --> PLG
HKS --> PLG
MCP --> PLG
迁移说明:
commands/目录已被官方废弃,功能迁移至skills/- 新项目应使用 Skills 而非 Commands
- Plugins 是推荐的分发方式,可以打包所有组件
3.1 SubAgent
基于官方文档:https://code.claude.com/docs/en/sub-agents
概述
SubAgent(子代理)是专门处理特定类型任务的 AI 助手。每个 SubAgent 运行在独立的上下文窗口中,具有:
- 自定义系统提示
- 特定工具访问权限
- 独立权限设置
- 独立对话历史
Claude 会根据任务描述和 SubAgent 配置自动将任务委托给合适的 SubAgent。
核心优势
| 优势 | 说明 |
|---|---|
| 保留上下文 | 将探索和实现分离,不占用主对话上下文 |
| 强制约束 | 通过限制工具访问来执行安全策略 |
| 复用配置 | 跨项目复用 SubAgent 定义 |
| 专业化行为 | 针对特定领域使用专注的提示词 |
| 成本控制 | 将任务路由到更快、更便宜的模型(如 Haiku) |
工作原理
flowchart TB
subgraph Main["主 Agent"]
A[接收复杂任务] --> B[任务分析]
B --> C[任务分解]
C --> D{委托决策}
end
subgraph Delegate["自动委托"]
D -->|基于描述匹配| E1[Explore SubAgent]
D -->|基于描述匹配| E2[Plan SubAgent]
D -->|基于描述匹配| E3[Custom SubAgent]
end
subgraph Execute["独立执行"]
E1 --> F1[独立上下文窗口]
E2 --> F2[独立上下文窗口]
E3 --> F3[独立上下文窗口]
end
subgraph Return["结果返回"]
F1 --> G[汇总结果]
F2 --> G
F3 --> G
G --> H[整合到主对话]
end
内置 SubAgent 类型
mindmap
root((内置 SubAgent))
Explore
只读工具
使用 Haiku 模型
文件发现
代码搜索
代码库探索
Plan
继承主模型
只读工具
计划模式研究
实现方案设计
General Purpose
继承主模型
全部工具
复杂多步骤任务
探索+修改+推理
Bash
命令执行
独立上下文
Claude Code Guide
使用 Haiku
Claude Code 功能问答
| 类型 | 模型 | 工具 | 用途 | 彻底程度 |
|---|---|---|---|---|
| Explore | Haiku | 只读 | 文件发现、代码搜索、代码库探索 | quick/medium/very thorough |
| Plan | 继承 | 只读 | 计划模式下的代码库研究 | - |
| General Purpose | 继承 | 全部 | 复杂多步骤任务 | - |
| Bash | - | Bash | 在独立上下文中运行终端命令 | - |
自定义 SubAgent 配置
SubAgent 使用 Markdown 文件定义,支持 YAML frontmatter:
1---
2name: code-reviewer
3description: 审查代码质量和最佳实践。在代码修改后主动使用。
4tools: Read, Glob, Grep, Bash
5model: sonnet
6permissionMode: default
7skills:
8 - api-conventions
9 - error-handling-patterns
10hooks:
11 PreToolUse:
12 - matcher: "Bash"
13 hooks:
14 - type: command
15 command: "./scripts/validate-command.sh"
16---
17
18你是一个代码审查专家。被调用时,分析代码并提供
19关于质量、安全性和最佳实践的具体可行反馈。
支持的 frontmatter 字段:
| 字段 | 必需 | 说明 |
|---|---|---|
name |
是 | 唯一标识符(小写、连字符) |
description |
是 | Claude 何时应委托给此 SubAgent |
tools |
否 | 逗号分隔的工具列表;省略则继承全部 |
disallowedTools |
否 | 要拒绝的工具 |
model |
否 | sonnet、opus、haiku 或 inherit(默认) |
permissionMode |
否 | default、acceptEdits、dontAsk、bypassPermissions、plan |
skills |
否 | 要预加载的技能列表 |
hooks |
否 | 生命周期钩子 |
SubAgent 存储位置与优先级
| 位置 | 作用域 | 优先级 | 用途 |
|---|---|---|---|
--agents CLI 参数 |
当前会话 | 1(最高) | 快速测试、自动化 |
.claude/agents/ |
项目 | 2 | 团队协作(提交到 git) |
~/.claude/agents/ |
用户 | 3 | 个人、跨项目 |
Plugin agents/ 目录 |
插件 | 4(最低) | 通过插件分发 |
前台 vs 后台执行
前台执行(默认):
- 阻塞主对话
- 权限提示传递给用户
- 完全交互式
后台执行:
- 并发运行
- 继承父权限,自动拒绝未授权操作
- MCP 工具不可用
- 触发方式:使用
run_in_background=true或 Ctrl+B
常见使用模式
flowchart LR
subgraph Pattern1["隔离高输出操作"]
A1[测试套件运行] --> B1[SubAgent 中执行]
B1 --> C1[只返回失败结果]
end
subgraph Pattern2["并行研究"]
A2[同时启动多个 SubAgent]
A2 --> B2[研究认证模块]
A2 --> C2[研究数据库模块]
A2 --> D2[研究 API 模块]
end
subgraph Pattern3["链式执行"]
A3[code-reviewer] --> B3[找出问题]
B3 --> C3[optimizer] --> D3[修复问题]
end
何时使用 SubAgent vs 主对话
| 场景 | 使用主对话 | 使用 SubAgent |
|---|---|---|
| 需要频繁来回交流 | ✓ | |
| 多阶段共享大量上下文 | ✓ | |
| 快速、针对性修改 | ✓ | |
| 延迟敏感 | ✓ | |
| 产生大量冗余输出 | ✓ | |
| 需要特定工具限制/权限 | ✓ | |
| 工作独立,只需摘要输出 | ✓ | |
| 想保留主对话上下文 | ✓ |
重要约束
- 不支持嵌套:SubAgent 不能启动其他 SubAgent
- 独立上下文:每个 SubAgent 从空白开始(除非 resume)
- 权限继承:继承父级权限上下文,但可覆盖模式
- 工具限制:通过
tools、disallowedTools和 hook 验证强制执行 - 后台限制:无 MCP 工具,自动拒绝未授权操作
- 转录持久化:独立存储,主对话 compact 后仍然存在
3.2 Plugin 与 MCP
基于官方文档:https://code.claude.com/docs/en/mcp 和 https://code.claude.com/docs/en/plugins
MCP 概述
MCP(Model Context Protocol)是一个开源标准,允许 Claude Code 连接数百个外部工具和数据源。通过 MCP 服务器,Claude Code 可以访问工具、数据库、API 和其他服务。
MCP 能做什么
连接 MCP 服务器后,你可以要求 Claude Code:
| 场景 | 示例 |
|---|---|
| 实现问题追踪器中的功能 | “添加 JIRA 问题 ENG-4521 中描述的功能并在 GitHub 上创建 PR” |
| 分析监控数据 | “检查 Sentry 和 Statsig 查看 ENG-4521 功能的使用情况” |
| 查询数据库 | “根据 PostgreSQL 数据库找出使用该功能的 10 个随机用户的邮箱” |
| 集成设计 | “根据 Slack 中发布的新 Figma 设计更新我们的标准邮件模板” |
| 自动化工作流 | “创建 Gmail 草稿邀请这 10 位用户参加新功能反馈会” |
MCP 协议架构
flowchart TB
subgraph ClaudeCode["Claude Code"]
A[MCP Client]
end
subgraph Transport["传输方式"]
B1[stdio 本地进程]
B2[HTTP 远程服务]
B3[SSE 服务端推送]
end
subgraph MCPServers["MCP Servers"]
C1[GitHub Server]
C2[Sentry Server]
C3[PostgreSQL Server]
C4[Figma Server]
C5[自定义 Server]
end
A --> B1 --> C1
A --> B2 --> C2
A --> B2 --> C3
A --> B2 --> C4
A --> B1 --> C5
MCP Server 安装方式
方式一:远程 HTTP 服务器(推荐)
1# 基本语法
2claude mcp add --transport http <name> <url>
3
4# 示例:连接 Notion
5claude mcp add --transport http notion https://mcp.notion.com/mcp
6
7# 带 Bearer Token
8claude mcp add --transport http secure-api https://api.example.com/mcp \
9 --header "Authorization: Bearer your-token"
方式二:本地 Stdio 服务器
1# 基本语法
2claude mcp add [options] <name> -- <command> [args...]
3
4# 示例:添加 Airtable 服务器
5claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
6 -- npx -y airtable-mcp-server
重要:所有选项(--transport、--env、--scope、--header)必须在服务器名称之前。--(双破折号)用于分隔选项和命令。
MCP 管理命令
1# 列出所有配置的服务器
2claude mcp list
3
4# 获取特定服务器详情
5claude mcp get github
6
7# 移除服务器
8claude mcp remove github
9
10# 检查服务器状态(在 Claude Code 中)
11/mcp
安装作用域
| 作用域 | 存储位置 | 说明 | 用途 |
|---|---|---|---|
| local(默认) | ~/.claude.json |
私有,仅当前项目可访问 | 个人开发服务器、敏感凭据 |
| project | .mcp.json(项目根目录) |
通过版本控制共享 | 团队协作 |
| user | ~/.claude.json |
在所有项目中可用 | 跨项目工具 |
1# 项目作用域
2claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
3
4# 用户作用域
5claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
MCP 资源引用
使用 @ 提及引用 MCP 服务器中的资源:
1# 列出可用资源(输入 @)
2> @
3
4# 引用特定资源
5> 你能分析 @github:issue://123 并建议修复方案吗?
6
7# 多资源引用
8> 比较 @postgres:schema://users 和 @docs:file://database/user-model
MCP 提示作为命令
MCP 服务器可以将提示暴露为命令:
1# 无参数执行提示
2> /mcp__github__list_prs
3
4# 带参数执行提示
5> /mcp__github__pr_review 456
6> /mcp__jira__create_issue "登录流程中的 Bug" high
环境变量配置
在 .mcp.json 中支持环境变量展开:
1{
2 "mcpServers": {
3 "api-server": {
4 "type": "http",
5 "url": "${API_BASE_URL:-https://api.example.com}/mcp",
6 "headers": {
7 "Authorization": "Bearer ${API_KEY}"
8 }
9 }
10 }
11}
特殊环境变量:
MCP_TIMEOUT:设置 MCP 服务器启动超时MAX_MCP_OUTPUT_TOKENS:配置最大 MCP 工具输出(默认:25,000 tokens)ENABLE_TOOL_SEARCH:控制工具搜索行为
Plugin 概述
Plugin 是自定义扩展,可以用 Skills、Agents、Hooks 和 MCP Servers 扩展 Claude Code。可以跨项目和团队共享。
Plugin vs 独立配置
| 方面 | 独立配置(.claude/) |
插件 |
|---|---|---|
| 作用域 | 个人、项目特定 | 共享、团队/社区 |
| Skill 名称 | /hello |
/plugin-name:hello |
| 适用于 | 快速实验、个人工作流 | 分发、版本化发布 |
| 共享 | 手动复制 | 市场安装 |
Plugin 结构
1my-plugin/
2├── .claude-plugin/
3│ └── plugin.json # 必需的清单文件
4├── commands/ # Skills(Markdown 格式)
5│ └── hello.md
6├── agents/ # 自定义 Agent 定义
7├── skills/ # Agent Skills
8│ └── code-review/
9│ └── SKILL.md
10├── hooks/ # 事件处理器
11│ └── hooks.json
12├── .mcp.json # MCP 服务器配置
13└── .lsp.json # LSP 服务器配置
关键:只有 plugin.json 放在 .claude-plugin/ 内。所有其他目录必须在插件根级别。
创建 Plugin
步骤 1:创建清单文件
创建 .claude-plugin/plugin.json:
1{
2 "name": "my-first-plugin",
3 "description": "一个学习基础的问候插件",
4 "version": "1.0.0",
5 "author": {
6 "name": "Your Name"
7 }
8}
步骤 2:添加 Skill
创建 skills/hello/SKILL.md:
1---
2description: 用友好的消息问候用户
3disable-model-invocation: true
4---
5
6热情地问候用户,询问今天如何帮助他们。
步骤 3:测试插件
1claude --plugin-dir ./my-first-plugin
然后尝试命令:
1/my-first-plugin:hello
常用 MCP Server
| MCP Server | 用途 | 配置方式 |
|---|---|---|
| github | PR/Issue/Repo 操作 | 需要 PAT Token |
| sentry | 错误监控分析 | OAuth 认证 |
| supabase | 数据库 CRUD | 需要 Project Ref |
| playwright | 浏览器自动化 | 直接使用 |
| memory | 持久化记忆 | 直接使用 |
| context7 | 库文档查询 | 直接使用 |
| vercel | 部署管理 | HTTP 模式 |
上下文管理注意事项
1# 重要提醒
2- 不要同时启用所有 MCP
3- 200k 上下文可能因为太多工具缩减到 70k
4- 建议:配置 20-30 个 MCP,每个项目启用 <10 个
5- 使用 disabledMcpServers 按项目禁用
6- 当 MCP 工具定义超过上下文窗口的 10% 时,工具搜索会自动按需加载工具
3.3 Skills
基于官方文档:https://code.claude.com/docs/en/skills
概述
Skills 通过添加自定义功能和斜杠命令来扩展 Claude 的能力。Skill 是一个带有 YAML frontmatter 和 markdown 指令的 SKILL.md 文件,Claude 在调用时会遵循这些指令。
重要:自定义斜杠命令已合并到 Skills 中。位于 .claude/skills/review/SKILL.md 的 Skill 会创建 /review 命令,替代了旧的 .claude/commands/ 方式。
Skills 存储位置
| 位置 | 路径 | 作用域 |
|---|---|---|
| 企业 | 见托管设置 | 所有组织用户 |
| 个人 | ~/.claude/skills/<skill-name>/SKILL.md |
所有项目 |
| 项目 | .claude/skills/<skill-name>/SKILL.md |
仅当前项目 |
| 插件 | <plugin>/skills/<skill-name>/SKILL.md |
启用插件的地方 |
项目 Skills 会覆盖同名的个人 Skills。嵌套目录中的 Skills(如 packages/frontend/.claude/skills/)会自动被发现。
创建 Skill
基本结构:
1---
2name: explain-code
3description: 用视觉图表和类比解释代码。在解释代码工作原理、教授代码库知识或用户问"这是怎么工作的?"时使用。
4---
5
6解释代码时,始终包括:
7
81. **从类比开始**:将代码比作日常生活中的事物
92. **画图**:使用 ASCII 艺术展示流程、结构或关系
103. **逐步讲解**:解释发生了什么
114. **指出陷阱**:常见错误或误解是什么?
12
13保持解释对话式。对于复杂概念,使用多个类比。
使用方式:
- 手动调用:
/explain-code src/auth/login.ts - 自动调用:当请求与描述匹配时,Claude 会自动加载
Frontmatter 配置
所有字段都是可选的。只推荐使用 description。
| 字段 | 类型 | 用途 |
|---|---|---|
name |
string | Skill 标识符(小写、连字符,最多 64 字符)。默认为目录名。 |
description |
string | Skill 做什么以及何时使用。Claude 用这个来自动加载 Skills。 |
argument-hint |
string | 自动完成提示:[issue-number] 或 [filename] [format] |
disable-model-invocation |
boolean | 设为 true 阻止 Claude 自动加载。用于有副作用的命令如 /deploy。 |
user-invocable |
boolean | 设为 false 从 / 菜单隐藏。仅用于背景知识。 |
allowed-tools |
string | Claude 可以不询问就使用的工具(逗号分隔):Read, Grep, Bash |
model |
string | Skill 激活时使用的模型 |
context |
string | 设为 fork 在隔离的 SubAgent 上下文中运行 |
agent |
string | 与 context: fork 一起使用的 SubAgent 类型:Explore、Plan、general-purpose |
hooks |
object | 此 Skill 的生命周期钩子 |
控制调用方式
引用内容(Claude 应用于当前工作的知识):
1---
2name: api-conventions
3description: 此代码库的 API 设计模式
4---
5
6编写 API 端点时:
7- 使用 RESTful 命名约定
8- 返回一致的错误格式
9- 包含请求验证
任务内容(特定操作的分步指令):
使用 disable-model-invocation: true 要求手动调用:
1---
2name: deploy
3description: 部署应用到生产环境
4disable-model-invocation: true
5---
6
7部署应用:
81. 运行测试套件
92. 构建应用
103. 推送到部署目标
背景知识(Claude 应该知道但用户不应调用的知识):
1---
2name: legacy-system-context
3description: 理解遗留支付系统
4user-invocable: false
5---
6
7遗留支付系统...
字符串替换
Skills 支持动态值:
| 变量 | 说明 |
|---|---|
$ARGUMENTS |
调用 Skill 时传递的所有参数 |
${CLAUDE_SESSION_ID} |
当前会话 ID,用于日志/关联 |
1---
2name: fix-issue
3description: 修复 GitHub issue
4disable-model-invocation: true
5---
6
7按照我们的编码标准修复 GitHub issue $ARGUMENTS。
8
91. 读取 issue 描述
102. 实现修复
113. 编写测试
124. 创建提交
使用:/fix-issue 123 → Claude 收到 “按照我们的编码标准修复 GitHub issue 123…”
动态上下文注入
使用 !`command` 运行 shell 命令并注入其输出:
1---
2name: pr-summary
3description: 总结 Pull Request 的变更
4context: fork
5agent: Explore
6allowed-tools: Bash(gh:*)
7---
8
9## Pull Request 上下文
10- PR diff: !`gh pr diff`
11- PR 评论: !`gh pr view --comments`
12- 变更文件: !`gh pr diff --name-only`
13
14总结这个 Pull Request...
命令在 Claude 看到内容之前执行。
在 SubAgent 中运行 Skills
添加 context: fork 在隔离环境中运行 Skills,不带对话历史:
1---
2name: deep-research
3description: 深入研究主题
4context: fork
5agent: Explore
6---
7
8彻底研究 $ARGUMENTS:
9
101. 使用 Glob 和 Grep 查找相关文件
112. 阅读并分析代码
123. 用具体文件引用总结发现
agent 字段选项:Explore(只读)、Plan、general-purpose 或自定义 agents。
限制工具访问
限制 Claude 可以使用的工具:
1---
2name: safe-reader
3description: 读取文件但不做更改
4allowed-tools: Read, Grep, Glob
5---
内置 Skills 分类
mindmap
root((Skills))
开发流程
brainstorming 头脑风暴
writing-plans 计划编写
test-driven-development TDD
code-review 代码审查
verification-before-completion 完成前验证
Git 操作
commit 提交代码
commit-push-pr 提交并创建PR
调试分析
systematic-debugging 系统调试
设计模式
frontend-design 前端设计
backend-patterns 后端模式
工具使用
using-git-worktrees Git工作树
using-superpowers 超能力使用
| Skill 名称 | 用途 | 触发方式 |
|---|---|---|
| brainstorming | 需求分析与方案讨论 | /brainstorming |
| writing-plans | 制定实现计划 | /writing-plans |
| test-driven-development | TDD 开发流程 | /tdd |
| code-review | 代码审查 | /code-review |
| systematic-debugging | 系统化调试 | /debug |
| verification-before-completion | 完成前验证 | 自动激活 |
| frontend-design | 前端设计模式 | /frontend-design |
故障排除
| 问题 | 解决方案 |
|---|---|
| Skill 没有触发 | 检查描述是否包含用户会说的关键词;用 /skill-name 调用 |
| Skill 触发太频繁 | 使描述更具体;添加 disable-model-invocation: true |
| Claude 看不到所有 Skills | Skill 描述可能超过上下文预算(默认 15,000 字符)。检查 /context 警告;增加 SLASH_COMMAND_TOOL_CHAR_BUDGET |
3.4 Hook
基于官方文档:https://code.claude.com/docs/en/hooks
概述
Hooks 是在会话期间特定时间点触发的自动化操作。它们可以执行 bash 命令或基于 LLM 的评估,用于控制工具执行、验证输入、管理权限以及执行设置/清理任务。
Hook 生命周期
flowchart LR
A[SessionStart] --> B[UserPromptSubmit]
B --> C[PreToolUse]
C --> D[PermissionRequest]
D --> E[PostToolUse]
E --> F[SubagentStop]
F --> G[Stop]
G --> H[PreCompact]
H --> I[SessionEnd]
Hook 类型
1. Bash 命令 Hooks(type: "command")
执行 shell 脚本进行确定性规则检查:
1{
2 "type": "command",
3 "command": "/path/to/script.sh",
4 "timeout": 60
5}
2. 提示 Hooks(type: "prompt")
使用 LLM 进行上下文感知决策(仅 Stop/SubagentStop):
1{
2 "type": "prompt",
3 "prompt": "评估 Claude 是否应该停止: $ARGUMENTS",
4 "timeout": 30
5}
Hook 事件详解
| 事件 | 触发时机 | 可控制 |
|---|---|---|
| SessionStart | 会话开始/恢复时 | 加载上下文,通过 CLAUDE_ENV_FILE 持久化环境变量 |
| UserPromptSubmit | 用户提交提示时 | 添加上下文或阻止提示 |
| PreToolUse | Claude 创建工具参数后、执行前 | allow/deny/ask,修改输入 |
| PermissionRequest | 权限对话框出现时 | 代替用户允许/拒绝 |
| PostToolUse | 工具成功完成后 | 处理结果、日志记录 |
| SubagentStop | SubAgent 完成时 | 可阻止并提供继续原因 |
| Stop | Claude 完成时 | 可阻止并提供继续原因 |
| PreCompact | 上下文压缩前(手动或自动) | 保存状态 |
| SessionEnd | 会话终止时 | 清理任务 |
| Setup | 使用 --init、--init-only 或 --maintenance 标志时 |
一次性操作如依赖安装 |
| Notification | Claude Code 发送通知时 | 发送自定义通知 |
配置结构
1{
2 "hooks": {
3 "EventName": [
4 {
5 "matcher": "ToolPattern",
6 "hooks": [
7 {
8 "type": "command",
9 "command": "your-command"
10 }
11 ]
12 }
13 ]
14 }
15}
匹配器(用于 PreToolUse、PermissionRequest、PostToolUse):
- 简单字符串:
Write精确匹配 - 正则表达式:
Edit|Write或Notebook.* - 通配符:
*匹配所有工具
常用工具匹配器
| 匹配器 | 匹配目标 |
|---|---|
Bash |
Shell 命令 |
Read |
文件读取 |
Write |
文件写入 |
Edit |
文件编辑 |
Task |
SubAgent 任务 |
Glob, Grep |
模式匹配 |
WebFetch, WebSearch |
Web 操作 |
mcp__* |
MCP 工具(如 mcp__memory__create_entities) |
Hook 输入输出
输入(通过 stdin):
1{
2 "session_id": "abc123",
3 "transcript_path": "/path/to/transcript.jsonl",
4 "cwd": "/current/directory",
5 "permission_mode": "default",
6 "hook_event_name": "PreToolUse",
7 "tool_name": "Bash",
8 "tool_input": {
9 "command": "npm install"
10 }
11}
输出(退出码 + JSON):
| 退出码 | 含义 |
|---|---|
0 |
成功(stdout 处理为 JSON) |
2 |
阻塞错误(stderr 显示给 Claude,阻止操作) |
| 其他 | 非阻塞错误(stderr 显示给用户) |
JSON 输出示例:
1{
2 "continue": true,
3 "hookSpecificOutput": {
4 "hookEventName": "PreToolUse",
5 "permissionDecision": "allow",
6 "permissionDecisionReason": "自动批准读取操作"
7 }
8}
PreToolUse 控制选项
"permissionDecision": "allow"- 绕过权限系统"permissionDecision": "deny"- 阻止工具调用"permissionDecision": "ask"- 询问用户updatedInput- 执行前修改工具输入
环境变量
$CLAUDE_PROJECT_DIR- 项目根目录$CLAUDE_ENV_FILE- 持久化环境变量的文件(仅 SessionStart)$CLAUDE_PLUGIN_ROOT- 插件目录(用于插件 hooks)$CLAUDE_CODE_REMOTE- Web 端为 “true”,CLI 为空
Hook 配置详解
配置文件位置:~/.claude/settings.json
1{
2 "hooks": {
3 "SessionStart": [
4 {
5 "matcher": "*",
6 "hooks": [
7 {
8 "type": "command",
9 "command": "~/.claude/hooks/memory-persistence/session-start.sh"
10 }
11 ],
12 "description": "加载之前的会话上下文"
13 }
14 ],
15 "PreToolUse": [
16 {
17 "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm run dev|pnpm dev)\"",
18 "hooks": [
19 {
20 "type": "command",
21 "command": "#!/bin/bash\necho '[Hook] BLOCKED: Dev server must run in tmux' >&2\nexit 1"
22 }
23 ],
24 "description": "阻止在非 tmux 环境运行 dev server"
25 },
26 {
27 "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
28 "hooks": [
29 {
30 "type": "command",
31 "command": "#!/bin/bash\necho '[Hook] Review before push...' >&2\nread -r"
32 }
33 ],
34 "description": "push 前暂停确认"
35 },
36 {
37 "matcher": "tool == \"Write\" && tool_input.file_path matches \"\\\\.md$\"",
38 "hooks": [
39 {
40 "type": "command",
41 "command": "#!/bin/bash\necho '[Hook] BLOCKED: No random .md files' >&2\nexit 1"
42 }
43 ],
44 "description": "阻止创建不必要的文档文件"
45 }
46 ],
47 "PostToolUse": [
48 {
49 "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx)$\"",
50 "hooks": [
51 {
52 "type": "command",
53 "command": "#!/bin/bash\nprettier --write \"$file_path\" 2>/dev/null"
54 }
55 ],
56 "description": "编辑后自动格式化"
57 },
58 {
59 "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
60 "hooks": [
61 {
62 "type": "command",
63 "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
64 }
65 ],
66 "description": "检测 console.log"
67 }
68 ],
69 "PreCompact": [
70 {
71 "matcher": "*",
72 "hooks": [
73 {
74 "type": "command",
75 "command": "~/.claude/hooks/memory-persistence/pre-compact.sh"
76 }
77 ],
78 "description": "压缩前保存状态"
79 }
80 ],
81 "Stop": [
82 {
83 "matcher": "*",
84 "hooks": [
85 {
86 "type": "command",
87 "command": "~/.claude/hooks/memory-persistence/session-end.sh"
88 }
89 ],
90 "description": "会话结束保存状态"
91 },
92 {
93 "matcher": "*",
94 "hooks": [
95 {
96 "type": "command",
97 "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
98 }
99 ],
100 "description": "评估会话提取可学习模式"
101 }
102 ],
103 "Notification": [
104 {
105 "matcher": "*",
106 "hooks": [
107 {
108 "type": "command",
109 "command": "osascript -e 'display notification \"$message\" with title \"Claude Code\"'"
110 }
111 ],
112 "description": "macOS 系统通知"
113 }
114 ]
115 }
116}
Hook 输入输出格式
flowchart LR
subgraph Input["Hook 输入 (stdin)"]
A["JSON 格式"]
A --> A1["session_id: 会话ID"]
A --> A2["tool: 工具名称"]
A --> A3["tool_input: 工具参数"]
A --> A4["tool_output: 工具输出 (PostToolUse)"]
end
subgraph Script["Hook 脚本处理"]
B["读取 stdin (cat)"]
B --> C["jq 解析 JSON"]
C --> D["业务逻辑判断"]
D --> E["输出结果"]
end
subgraph Output["Hook 输出 (stdout)"]
F["JSON 格式"]
F --> F1["allow: boolean 是否允许"]
F --> F2["reason: string 拒绝原因"]
F --> F3["modified_params: object 修改后参数"]
end
Input --> Script --> Output
Hook 脚本示例:
1#!/bin/bash
2# 读取输入
3input=$(cat)
4
5# 解析参数
6tool=$(echo "$input" | jq -r '.tool')
7command=$(echo "$input" | jq -r '.tool_input.command // ""')
8
9# 检查危险命令
10if echo "$command" | grep -qE 'rm -rf /|mkfs|dd if='; then
11 echo '{"allow": false, "reason": "危险命令被阻止"}'
12 exit 0
13fi
14
15# 允许执行
16echo '{"allow": true}'
实用 Hook 示例
mindmap
root((Hook 用例))
安全防护
阻止危险命令 rm -rf
敏感文件保护 .env
权限校验
自动化
代码格式化 Prettier
TypeScript 类型检查
自动测试
质量控制
console.log 检测
TODO/FIXME 提醒
文件大小检查
持久化
会话状态保存
上下文压缩前保存
学习成果提取
通知
任务完成提醒
错误告警
PR 创建通知
日常开发流程演示
完整开发流程
flowchart TB
subgraph Plan["1.规划阶段"]
A[接收需求] --> B["brainstorming"]
B --> C[需求分析与讨论]
C --> D["writing-plans"]
D --> E[生成实现计划]
end
subgraph Implement["2.实现阶段"]
E --> F["TDD开发"]
F --> G[编写测试用例]
G --> H[实现功能代码]
H --> I[运行测试验证]
end
subgraph Review["3.审查阶段"]
I --> J["完成前验证"]
J --> K[自检清单]
K --> L["code-review"]
L --> M[代码审查]
end
subgraph Ship["4.交付阶段"]
M --> N["commit"]
N --> O[生成提交信息]
O --> P["创建PR"]
P --> Q[Pull Request]
end
各阶段工具配合
sequenceDiagram
participant Dev as 开发者
participant CC as Claude Code
participant SA as SubAgent
participant Git as Git
Note over Dev,Git: 需求分析
Dev->>CC: 实现用户登录功能
CC->>CC: 调用 /brainstorming skill
CC->>SA: Explore: 分析现有认证代码
SA-->>CC: 代码结构报告
CC-->>Dev: 讨论方案选型
Note over Dev,Git: 计划制定
Dev->>CC: 确认方案 A
CC->>CC: 调用 /writing-plans skill
CC-->>Dev: 输出实现计划
Note over Dev,Git: TDD 开发
Dev->>CC: 开始开发
CC->>CC: 调用 /tdd skill
CC->>CC: 编写测试-实现-重构
Note over Dev,Git: 提交代码
Dev->>CC: 提交代码
CC->>CC: 调用 /commit skill
CC->>Git: git add && git commit
CC->>Git: git push && gh pr create
CC-->>Dev: PR 链接
4. 资源详解
项目结构
1everything-claude-code/
2├── agents/ # 专业化子代理
3├── skills/ # 工作流技能定义
4├── commands/ # 斜杠命令
5├── rules/ # 规则指南
6├── hooks/ # 自动化钩子
7├── contexts/ # 动态上下文
8├── mcp-configs/ # MCP 服务器配置
9├── plugins/ # 插件文档
10└── examples/ # 示例配置
4.1 Agents(代理)
位置:~/.claude/agents/
| Agent | 文件 | 用途 | 工具权限 | 模型 |
|---|---|---|---|---|
| planner | planner.md |
功能规划,创建实现计划 | Read, Grep, Glob | Opus |
| architect | architect.md |
系统设计,架构决策 | Read, Grep, Glob | Opus |
| tdd-guide | tdd-guide.md |
TDD 开发指导 | 全部 | Sonnet |
| code-reviewer | code-reviewer.md |
代码质量/安全审查 | Read, Grep, Glob, Bash | Opus |
| security-reviewer | security-reviewer.md |
安全漏洞分析 | Read, Grep, Glob | Opus |
| build-error-resolver | build-error-resolver.md |
构建错误修复 | 全部 | Sonnet |
| e2e-runner | e2e-runner.md |
Playwright E2E 测试 | 全部 | Sonnet |
| refactor-cleaner | refactor-cleaner.md |
死代码清理 | 全部 | Sonnet |
| doc-updater | doc-updater.md |
文档同步更新 | Read, Write | Haiku |
使用示例:
1# 自动触发(推荐)
2- 复杂功能请求 → 自动调用 planner
3- 代码修改后 → 自动调用 code-reviewer
4- 新功能开发 → 自动调用 tdd-guide
5
6# 手动调用
7使用 Task 工具指定 subagent_type
4.2 Skills(技能)
位置:~/.claude/skills/
工作流技能
| Skill | 目录/文件 | 描述 |
|---|---|---|
| TDD 工作流 | tdd-workflow/SKILL.md |
测试驱动开发完整流程 |
| 安全审查 | security-review/SKILL.md |
安全检查清单 |
| 持续学习 | continuous-learning/ |
自动提取会话中的模式 |
| 战略压缩 | strategic-compact/ |
上下文压缩建议 |
知识技能
| Skill | 文件 | 描述 |
|---|---|---|
| 编码标准 | coding-standards.md |
语言最佳实践 |
| 后端模式 | backend-patterns.md |
API/数据库/缓存模式 |
| 前端模式 | frontend-patterns.md |
React/Next.js 模式 |
| ClickHouse | clickhouse-io.md |
ClickHouse 使用指南 |
| 项目指南示例 | project-guidelines-example.md |
项目配置示例 |
TDD Skill 核心流程:
1RED → GREEN → REFACTOR → REPEAT
2
3RED: 写一个会失败的测试
4GREEN: 写最少代码让测试通过
5REFACTOR: 改进代码,保持测试通过
6REPEAT: 下一个功能/场景
安全审查 Skill 核心检查项:
1## 必查项
2- [ ] 无硬编码密钥
3- [ ] 所有用户输入已验证
4- [ ] SQL 使用参数化查询
5- [ ] HTML 已消毒防 XSS
6- [ ] CSRF 保护已启用
7- [ ] 认证/授权已验证
8- [ ] API 有速率限制
4.3 Commands(命令)
位置:~/.claude/commands/
| 命令 | 文件 | 描述 |
|---|---|---|
/tdd |
tdd.md |
测试驱动开发 |
/plan |
plan.md |
创建实现计划 |
/e2e |
e2e.md |
E2E 测试生成 |
/code-review |
code-review.md |
代码审查 |
/build-fix |
build-fix.md |
修复构建错误 |
/refactor-clean |
refactor-clean.md |
死代码清理 |
/learn |
learn.md |
会话中提取模式 |
/update-docs |
update-docs.md |
更新文档 |
/update-codemaps |
update-codemaps.md |
更新代码地图 |
/test-coverage |
test-coverage.md |
检查测试覆盖率 |
命令使用示例:
1# TDD 开发新功能
2/tdd 实现用户登录功能
3
4# 创建实现计划
5/plan 添加实时通知系统
6
7# 代码审查
8/code-review
9
10# 修复构建错误
11/build-fix
4.4 Rules(规则)
位置:~/.claude/rules/
| 规则 | 文件 | 描述 |
|---|---|---|
| 安全规则 | security.md |
安全检查、密钥管理 |
| 编码风格 | coding-style.md |
不可变性、文件组织 |
| 测试规则 | testing.md |
TDD、80% 覆盖率 |
| Git 工作流 | git-workflow.md |
提交格式、PR 流程 |
| 代理规则 | agents.md |
代理编排、使用时机 |
| 模式规则 | patterns.md |
API 响应、仓库模式 |
| 性能规则 | performance.md |
模型选择、上下文管理 |
| Hook 规则 | hooks.md |
Hook 使用指南 |
核心规则摘要:
1## 编码风格
2- 不可变性:永远创建新对象,不要修改
3- 文件组织:多个小文件 > 少数大文件
4- 文件大小:200-400 行常规,800 行上限
5- 错误处理:必须有 try/catch
6
7## 安全规则
8- 无硬编码密钥
9- 环境变量存储敏感数据
10- 验证所有用户输入
11- 仅使用参数化查询
12
13## 测试规则
14- TDD:先写测试
15- 80% 最低覆盖率
16- 单元 + 集成 + E2E
4.5 Hooks(钩子)
位置:~/.claude/hooks/
hooks.json 完整配置
1{
2 "hooks": {
3 "PreToolUse": [
4 {
5 "matcher": "tool == \"Bash\" && tool_input.command matches \"npm run dev\"",
6 "description": "阻止非 tmux 环境运行 dev server",
7 "action": "阻止执行,提示使用 tmux"
8 },
9 {
10 "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
11 "description": "push 前暂停确认",
12 "action": "等待用户确认"
13 },
14 {
15 "matcher": "tool == \"Write\" && 非必要 .md 文件",
16 "description": "阻止创建不必要的文档",
17 "action": "阻止执行"
18 },
19 {
20 "matcher": "tool == \"Edit\" || tool == \"Write\"",
21 "description": "建议手动压缩",
22 "action": "调用 strategic-compact"
23 }
24 ],
25 "PostToolUse": [
26 {
27 "matcher": "tool == \"Bash\" && gh pr create",
28 "description": "PR 创建后记录 URL",
29 "action": "输出 PR 链接和审查命令"
30 },
31 {
32 "matcher": "tool == \"Edit\" && .ts/.tsx 文件",
33 "description": "自动格式化",
34 "action": "运行 Prettier"
35 },
36 {
37 "matcher": "tool == \"Edit\" && .ts/.tsx 文件",
38 "description": "TypeScript 类型检查",
39 "action": "运行 tsc --noEmit"
40 },
41 {
42 "matcher": "tool == \"Edit\" && JS/TS 文件",
43 "description": "检测 console.log",
44 "action": "警告移除"
45 }
46 ],
47 "PreCompact": [
48 {
49 "matcher": "*",
50 "description": "压缩前保存状态",
51 "action": "memory-persistence/pre-compact.sh"
52 }
53 ],
54 "SessionStart": [
55 {
56 "matcher": "*",
57 "description": "加载之前上下文",
58 "action": "memory-persistence/session-start.sh"
59 }
60 ],
61 "Stop": [
62 {
63 "matcher": "*",
64 "description": "最终 console.log 检查",
65 "action": "扫描修改文件"
66 },
67 {
68 "matcher": "*",
69 "description": "保存会话状态",
70 "action": "memory-persistence/session-end.sh"
71 },
72 {
73 "matcher": "*",
74 "description": "评估会话提取模式",
75 "action": "continuous-learning/evaluate-session.sh"
76 }
77 ]
78 }
79}
记忆持久化 Hooks
位置:hooks/memory-persistence/
| 脚本 | 触发时机 | 功能 |
|---|---|---|
session-start.sh |
SessionStart | 加载之前的会话上下文 |
pre-compact.sh |
PreCompact | 压缩前保存状态 |
session-end.sh |
Stop | 会话结束保存状态 |
战略压缩 Hook
位置:hooks/strategic-compact/
在逻辑间隔点建议手动压缩上下文,避免自动压缩丢失重要信息。
4.6 Contexts(上下文)
位置:~/.claude/contexts/
| 上下文 | 文件 | 描述 |
|---|---|---|
| 开发模式 | dev.md |
代码优先,快速迭代 |
| 审查模式 | review.md |
质量检查,安全验证 |
| 研究模式 | research.md |
探索理解,信息收集 |
开发上下文示例:
1# 开发上下文
2Mode: 活跃开发
3Focus: 实现、编码、构建功能
4
5## 行为
6- 先写代码,后解释
7- 工作方案优先于完美方案
8- 修改后运行测试
9- 保持提交原子化
10
11## 优先级
121. 让它工作
132. 让它正确
143. 让它整洁
4.7 MCP Configs(MCP 配置)
位置:mcp-configs/mcp-servers.json
1{
2 "mcpServers": {
3 "github": {
4 "command": "npx",
5 "args": ["-y", "@modelcontextprotocol/server-github"],
6 "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PAT"},
7 "description": "GitHub 操作"
8 },
9 "firecrawl": {
10 "command": "npx",
11 "args": ["-y", "firecrawl-mcp"],
12 "env": {"FIRECRAWL_API_KEY": "YOUR_KEY"},
13 "description": "网页抓取"
14 },
15 "supabase": {
16 "command": "npx",
17 "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=REF"],
18 "description": "Supabase 数据库"
19 },
20 "memory": {
21 "command": "npx",
22 "args": ["-y", "@modelcontextprotocol/server-memory"],
23 "description": "持久记忆"
24 },
25 "sequential-thinking": {
26 "command": "npx",
27 "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
28 "description": "链式推理"
29 },
30 "vercel": {
31 "type": "http",
32 "url": "https://mcp.vercel.com",
33 "description": "Vercel 部署"
34 },
35 "context7": {
36 "command": "npx",
37 "args": ["-y", "@context7/mcp-server"],
38 "description": "实时文档"
39 }
40 }
41}
4.8 Plugins(插件)
安装市场
1# 添加官方市场
2claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
3
4# 添加社区市场
5claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
推荐插件
| 类别 | 插件 | 用途 |
|---|---|---|
| 开发 | typescript-lsp |
TypeScript 智能提示 |
| 开发 | pyright-lsp |
Python 类型检查 |
| 开发 | hookify |
对话式创建 Hook |
| 质量 | code-review |
代码审查 |
| 质量 | security-guidance |
安全检查 |
| 搜索 | mgrep |
增强搜索 |
| 搜索 | context7 |
文档查询 |
| 工作流 | commit-commands |
Git 工作流 |
| 工作流 | feature-dev |
功能开发 |
4.9 Examples(示例)
项目级 CLAUDE.md 示例
位置:项目根目录 CLAUDE.md
1# 项目概述
2[项目描述、技术栈]
3
4## 关键规则
5### 1. 代码组织
6- 多小文件 > 少大文件
7- 200-400 行常规,800 行上限
8
9### 2. 代码风格
10- 无 emoji
11- 不可变性
12- 无 console.log
13
14### 3. 测试
15- TDD:先写测试
16- 80% 最低覆盖率
17
18### 4. 安全
19- 无硬编码密钥
20- 验证所有输入
21
22## 可用命令
23- `/tdd` - TDD 开发
24- `/plan` - 创建计划
25- `/code-review` - 代码审查
用户级 CLAUDE.md 示例
位置:~/.claude/CLAUDE.md
1## 核心理念
21. 代理优先:复杂工作委托专业代理
32. 并行执行:尽可能并行使用 Task
43. 先规划后执行:复杂操作使用 Plan Mode
54. 测试驱动:先写测试再实现
65. 安全第一:永不妥协安全
7
8## 模块化规则
9规则文件位于 `~/.claude/rules/`:
10- security.md - 安全检查
11- coding-style.md - 编码风格
12- testing.md - 测试规则
13- git-workflow.md - Git 工作流
14- agents.md - 代理编排
5. 效率工具推荐
工具列表
| 工具名称 | 用途 | 说明 |
|---|---|---|
| Typora | Markdown 编辑器 | 所见即所得的 Markdown 编辑 |
| Superset | 终端复用 | 会话持久化,多窗口管理 |
| Happy | 远程管理Claude/Codex | 免费、使用简单、端到端加密 |
| Alma | AI聚合使用工具 | 免费、方便使用、支持直接使用Claude订阅 |
| Typeless | 口述需求替代打字 | 效率神奇、准确性高 |
工作流组合技巧
flowchart LR
subgraph Research["调研分析"]
A[Claude Web + 联网搜索]
end
subgraph Writing["文档编写"]
B[Typora + Claude]
end
subgraph Development["开发实现"]
C[Claude Code + IDE]
end
subgraph Automation["自动化"]
D[Chrome 插件 + Hook]
end
Research --> Writing --> Development --> Automation
推荐的 Skills 组合
| 场景 | Skills 组合 |
|---|---|
| 新功能开发 | /brainstorming → /plan → /tdd → /code-review |
| Bug 修复 | /debug → /tdd (写复现测试) → 修复 → /code-review |
| 代码重构 | /plan → 重构 → /code-review → /commit |
| 安全审计 | security-review skill → /code-review |
我的已安装 Skills 清单
以下是通过 Claude Code 插件系统安装的 Skills:
核心开发流程 (superpowers)
| Skill | 命令 | 用途 |
|---|---|---|
| brainstorming | /brainstorming |
创意工作前的需求探索、方案设计 |
| writing-plans | /writing-plans |
多步骤任务的实现计划编写 |
| test-driven-development | /tdd |
TDD 开发流程 |
| systematic-debugging | /debug |
系统化调试,bug/测试失败分析 |
| code-reviewer | - | 代码审查,完成主要功能后调用 |
| verification-before-completion | - | 完成前验证,提交/PR 前检查 |
| executing-plans | - | 执行已编写的实现计划 |
| dispatching-parallel-agents | - | 2+ 独立任务的并行调度 |
| subagent-driven-development | - | 当前会话的子代理驱动开发 |
| receiving-code-review | - | 接收代码审查反馈时使用 |
| requesting-code-review | - | 请求代码审查 |
| using-git-worktrees | - | Git Worktree 隔离开发 |
| writing-skills | - | 创建/编辑 Skills |
| finishing-a-development-branch | - | 完成开发分支,决定合并/PR/清理 |
Git 工作流 (commit-commands)
| Skill | 命令 | 用途 |
|---|---|---|
| commit | /commit |
创建 Git 提交 |
| commit-push-pr | /commit-push-pr |
提交、推送并创建 PR |
| clean_gone | /clean_gone |
清理已删除远程分支的本地分支 |
功能开发 (feature-dev)
| Skill | 命令 | 用途 |
|---|---|---|
| feature-dev | /feature-dev |
引导式功能开发 |
| code-architect | - | 分析代码库,设计功能架构 |
| code-explorer | - | 深度分析现有功能实现 |
| code-reviewer | - | 代码审查,置信度过滤 |
后端开发 (backend-development)
| Skill | 用途 |
|---|---|
| api-design-principles | REST/GraphQL API 设计原则 |
| architecture-patterns | Clean Architecture、六边形架构、DDD |
| microservices-patterns | 微服务架构、事件驱动、弹性模式 |
| cqrs-implementation | CQRS 读写分离实现 |
| event-store-design | 事件存储设计 |
| saga-orchestration | Saga 模式分布式事务 |
| projection-patterns | 事件流投影构建 |
| workflow-orchestration-patterns | Temporal 持久化工作流 |
| temporal-python-testing | Temporal Python 测试 |
| backend-architect | 后端架构设计 (Agent) |
| event-sourcing-architect | 事件溯源架构设计 (Agent) |
| graphql-architect | GraphQL 架构优化 (Agent) |
| tdd-orchestrator | TDD 流程编排 (Agent) |
| temporal-python-pro | Temporal Python 专家 (Agent) |
前端开发 (frontend-design)
| Skill | 命令 | 用途 |
|---|---|---|
| frontend-design | /frontend-design |
高质量前端界面设计与实现 |
CI/CD 自动化 (cicd-automation)
| Skill | 用途 |
|---|---|
| deployment-pipeline-design | 多阶段 CI/CD 流水线设计 |
| github-actions-templates | GitHub Actions 工作流模板 |
| gitlab-ci-patterns | GitLab CI/CD 模式 |
| secrets-management | 密钥管理最佳实践 |
| cloud-architect | 云架构设计 (Agent) |
| deployment-engineer | 部署工程 (Agent) |
| devops-troubleshooter | DevOps 故障排查 (Agent) |
| kubernetes-architect | K8s 架构设计 (Agent) |
| terraform-specialist | Terraform IaC 专家 (Agent) |
区块链/Web3 (blockchain-web3)
| Skill | 用途 |
|---|---|
| solidity-security | 智能合约安全最佳实践 |
| defi-protocol-templates | DeFi 协议模板 |
| nft-standards | NFT 标准实现 (ERC-721/1155) |
| web3-testing | 智能合约测试 |
| blockchain-developer | 区块链开发 (Agent) |
性能与可观测性 (application-performance)
| Skill | 用途 |
|---|---|
| frontend-developer | React 19/Next.js 15 前端开发 (Agent) |
| observability-engineer | 监控/日志/追踪系统 (Agent) |
| performance-engineer | 性能优化专家 (Agent) |
API 安全 (backend-api-security)
| Skill | 用途 |
|---|---|
| backend-architect | 后端架构设计 (Agent) |
| backend-security-coder | 后端安全编码 (Agent) |
浏览器自动化 (dev-browser)
| Skill | 命令 | 用途 |
|---|---|---|
| dev-browser | - | 浏览器自动化,持久页面状态 |
| browsing | - | Chrome DevTools 协议控制 |
记忆与上下文 (episodic-memory)
| Skill | 命令 | 用途 |
|---|---|---|
| search-conversations | /search-conversations |
搜索历史对话 |
| remembering-conversations | - | 恢复之前的决策和解决方案 |
代码简化 (code-simplifier)
| Skill | 用途 |
|---|---|
| code-simplifier | 简化和优化代码,提升清晰度、一致性和可维护性,聚焦最近修改的代码 |
API 测试与文档 (api-testing-observability)
| Skill | 用途 |
|---|---|
| api-documenter | OpenAPI 3.1 文档、SDK 生成、开发者门户 (Agent) |
其他工具
| Skill | 命令 | 用途 |
|---|---|---|
| planning-with-files | /planning-with-files |
文件式规划 (task_plan.md) |
| crypto-options-trading | - | 加密期权交易功能开发 |
| code-review | /code-review |
PR 代码审查 |
| ralph-loop | /ralph-loop |
Ralph Loop 循环执行 |
| ralph-wiggum | /ralph-wiggum |
Ralph Wiggum 技术 |
6. Claude Code 擅长与不擅长
基于官方最佳实践文档:https://code.claude.com/docs/en/best-practices
核心约束:上下文窗口
大多数最佳实践都基于一个约束:Claude 的上下文窗口会快速填满,且性能随之下降。
Claude 的上下文窗口保存整个对话,包括每条消息、每个读取的文件和每个命令输出。一次调试会话或代码库探索可能消耗数万个 token。当上下文窗口接近填满时,Claude 可能开始"遗忘"早期指令或犯更多错误。
Claude Code 擅长的事情
mindmap
root((Claude 擅长))
代码探索与理解
快速了解新代码库结构
追踪执行流程
理解架构模式
查找相关代码
调试与修复
分析错误信息和堆栈
定位问题根源
实现修复并验证
处理边界情况
代码重构
识别过时的 API 用法
现代化代码模式
保持向后兼容
分步重构
测试相关
识别未测试代码
生成测试脚手架
添加边界条件测试
运行并修复测试
自动化任务
创建 Pull Request
生成文档
代码审查
CI/CD 集成
| 擅长领域 | 具体能力 | 最佳实践 |
|---|---|---|
| 代码库探索 | 快速理解项目结构、架构模式、执行流程 | 先问广泛问题,再缩小到具体领域 |
| 调试修复 | 分析错误、追踪问题、实现修复 | 提供错误信息、复现步骤、期望结果 |
| 重构现代化 | 识别过时代码、应用现代模式 | 分小步重构,每步都可测试 |
| 测试生成 | 生成符合项目风格的测试、覆盖边界情况 | 指定要验证的具体行为 |
| PR 与文档 | 生成描述性 PR、添加代码注释 | 让 Claude 直接创建 PR |
| Unix 风格集成 | 管道输入输出、CI/CD 集成、批量处理 | 使用 claude -p 和 --output-format |
关键成功因素:给 Claude 验证方式
这是最能提升效果的单一做法: 让 Claude 能够验证自己的工作。
| 策略 | 改进前 | 改进后 |
|---|---|---|
| 提供验证标准 | “实现一个验证邮箱的函数” | “写一个 validateEmail 函数。测试用例:user@example.com 为 true,invalid 为 false。实现后运行测试” |
| 视觉验证 UI 变更 | “让仪表盘更好看” | “[粘贴截图] 实现这个设计。截图结果并与原图比较,列出差异并修复” |
| 解决根本原因 | “构建失败了” | “构建失败,错误信息:[粘贴错误]。修复它并验证构建成功。解决根本原因,不要压制错误” |
Claude Code 不擅长的事情
mindmap
root((Claude 不擅长))
模糊的任务
没有明确验证标准
没有具体范围
无法自我检查
上下文管理
长会话性能下降
无关信息堆积
早期指令被遗忘
读心术
需要具体上下文
需要明确约束
需要指向示例
无限探索
无范围的调查
读取大量无关文件
消耗上下文窗口
| 不擅长场景 | 问题描述 | 解决方案 |
|---|---|---|
| 模糊提示 | 可能解决错误的问题 | 使用 Plan Mode 分离探索和执行 |
| 无验证标准 | 生成看起来对但实际不工作的代码 | 提供测试、截图或期望输出 |
| 长会话 | 上下文充满无关信息,性能下降 | 任务间使用 /clear,或用 SubAgent |
| 无范围探索 | 读取数百文件填满上下文 | 缩小调查范围或使用 SubAgent |
| 过长 CLAUDE.md | 重要规则被忽略 | 精简保留,只保留 Claude 无法从代码推断的内容 |
常见失败模式及修复
| 失败模式 | 描述 | 修复方法 |
|---|---|---|
| 厨房水槽会话 | 一个任务开始,问无关问题,再回到第一个任务。上下文充满无关信息 | 无关任务之间使用 /clear |
| 反复纠正 | Claude 做错了,你纠正,还是错,再纠正。上下文被失败尝试污染 | 两次纠正失败后,/clear 并写更好的初始提示 |
| 过度指定 CLAUDE.md | 文件太长,Claude 忽略一半,重要规则丢失在噪音中 | 无情精简。如果没有指令 Claude 也能做对,删除它 |
| 信任后验证差距 | Claude 生成看似合理但不处理边界情况的实现 | 始终提供验证(测试、脚本、截图)。无法验证就不要发布 |
| 无限探索 | 要求 Claude “调查"某事但不限定范围。Claude 读取数百文件填满上下文 | 缩小调查范围或使用 SubAgent,探索不消耗主上下文 |
最佳工作流程
flowchart LR
subgraph Explore["1.探索"]
A[进入 Plan Mode] --> B[读取文件回答问题]
B --> C[不做任何修改]
end
subgraph Plan["2.规划"]
C --> D[要求创建详细实现计划]
D --> E[确定需要修改的文件]
end
subgraph Implement["3.实现"]
E --> F[切换回 Normal Mode]
F --> G[按计划编码]
G --> H[验证是否符合计划]
end
subgraph Commit["4.提交"]
H --> I[要求提交并创建 PR]
end
何时跳过规划:
- 范围清晰且修复很小(修复拼写错误、添加日志行、重命名变量)
- 如果你能用一句话描述 diff,跳过规划
何时使用规划:
- 不确定方法时
- 变更涉及多个文件时
- 不熟悉被修改的代码时
上下文管理技巧
| 技巧 | 说明 |
|---|---|
频繁使用 /clear |
无关任务之间重置上下文窗口 |
| 使用 SubAgent 调查 | 让 SubAgent 探索代码库,只返回摘要,不消耗主上下文 |
手动压缩 /compact |
可以指定指令如 /compact 关注 API 变更 |
| 使用 Git Worktree | 并行运行多个 Claude 会话,完全隔离 |
| 会话恢复 | 使用 claude --continue 或 --resume 继续之前的会话 |
| 会话命名 | 使用 /rename 给会话起描述性名称,便于后续查找 |
7. Q&A & 资源汇总
常见问题
Q: Claude Code 和 Claude Web 如何选择?
日常问答、调研用 Web;涉及代码、文件操作用 Claude Code。
Q: MCP Server 如何自定义开发?
参考官方 MCP SDK,实现 Tool 接口。使用 JSON-RPC 2.0 协议。
Q: Skills 和 Hook 的区别?
Skills 是主动调用的工作流模板;Hook 是被动触发的自动化脚本。
Q: SubAgent 和主 Agent 有什么区别?
SubAgent 有独立上下文,可以并行执行;完成后结果汇总给主 Agent。
Q: 如何避免上下文窗口耗尽?
- 限制同时启用的 MCP 数量(<10个)
- 使用 strategic-compact hook 在逻辑间隔压缩
- 对于长任务使用后台 SubAgent
Q: 如何在多个项目间共享配置?
用户级配置放
~/.claude/;项目级配置放项目根目录CLAUDE.md。
快速开始
1# 1. 克隆仓库
2git clone https://github.com/affaan-m/everything-claude-code.git
3
4# 2. 复制代理
5cp everything-claude-code/agents/*.md ~/.claude/agents/
6
7# 3. 复制规则
8cp everything-claude-code/rules/*.md ~/.claude/rules/
9
10# 4. 复制命令
11cp everything-claude-code/commands/*.md ~/.claude/commands/
12
13# 5. 复制技能
14cp -r everything-claude-code/skills/* ~/.claude/skills/
15
16# 6. 配置 Hooks (复制到 settings.json)
17# 7. 配置 MCP (复制需要的到 ~/.claude.json)
资源链接
| 资源 | 链接 |
|---|---|
| Claude Code 官方文档 | https://code.claude.com/docs/en/overview |
| SubAgent 文档 | https://code.claude.com/docs/en/sub-agents |
| Hooks 文档 | https://code.claude.com/docs/en/hooks |
| Skills 文档 | https://code.claude.com/docs/en/skills |
| MCP 文档 | https://code.claude.com/docs/en/mcp |
| Plugins 文档 | https://code.claude.com/docs/en/plugins |
| MCP 协议规范 | https://modelcontextprotocol.io |
| 推荐项目 GitHub | https://github.com/affaan-m/everything-claude-code |
联系方式
- Twitter: @NoPanic
本文档使用 Claude 辅助生成