Claude Workflow Guide

Posted by NoPanic on Sat, Jan 24, 2026

Claude 效率全家桶:从浏览器到终端的 AI 工作流

一个重度用户的日常实践分享

文档说明:本文档中的原理部分基于 Claude Code 官方文档整理。官方文档参考:


目录

  1. Claude Web 端
  2. Claude Chrome 插件
  3. Claude Code(核心)
  4. 资源详解
  5. 效率工具推荐
  6. Q&A & 资源汇总

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

工作原理说明:

  1. 输入解析:Claude 首先分析用户输入,判断是否需要外部信息(联网搜索或文件内容)
  2. 上下文构建:将用户问题、上传文件、搜索结果整合为完整上下文
  3. 推理生成:基于 Transformer 架构进行多轮推理,生成响应
  4. 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

操作步骤

  1. 准备阶段

    • 将简历上传至 Claude Web 进行优化
    • 根据目标岗位 JD 调整关键词
  2. 自动填写

    • 打开招聘网站职位页面
    • 插件识别表单字段
    • 自动填充个人信息
    • 用户确认后提交

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 sonnetopushaikuinherit(默认)
permissionMode defaultacceptEditsdontAskbypassPermissionsplan
skills 要预加载的技能列表
hooks 生命周期钩子

SubAgent 存储位置与优先级

位置 作用域 优先级 用途
--agents CLI 参数 当前会话 1(最高) 快速测试、自动化
.claude/agents/ 项目 2 团队协作(提交到 git)
~/.claude/agents/ 用户 3 个人、跨项目
Plugin agents/ 目录 插件 4(最低) 通过插件分发

前台 vs 后台执行

前台执行(默认):

  • 阻塞主对话
  • 权限提示传递给用户
  • 完全交互式

后台执行

  • 并发运行
  • 继承父权限,自动拒绝未授权操作
  • MCP 工具不可用
  • 触发方式:使用 run_in_background=trueCtrl+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)
  • 权限继承:继承父级权限上下文,但可覆盖模式
  • 工具限制:通过 toolsdisallowedTools 和 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,每个项目启用 <105- 使用 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 类型:ExplorePlangeneral-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(只读)、Plangeneral-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 命令 Hookstype: "command") 执行 shell 脚本进行确定性规则检查:

1{
2  "type": "command",
3  "command": "/path/to/script.sh",
4  "timeout": 60
5}

2. 提示 Hookstype: "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|WriteNotebook.*
  • 通配符:* 匹配所有工具

常用工具匹配器

匹配器 匹配目标
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 函数。测试用例:[email protected] 为 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: 如何避免上下文窗口耗尽?

  1. 限制同时启用的 MCP 数量(<10个)
  2. 使用 strategic-compact hook 在逻辑间隔压缩
  3. 对于长任务使用后台 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

联系方式


本文档使用 Claude 辅助生成