Claude Code常见名词扫盲

---

钩子(hook)

1. 明确钩子的使用场景

钩子类型	适合做什么	不适合做什么
PreToolUse	• 危险命令前二次确认 • 自动添加提醒（如tmux） • 参数校验	• 执行耗时操作（会拖慢响应） • 修改工具输入（容易出错）
PostToolUse	• 格式化输出结果 • 记录操作日志 • 自动补充后续操作	• 做复杂判断（上下文已结束） • 抛错误（可能中断流程）
UserPromptSubmit	• 检查消息是否合规 • 自动补充上下文	• 做耗时处理 • 频繁触发外部API
Stop	• 自动保存对话 • 触发后续自动化流程	• 做UI交互（无法返回结果）

4. 实用示例：防止误删文件

{
  "PreToolUse": [
    {
      "matcher": "tool == \"Bash\" && tool_input.command matches \"rm -rf\"",
      "hooks": [
        {
          "type": "command",
          "command": "echo '[⚠️ 安全提醒] 检测到 rm -rf 命令，请确认删除路径正确' >&2"
        }
      ]
    }
  ]
}

5. 快速创建钩子的方法

不用手写 JSON，直接在 Claude Code 里说：

/hookify 每次我执行 git push 之前，提醒我先运行测试

它会自动生成配置。

---

核心原则：钩子应该轻量、快速、单一职责。复杂的逻辑应该做成技能（skills）而不是钩子。

子代理（Subagents）

可以被委派任务并自主使用技能（skills）。它们还可以通过特定的工具权限进行沙盒化隔离。

# 子代理结构示例
~/.claude/agents/
  planner.md           # 功能实现规划
  architect.md         # 系统设计决策
  tdd-guide.md         # 测试驱动开发
  code-reviewer.md     # 质量/安全审查
  security-reviewer.md # 漏洞分析
  build-error-resolver.md
  e2e-runner.md
  refactor-cleaner.md

为每个子代理配置允许的工具、MCP 和权限，以实现适当的权限范围限定。

---

子代理(sub-agent)

1. 明确职责边界

子代理类型	职责	应配置的工具
planner	拆解任务、制定步骤	Read（查看代码）、Glob（搜索文件）
code-reviewer	代码审查、质量检查	Read、Grep（不赋予写入权限）
security-reviewer	安全漏洞扫描	Read、Grep（只读）
build-error-resolver	解决编译错误	Read、Bash（构建命令）、Write（修复代码）
e2e-runner	运行端到端测试	Bash（测试命令）、Read（日志）

2. 子代理配置文件示例

~/.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 代码审查专家，关注代码质量和最佳实践
tools:
  - Read
  - Grep
  - Glob
permissions:
  - read-only: true
---

你是一个代码审查专家。审查以下方面：
1. 代码可读性和命名规范
2. 错误处理是否完善
3. 是否有潜在的性能问题
4. 是否遵循项目约定

只输出审查意见，不要修改代码。

3. 子代理 vs 技能（Skills）的区别

特性	子代理（Subagent）	技能（Skills）
执行方式	独立运行，自主决策	被主代理调用执行
工具权限	可独立配置，沙盒化	继承主代理权限
适用场景	需要专注、隔离的任务	可复用的能力模块
复杂度	复杂工作流	相对单一功能

4. 设计原则

• 单一职责：一个子代理只做一件事
• 最小权限：只授予完成任务必需的工具
• 输出结构化：便于主代理理解和使用结果
• 可测试：可以单独验证子代理的行为

5. 实用工作流

# 典型的多子代理协作流程
主代理 → planner（拆解任务）
       ↓
   code-reviewer（审查现有代码）
       ↓
   architect（设计方案）
       ↓
   tdd-guide（编写测试）
       ↓
   build-error-resolver（处理构建错误）

核心原则：子代理应该像微服务一样——独立、专注、可组合。通过合理的权限隔离，让每个子代理在安全的沙盒中完成特定任务。

规则与记忆

您的 .rules 文件夹存放着 .md 文件，其中包含 Claude 始终遵循的最佳实践。有两种方式：

• 单一 CLAUDE.md – 所有规则放在一个文件中（用户级或项目级）
• Rules 文件夹 – 按关注点分组的模块化 .md 文件

~/.claude/rules/
  security.md      # 禁止硬编码密钥，验证输入
  coding-style.md  # 不可变性，文件组织结构
  testing.md       # TDD 工作流，80% 覆盖率
  git-workflow.md  # 提交格式，PR 流程
  agents.md        # 何时委派给子代理
  performance.md   # 模型选择，上下文管理

规则示例：

• 代码库中不使用 emoji
• 前端避免使用紫色调
• 部署前必须测试代码
• 优先使用模块化代码而非巨型文件
• 绝不提交 console.log

---

规则(rules)

1. 单一文件 vs 文件夹，如何选择？

方式	适用场景	优点	缺点
CLAUDE.md	项目简单、规则少（<20条）	简单直观，一目了然	规则多了难维护
rules/ 文件夹	项目复杂、多人协作	模块化，便于分工维护	需要组织管理

2. 规则文件的推荐结构

# 规则文件名：coding-style.md

## 适用范围
所有代码文件

## 规则列表

### 命名规范
- 变量使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 文件名使用 kebab-case

### 代码组织
- 单个文件不超过 300 行
- 函数不超过 50 行
- 相关功能放在同一目录

### 注释要求
- 公共 API 必须有 JSDoc 注释
- 复杂逻辑必须有行内注释

3. 撰写有效规则的原则

✅ 具体可执行

❌ "写高质量的代码"
✅ "单个函数不超过 50 行，圈复杂度不超过 10"

✅ 明确边界

❌ "尽量使用 TypeScript"
✅ "所有新增代码必须使用 TypeScript，禁止使用 any"

✅ 有验证方式

❌ "注意性能"
✅ "API 响应时间 P99 < 200ms，超过需提供 benchmark 报告"

4. 规则优先级

优先级	位置	说明
1（最高）	项目/.claude/rules/	项目特定规则
2	项目/CLAUDE.md	项目通用规则
3	~/.claude/rules/	用户全局规则
4（最低）	~/.claude/CLAUDE.md	用户全局规则

规则合并：多个规则文件会合并生效，冲突时按优先级覆盖。

5. 实用规则示例

~/.claude/rules/git-workflow.md:

## Git 提交规范

### 提交信息格式
<type>(<scope>): <subject>

类型(type):
- feat: 新功能
- fix: 修复bug
- docs: 文档
- style: 格式
- refactor: 重构

示例:
feat(auth): 添加双因素认证
fix(api): 修复超时处理逻辑

### PR 要求
- 至少 1 人 approve
- CI 全部通过
- 变更行数 > 500 需额外说明原因

~/.claude/rules/security.md:

## 安全规则

### 禁止事项
- 禁止在代码中硬编码密钥、token、密码
- 禁止使用 eval() 执行动态代码
- 禁止在日志中打印敏感信息（密码、token）

### 强制要求
- 所有用户输入必须验证和转义
- 依赖库更新前检查 CVE 漏洞
- 使用参数化查询防止 SQL 注入

6. 维护建议

• 定期审查：每月清理过时或无效的规则
• 版本控制：项目级规则纳入 Git 管理
• 渐进式添加：遇到重复性问题时再补充规则，避免预先定义过多
• 团队共识：重要规则需要团队讨论确认

---

核心原则：规则是团队的契约，不是束缚。好的规则应该降低认知负担，让 Claude 和团队成员都能一致、高效地工作。

插件（Plugins）

插件将工具打包，便于安装，无需繁琐的手动配置。一个插件可以是技能（skill）+ MCP 的组合，也可以是钩子/工具的集合。

安装插件：

# 添加插件市场
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep

# 打开 Claude，运行 /plugins，找到新市场，从那里安装

显示新安装的 Mixedbread-Grep 市场

---

LSP 插件：如果您经常在编辑器外运行 Claude Code，LSP 插件尤其有用。语言服务器协议（Language Server Protocol）让 Claude 能够提供实时的类型检查、跳转到定义和智能补全，无需打开 IDE。

# 已启用的插件示例
typescript-lsp@claude-plugins-official  # TypeScript 智能支持
pyright-lsp@claude-plugins-official     # Python 类型检查
hookify@claude-plugins-official         # 对话式创建钩子
mgrep@Mixedbread-Grep                   # 比 ripgrep 更好的搜索

与 MCP 相同的警告：注意您的上下文窗口。

---

插件(plugins)

1. 常用插件类型与用途

插件类型	示例	解决的问题
LSP 插件	typescript-lsp, pyright-lsp	编辑器外获得 IDE 级代码理解能力
工具增强	mgrep	更强的搜索能力（语义搜索 vs 正则匹配）
快捷创建	hookify	用自然语言创建钩子，不用写 JSON
MCP 集成	各种 MCP 服务器	连接外部数据源、数据库、API

2. 插件管理流程

# 1. 查看已安装的插件市场
claude plugin marketplace list

# 2. 添加新市场
claude plugin marketplace add <repo-url>

# 3. 更新市场中的插件
claude plugin marketplace update

# 4. 在 Claude 中管理插件
/plugins  # 交互式界面，启用/禁用/配置插件

3. LSP 插件的价值场景

场景	无 LSP 插件	有 LSP 插件
重构变量名	手动搜索替换，易遗漏	精准重命名，自动更新所有引用
查找函数定义	文本搜索，可能匹配注释/字符串	跳转到实际定义，支持跨文件
类型错误	运行时才发现	编码时实时提示
自动补全	基于文本推测	基于类型系统精确补全

4. 插件配置示例

.claude/plugins/config.json:

{
  "plugins": {
    "typescript-lsp": {
      "enabled": true,
      "config": {
        "tsconfigPath": "./tsconfig.json",
        "diagnostics": true
      }
    },
    "mgrep": {
      "enabled": true,
      "config": {
        "maxResults": 50,
        "caseSensitive": false
      }
    }
  }
}

5. 插件选择原则

• 按需安装：只装项目真正需要的插件，不要贪多
• 优先官方：@claude-plugins-official 的插件更稳定
• 关注上下文：LSP 插件会消耗较多上下文 token，按需启用
• 团队同步：团队项目应统一插件配置，避免环境差异

6. 插件 vs MCP vs 技能 vs 钩子

概念	定位	关系
插件	打包分发方式	可以包含 MCP、技能、钩子、工具的集合
MCP	外部工具/数据源连接	可以被插件打包
技能	可复用的能力模块	可以被插件打包
钩子	事件触发的自动化	可以被插件打包
子代理	自主任务执行者	通常是规则文件，不通过插件分发

7. 上下文窗口管理

⚠️ 重要警告：每个插件都可能向上下文注入内容，过多插件会：

• 快速消耗上下文 token
• 降低响应速度
• 可能导致 Claude 遗漏关键信息

管理策略：

# 查看当前上下文使用情况
/context

# 临时禁用某个插件
/plugins disable mgrep

# 按项目启用插件
# 在项目 .claude/plugins.json 中指定只启用特定插件

---

核心原则：插件是 Claude Code 的扩展机制，让您能按需组装能力。但要像管理手机应用一样管理插件——只装需要的，定期清理不用的，避免上下文臃肿。