6. 配置你的环境

🟡 进阶 | 官方最佳实践 #4：环境配置是长期杠杆——投入一次，每次会话都受益。
本章是全文最长的一章，因为环境配置涵盖 CLAUDE.md、权限、CLI 工具、MCP、Hooks、Skills 和子代理。这些配置一旦就绪，会在之后的每次会话中持续发挥作用。

编写有效的 CLAUDE.md 🟢

CLAUDE.md 是一个特殊文件，Claude 在每次会话开始时读取它。写入 Bash 命令、代码风格、工作流规则等Claude 无法从代码中推断的信息。

什么该写，什么不该写

该写 ✅	不该写 ❌
Claude 猜不到的 Bash 命令	Claude 读代码就能知道的信息
与默认不同的代码风格规则	标准语言规范（Claude 已知）
测试指令和首选测试框架	详细的 API 文档（链接即可）
仓库约定（分支命名、PR 格式）	频繁变化的信息
项目特有的架构决策	长篇教程或解释
开发环境怪癖（必需的环境变量）	逐文件的代码库描述
常见陷阱和非显而易见的行为	“写干净的代码”之类的废话

格式自由但保持精炼，例如：

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, not the whole test suite, for performance

CLAUDE.md 的检验标准

对每一行问自己：“如果删掉这行，Claude 会犯错吗？” 如果不会，就删掉它。

臃肿的 CLAUDE.md 会导致 Claude 忽略你真正重要的指令。如果 Claude 反复不遵守某条规则，CLAUDE.md 可能太长了，规则被淹没了。像对待代码一样对待 CLAUDE.md——出问题时审查它、定期修剪、通过观察 Claude 行为来测试变更。

分层加载机制 🟡

CLAUDE.md 文件可以放在多个位置，自动按层级加载：

优先级	层级	位置	管理者	加载时机
最高 🔴	企业托管策略	/Library/…/ClaudeCode/CLAUDE.md	IT/DevOps	启动时，不可覆盖
↓	项目级	./CLAUDE.md 或 .claude/CLAUDE.md + .claude/rules/*.md	团队（Git）	启动时自动
↓	项目级（个人）	./CLAUDE.local.md	个人（gitignore）	启动时自动
↓	用户级	~/.claude/CLAUDE.md + ~/.claude/rules/*.md	个人	启动时自动
最低	自动记忆	~/.claude/projects//memory/MEMORY.md	Claude 自动	前 200 行自动
按需	子目录	任意子目录的 CLAUDE.md	团队	Claude 访问该目录时

优先级规则：

• 企业策略不可覆盖
• 更具体的指令优先——项目级覆盖用户级
• 所有层级累加贡献内容
• 子目录 CLAUDE.md 按需加载（只在 Claude 访问该目录的文件时加载）

模块化 rules/ 目录 🟡

对大型项目，使用 .claude/rules/ 组织规则：

.claude/rules/
├── code-style.md        # 代码风格
├── testing.md           # 测试规范
├── security.md          # 安全要求
├── frontend/
│   ├── react.md         # React 特定规则
│   └── styles.md        # 样式规范
└── backend/
    ├── api.md           # API 设计
    └── database.md      # 数据库规范

规则文件支持通过 YAML frontmatter 限定作用路径：

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
  - "src/**/*.{ts,tsx}"       # brace expansion：同时匹配 .ts 和 .tsx
---

# API 开发规范
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式

用户级 rules/：~/.claude/rules/ 下的规则应用于你所有项目，优先级低于项目级 .claude/rules/。适合存放个人编码偏好、通用工作流等。

Symlinks 共享规则：rules/ 目录支持符号链接，可跨项目复用规则文件：

# 链接共享规则目录
ln -s ~/shared-claude-rules .claude/rules/shared
​
# 链接单个规则文件
ln -s ~/company-standards/security.md .claude/rules/security.md

@ 导入语法 🟡

CLAUDE.md 支持通过 @ 语法导入其他文件：

# 项目概览见 @README.md，可用命令见 @package.json

# 额外指令
- Git 工作流：@docs/git-instructions.md

规则：

• 支持相对路径和绝对路径
• 导入可递归，最大深度 5 层
• 代码块中的 @ 不会触发导入
  - 注意：@ 导入会把被引用文件的完整内容拉入上下文。避免导入大文件，改为让 Claude 按需读取

自动记忆（Auto Memory）🟡

除了手动编写的 CLAUDE.md，Claude 还有自动记忆系统：

~/.claude/projects/<project>/memory/
├── MEMORY.md              # 索引文件（前 200 行自动加载）
├── debugging.md           # 调试模式笔记
└── api-conventions.md     # API 设计决策

project 由 git 仓库根路径决定——同一 repo 的子目录共享同一个 memory 目录；非 git 项目按工作目录区分。

• Claude 在会话中自动记录有用信息
• MEMORY.md 的前 200 行在每次会话启动时注入系统提示；其余 topic 文件（如 debugging.md）不自动加载，Claude 按需读取
• 使用 /memory 命令可在编辑器中直接编辑
• 你可以主动让 Claude 记住信息："记住我们使用 pnpm 而不是 npm"
• Worktree 隔离：Git worktrees 各自拥有独立的 memory 目录，互不影响（与 9.5 Worktree 并行开发配合使用）

关闭 Auto Memory（默认开启）：

方式	配置	作用范围
/memory 菜单	交互式开关	当前用户
用户设置	~/.claude/settings.json 中 “autoMemoryEnabled”: false	所有项目
项目设置	.claude/settings.json 中 “autoMemoryEnabled”: false	当前项目
环境变量	CLAUDE_CODE_DISABLE_AUTO_MEMORY=1	优先级最高，覆盖以上所有

CI/CD 环境建议用环境变量关闭，避免自动记忆污染 runner。

三大记忆系统对比

Claude Code 有三套独立的记忆机制，各有适用场景：

维度	CLAUDE.md	Auto Memory	Session Memory
存储位置	项目根目录 / ~/.claude/	~/.claude/projects//memory/	会话内存（不持久化）
谁来写	人工编写，提交到 Git	Claude 自动记录	Claude 会话中自动管理
作用范围	团队共享（项目级）或个人全局	个人 + 项目级	仅当前会话
加载方式	每次会话自动注入系统提示	MEMORY.md 前 200 行自动注入；其余文件按需读取	始终在上下文中
典型内容	编码规范、项目架构、团队约定	调试经验、个人偏好、项目特有模式	当前任务的中间状态
适合存放	“团队所有人都该知道的”	“我个人反复遇到的”	“这次任务需要的”

选择原则：团队规范 → CLAUDE.md；个人经验 → Auto Memory；临时上下文 → 自然语言告诉 Claude。

Auto Memory 最佳实践

1. 保持 MEMORY.md 精简：前 200 行是”黄金区域”，每次会话自动加载。放最重要的索引信息，详细内容拆到 topic 文件
2. 语义化组织 topic 文件：按主题而非时间组织——debugging.md、api-conventions.md 比 day1.md、day2.md 更有用
3. 定期清理过时记忆：项目演进后旧记忆可能误导 Claude。用 /memory 定期审查，删除不再适用的内容
4. 主动引导记忆：遇到 Claude 反复犯同一个错时，直接说 "记住：这个项目的测试必须用 vitest 而不是 jest"
5. Worktree 隔离意识：每个 Git worktree 有独立的 memory 目录（见 9.5）。如果在 worktree 中积累了有价值的记忆，记得迁移回主 worktree

/memory 命令完整功能

/memory 不只是编辑器——它是 Auto Memory 的管理中心：

功能	说明
编辑 MEMORY.md	在系统编辑器中打开，直接修改自动记忆内容
查看加载状态	显示当前会话加载了哪些记忆文件及其来源路径
开关 Auto Memory	交互式切换当前用户的 Auto Memory 启用/禁用状态
查看记忆目录	显示 ~/.claude/projects//memory/ 的完整路径和文件列表

💡 调试技巧：当 Claude 的行为不符合预期时，先运行 /memory 查看加载了哪些文件——问题可能出在过时的自动记忆覆盖了 CLAUDE.md 的规则。

使用强调语法提高遵从度

# 重要规则
- **IMPORTANT**: 所有 API 响应必须包含 `request_id` 字段
- **YOU MUST**: 在提交前运行 `npm run typecheck`
- **NEVER**: 不要修改 migrations/ 目录下的已有文件

Boris Pro Tip B5：Boris 的做法是让团队共同维护 CLAUDE.md，提交到 Git，像维护代码一样维护它。当 Claude 犯错时，他会让 Claude 自己更新 CLAUDE.md："@claude 更新 CLAUDE.md，添加这条规则以避免这个错误再次发生"。这让规则库随着团队经验自然增长。

进阶做法：当项目知识超出 CLAUDE.md 的合理长度时，可拆分到 notes/ 目录，由 CLAUDE.md 引用。例如：在 CLAUDE.md 中写 详细的 API 约定见 @notes/api-conventions.md，保持主文件精简的同时让 Claude 在需要时按需读取深度知识。

CLAUDE.md 模板集 🟢

最小可用模板

# 构建
- 安装：`npm install`
- 测试：`npm test`
- Lint：`npm run lint`

# 规范
- TypeScript strict 模式
- 提交消息使用 Conventional Commits

通用项目模板

# 项目：[项目名]
[一句话描述]。技术栈：[列出关键技术]。

# 构建与测试
- 安装：`pnpm install`
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 测试全部：`pnpm test`
- 测试单个：`pnpm test -- path/to/test`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`

# 代码规范
- 使用 ES modules（import/export）
- 函数参数 >3 个时使用对象参数
- 错误处理使用 AppError 类（@src/lib/errors.ts）
- API 路径 kebab-case，JSON 属性 camelCase

# 架构
- 状态管理：Zustand（不是 Redux）
- ORM：Drizzle（不是 Prisma）
- API：tRPC

# 工作流
- **IMPORTANT**: 修改代码后运行 `pnpm typecheck`
- **NEVER**: 不要修改 migrations/ 下的已有文件
- 提交遵循 Conventional Commits

# 压缩指令
When compacting, preserve:
- 修改过的文件完整列表
- 测试命令和结果
- 未完成的任务

前端项目模板

# 构建命令
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`
- 测试：`pnpm test`（Vitest）
- E2E：`pnpm e2e`（Playwright）

# 代码规范
- 函数式组件 + hooks
- Tailwind CSS（不用 CSS modules）
- 导入顺序：React → 第三方 → 本地 → 类型 → 样式

# 组件结构
- 页面：`src/app/`（Next.js App Router）
- 组件：`src/components/`
- 参考：`src/components/ui/Button.tsx`

# 测试
- 优先运行单个测试文件
- UI 变更后截图对比验证

配置权限 🟡

默认情况下，Claude Code 对可能修改系统的操作请求权限。这很安全但频繁打断你。

权限允许列表

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git commit *)",
      "Bash(git push *)"
    ],
    "ask": [
      "Bash(git push --force *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)",
      "Bash(rm -rf *)"
    ]
  }
}

![[Pasted image 20260304162629.png]]

deny 优先 → 然后 ask → 然后 allow → 首次匹配生效。

沙箱隔离

沙箱提供 OS 级别的文件系统和网络隔离：

/sandbox

沙箱定义的是边界，而非绕过所有检查。启用沙箱后 Claude 可以更自由地工作。

Boris Pro Tip B6：Boris 使用 /permissions 预批准安全的常用命令（如 lint、test、git 操作），而不是用 --dangerously-skip-permissions 跳过所有权限。他的原则是：预批准而非跳过权限——前者是有意识的安全决策，后者是关闭安全门。

权限模式

模式	说明	切换方式
default	标准权限检查	默认
acceptEdits	自动接受文件编辑	Shift+Tab
plan	只读模式	Shift+Tab / –permission-mode plan
dontAsk	自动拒绝未允许的工具	CLI 参数
bypassPermissions	跳过所有检查	–dangerously-skip-permissions（强烈建议仅在沙箱/隔离环境中使用）

使用 CLI 工具 🟢

CLI 工具是与外部服务交互最节省上下文的方式。

# Claude Code 直接调用已安装的 CLI
用 gh 创建一个 PR
用 aws s3 ls 查看桶列表
用 sentry-cli 查看最近的错误

Claude 也善于学习不熟悉的 CLI 工具：

用 'foo-cli-tool --help' 学习 foo 工具的用法，然后用它完成 A、B、C

为什么 CLI 优于 MCP：CLI 工具无常驻上下文成本，只在调用时产生输出。而 MCP 服务器的工具定义默认常驻占用上下文空间（新版本的 Tool Search 机制可延迟加载，但仍建议控制 MCP 工具数量）。

配置 MCP 服务器 🟡

MCP（Model Context Protocol）让 Claude 连接外部数据源——Notion、Figma、数据库等。

MCP 架构速览

MCP 基于三个角色协作：

角色	位置	职责	示例
Host（宿主）	中心编排器	管理连接、路由请求	Claude Code
Client（客户端）	连接器	1:1 会话管理、协议翻译、安全边界	每个 Server 一个内部实例
Server（服务器）	能力提供方	暴露 Tools / Resources / Prompts	GitHub Server, Notion Server

MCP Server 提供三种能力：

能力类型	说明	示例
Tools（行动能力）	AI 可执行的操作	create_issue、query_database
Resources（参考数据）	AI 可引用的数据	@github:issue://123
Prompts（工作流模板）	封装好的提示词	/mcp__github__list_prs

安全模型：AI 模型永远不接触 API Key/Token。凭证由 Host 在运行时通过环境变量注入。

少即是多原则

每个 MCP 服务器都向上下文中添加工具定义，默认即使空闲也占用空间（新版 Tool Search 机制可延迟加载超阈值的工具，但仍建议主动控制数量）。
✅ 推荐做法：
- CLI 优先：能用 gh、aws、gcloud 完成的，不用 MCP
- 按需启用：只添加确实需要的 MCP 服务器
- 定期审计：用 /mcp 查看并禁用未使用的服务器
- 用 /context 监控：了解每个 MCP 服务器的上下文消耗

❌ 避免做法：

• 一次性添加十几个 MCP 服务器
• 安装后不管——默认空闲也占上下文空间

添加服务器

claude mcp add <server-name> -- <command>

配置文件

// .mcp.json（项目级）
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

位置	作用域
.mcp.json（项目根目录）	项目级，所有协作者
~/.claude.json	用户级，所有项目

配置 Hooks 🟡

Hooks 在 Claude 工作流的特定节点自动执行脚本。与 CLAUDE.md 中的建议性指令不同，Hooks 是确定性的，保证操作一定发生。

Hooks vs CLAUDE.md 规则

维度	CLAUDE.md 规则	Hooks
驱动模型	建议性（AI 可能忽略）	事件驱动，确定性执行
类比	团队规范文档	自动化传感器
执行保证	不保证	退出码 0 = 继续，退出码 2 = 阻止（限可阻止事件）
适用场景	代码风格、架构决策	格式化、保护文件、通知、验证
经验法则	“Claude 应该做”	“必须发生”

Hook 事件流程

![[Pasted image 20260304163210.png]]

核心事件类型

事件	触发时机	典型用途
SessionStart	会话开始或恢复	注入上下文、初始化环境
UserPromptSubmit	提交提示词后	预处理或验证输入
PreToolUse	工具调用前	阻止危险操作
PostToolUse	工具调用后	自动格式化、运行 lint
Notification	需要注意时	桌面通知
Stop	Claude 完成响应	验证任务完成度
PreCompact	压缩前	注入必须保留的上下文

Hook 退出码

退出码	行为
0	操作继续。stdout 可注入上下文（仅 exit 0 时解析 JSON 输出）
2	阻止操作（仅限可阻止事件：PreToolUse、UserPromptSubmit、Stop 等）。stderr 作为反馈发送给 Claude。对于不可阻止事件（PostToolUse、Notification 等），exit 2 仅显示 stderr
其他	操作继续。stderr 记入日志

注意：exit 2 的具体行为取决于事件类型。例如 PreToolUse 中 exit 2 阻止工具调用，Stop 中 exit 2 阻止 Claude 停止（强制继续），PostToolUse 中 exit 2 仅将 stderr 显示给 Claude（工具已执行，无法阻止）。
Boris Pro Tip B7：Boris 配置了 PostToolUse Hook 在每次文件编辑后自动运行 Prettier 格式化。这保证了所有 Claude 写的代码都自动符合项目格式规范，无需在 CLAUDE.md 中写格式化规则。

实用 Hook 示例

文件编辑后自动格式化：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

阻止编辑受保护文件：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

桌面通知（macOS）：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 需要你的注意\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Stop Hook：验证任务完成度：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查所有任务是否已完成。如果没有，返回 {\"ok\": false, \"reason\": \"剩余工作描述\"}。"
          }
        ]
      }
    ]
  }
}

Claude 也可以帮你写 Hooks：

写一个 Hook，在每次文件编辑后运行 eslint
写一个 Hook，阻止对 migrations 目录的写入

运行 /hooks 可以交互式配置，或直接编辑 .claude/settings.json。

创建 Skills 🟡

Skills 是存放在 .claude/skills/ 下的可重用工作流或领域知识。与 CLAUDE.md 的全量常驻不同，Skills 采用两级加载：description 常驻（占上下文预算约 2%，用于 AI 自动发现），完整内容仅在调用时加载。设置 disable-model-invocation: true 的 Skill，description 也不会常驻。

指令 vs 技能：范式转换

注意：当前版本中，自定义 Slash Commands 已并入 Skills 体系（.claude/commands/ 作为兼容方式保留）。下表用于理解两种思维模型的区别，而非两套独立机制。

维度	Slash Commands（指令）	Skills（技能）
本质	命令式：”去做这件事”	声明式：”我是一种能力”
发起者	用户主动调用	AI 自发现匹配任务
示例	/gen-test myfile.go	“我是一个 Go 代码审查技能”
发现机制	用户记住命令名	AI 扫描技能库自动匹配
核心价值	执行效率	渐进式知识加载

关键洞察：Skills 解决的核心问题是”如何在保持上下文窗口轻量的同时提供大量专业知识”——答案是 AI 按需加载，只在需要时才读取。

SKILL.md 结构

# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---
分析并修复 GitHub Issue: $ARGUMENTS。

1. 使用 `gh issue view` 获取 Issue 详情
2. 理解问题描述
3. 搜索代码库找到相关文件
4. 实现必要的修改
5. 编写并运行测试验证修复
6. 确保代码通过 lint 和类型检查
7. 创建描述性的提交消息
8. 推送并创建 PR

团队实用 Skill/Command 创意

来自 Claude Code 团队的真实用法：

• /techdebt：每次会话结束时运行，自动发现和清理重复代码
• 上下文聚合 Skill：同步过去 7 天的 Slack、GDrive、Asana、GitHub 到一个上下文中，快速获取项目全貌
• 数据分析 Skill：封装 BigQuery / bq CLI 查询能力，团队成员直接在 Claude Code 中跑分析（Boris 说他 6 个月没写过一行 SQL）
• analytics-engineer 代理：编写 dbt 模型、审查代码、在 dev 环境测试变更

经验法则：如果一个操作你每天做超过一次，就该把它变成 Skill 或 Slash Command。
调用方式：

/fix-issue 1234

frontmatter 参数

参数	说明
name	技能名称（调用时用 /name）
description	描述（默认常驻加载到上下文用于 AI 自动发现，保持简短；设 disable-model-invocation: true 时不常驻）
disable-model-invocation	设为 true 表示需要手动调用（有副作用的工作流）
$ARGUMENTS	占位符，接收 /skill-name 后的参数

更多 Skill 示例

代码审查 Skill：

# .claude/skills/review/SKILL.md
---
name: review
description: 代码审查当前变更
---
审查当前分支相对于 main 的所有变更。

1. 运行 `git diff main --name-only` 列出变更文件
2. 逐个审查
3. 检查：安全漏洞、性能、错误处理、边界情况、风格一致性
4. 按严重度分类输出

创建 PR Skill：

# .claude/skills/pr/SKILL.md
---
name: pr
description: 创建格式化的 PR
disable-model-invocation: true
---
为当前分支创建 Pull Request。

1. `git log main..HEAD --oneline` 获取提交历史
2. `git diff main --stat` 获取变更统计
3. 编写 PR 标题和描述
4. 使用 `gh pr create` 创建
5. 输出 PR URL

Boris Pro Tip B8：Boris 的 /commit-push-pr Skill 是他每天用几十次的命令——提交、推送、创建 PR 一步到位。他认为将重复性工作流封装成 Skill 是 Claude Code 最被低估的功能之一。

⚠️ 安全提醒：Skills 可执行任意 shell 命令。安装第三方 Skill 前，务必审查 SKILL.md 中的脚本内容，确认没有恶意命令。建议结合权限系统（deny 规则）限制 Skill 的工具访问范围。

内置技能：/simplify 与 /batch 🟡

除了自定义 Skills，Claude Code 还内置了两个强大的技能（v2.1.63+），覆盖代码审查和大规模迁移两大高频场景。

/simplify —— 自动化代码审查

/simplify 是一个并行代码审查技能，会同时启动 3 个专项审查代理（subagent），从不同维度分析你最近的代码变更：

审查代理	关注点	典型发现
code reuse	重复代码、可提取的公共逻辑	“这三个文件有相似的错误处理，可提取为 handleApiError() 工具函数”
code quality	代码规范、可读性、潜在 bug	“变量命名不一致：userId vs user_id；缺少边界检查”
efficiency	性能问题、不必要的计算	“循环内重复查询数据库，可移到循环外批量获取”
![[Pasted image 20260304163353.png]]
调用方式：

# 审查所有近期变更（最常用）
/simplify
​
# 聚焦特定方面
/simplify focus on error handling patterns
/simplify check the new authentication module

最佳使用时机：

• ✅ Feature 完成后、提交 PR 前——最后一道自动化质量关卡
• ✅ Bug fix 后——确认修复没有引入新的代码异味
• ✅ 重构后——验证重构是否真的简化了代码
• ❌ 写了两行代码——杀鸡用牛刀，/simplify 适合有一定体量的变更

/simplify 不替代 linter 或团队 code review，它是补充层——关注更高层次的设计模式和代码组织，而非格式问题。

/batch —— 大规模并行迁移

/batch 是一个大规模代码库迁移技能，自动将一个高层指令分解为多个独立任务并行执行，每个任务生成独立的 PR。

三阶段工作流

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  1. 研究     │ →  │  2. 执行     │ →  │  3. 追踪     │
│  分析代码库  │    │  并行处理    │    │  汇总结果    │
│  生成任务列表│    │  每个任务独立│    │  状态看板    │
│  人工审批    │    │  独立 PR     │    │  失败重试    │
└─────────────┘    └─────────────┘    └─────────────┘

调用示例：

# 框架迁移
/batch Migrate all React class components to functional components with hooks
​
# API 版本升级
/batch Update all API calls from v2 to v3, following the migration guide in docs/v3-migration.md
​
# 全局重构
/batch Replace all console.log with structured logger from @/lib/logger

适用 vs 不适用：

✅ 适用	❌ 不适用
框架迁移（React Class → Hooks）	需要跨文件协调的重构
API 版本升级	涉及数据库 schema 变更
全局模式替换（console.log → logger）	需要人工判断的逻辑修改
依赖升级后的 breaking changes 修复	少于 5 个文件的小规模修改

💡 /batch 与 9.6 节 Fan-out 的关系：/batch 是内置的、开箱即用的批量处理方案；Fan-out 是更灵活的自定义方案。大多数批量迁移场景下，先试 /batch，如果需要自定义任务拆分逻辑或特殊的并行策略，再用 Fan-out。

/simplify vs /batch 速览

维度	/simplify	/batch
目的	代码审查——发现并修复质量问题	大规模迁移——批量变更代码库
输入	自动检测近期变更（或指定范围）	一条高层迁移指令
并行方式	3 个审查代理同时分析同一段代码	N 个执行代理各自处理不同文件/模块
输出	问题列表 + 自动修复建议	每个任务一个独立 PR
适合频率	每次 PR 前	每次大规模迁移时
难度	🟡	🔴

创建自定义子代理 🔴

子代理运行在独立的上下文窗口中，有自己的系统提示、工具访问和权限。

为什么需要子代理？

可以把主 Claude 会话想象成 CTO，子代理是各部门总监：

角色	类比	特点
主会话	CTO	全局视野，协调任务
安全子代理	安全总监	专注安全审计，有自己的知识和工具
测试子代理	QA 总监	专注测试覆盖，独立上下文
调试子代理	故障专家	专注根因分析，不受其他任务干扰

子代理的三个核心特质：

特质	解决的问题	机制
独立上下文窗口	上下文污染	独立内存空间，不读/不污染主会话
自定义系统提示	指令冲突	每个子代理有专属人格和领域知识
细粒度工具权限	权限过宽	最小权限原则（审查者只读、DevOps 可执行）

子代理配置文件

在 .claude/agents/ 下创建 Markdown 文件：

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 审查代码安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---

你是一名高级安全工程师。审查代码的：
- 注入漏洞（SQL、XSS、命令注入）
- 认证和授权缺陷
- 代码中的密钥或凭证
- 不安全的数据处理

提供具体行号引用和修复建议。

关键配置项

---
name: db-reader
description: 执行只读数据库查询
tools: Bash                        # 可用工具
model: haiku                       # 控制成本
permissionMode: dontAsk            # 自动拒绝未允许的工具
maxTurns: 10                       # 限制最大轮次
memory: user                       # 启用跨会话持久记忆
background: true                   # 在后台运行
isolation: worktree                # 在独立 worktree 中工作
---

使用子代理的技巧

• 在任何请求后追加 “use subagents”，让 Claude 投入更多算力并行处理
• 将独立子任务分配给子代理，保持主会话上下文窗口干净聚焦
• 可以通过 Hook 将权限请求路由到 Opus 审批（详见 Hooks 文档）
• 使用 /agents 可交互式管理子代理（创建、编辑、删除），无需手动编辑文件

内置子代理

子代理	模型	用途
Explore	Haiku（快速）	只读代码搜索和分析
Plan	继承	Plan Mode 下的代码库研究
general-purpose	继承	复杂多步骤任务
Bash	继承	独立上下文中执行命令

五大扩展组件对比 🟡

Claude Code 有五种扩展机制。理解它们的区别是高效配置环境的关键：

核心辨析：Slash Commands vs. Skills vs. Sub-agents

这三者看似相似，但定位和适用场景截然不同：

维度	Slash Commands	Agent Skills	Sub-agents
调用者	用户 (User)	AI 模型 (Model)	AI 模型 (Model)
调用模式	命令式 (Imperative)：”AI，执行这个！”	发现式 (Declarative)：”我声明有一种能力…”	委托式 (Delegative)：”这个问题太专业，我交给专家…”
核心作用	封装高频工作流为快捷指令	封装领域知识和能力为可发现的”知识胶囊”	封装专家”人格”，处理需要独立上下文的复杂任务
上下文	共享主会话上下文	共享主会话上下文	拥有独立的上下文窗口
发现机制	用户通过 /help 菜单或记忆发现	AI 通过语义匹配 description 自主发现	AI 通过语义匹配 description 自主委托
适合场景	确定的、重复性的、需要由人发起的任务	需要 AI 具备特定领域知识或遵循特定流程的开放式任务	需要深度思考、多步推理、且不希望污染主会话上下文的复杂独立子任务
心智模型	工具箱里的电动工具	AI 可自主查阅的”专家知识库”	可以随时召唤的”领域专家”顾问团

完整五组件对比（含 Hooks 和 MCP）

维度	Slash Commands	Skills	Hooks	子代理	MCP
触发方式	用户 /命令	AI 自发现 + /命令	事件自动触发	主代理委托	Claude 自动调用
执行保证	建议性	建议性	确定性 ✅	建议性	建议性
上下文成本	共享主上下文	按需加载	零（独立运行）	独立窗口	工具定义默认常驻（Tool Search 可延迟加载）
参数	$ARGUMENTS / $1 $2	frontmatter	JSON stdin	frontmatter	协议定义
配置位置	.claude/commands/	.claude/skills/	settings.json	.claude/agents/	.mcp.json
作用域	项目级 / 用户级	项目级 / 用户级	项目级 / 用户级	项目级 / 用户级	项目级 / 用户级

![[Pasted image 20260304163508.png]]

自定义状态栏（Status Line）🟡

状态栏显示在输入框正下方，让你在工作时随时看到关键信息——当前模型、工作目录、剩余上下文、已花费 token 等。

/statusline

运行后进入交互式配置界面，选择要显示的信息项。配置保存在 settings.json 中：

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"   // 脚本通过 stdin 接收会话 JSON 数据
  }
}

也可以直接内联命令，不写脚本文件：

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

提示：更简单的方式是运行 /statusline，用自然语言描述你想看到的信息，Claude 会自动生成配置脚本。

Boris Pro Tip B13：Claude Code 团队里每个人的状态栏配置都不一样——有人盯 token 成本，有人盯剩余上下文，有人显示当前 Git 分支。用 /statusline 找到最适合你工作习惯的组合。

![[Pasted image 20260304163541.png]]