何雨果的知识库

Appearance

ClaudeCode 完整使用流程指南 ​

2026 年 6 月更新CLI / Desktop / Remote Control

🎯 学习目标

本指南涵盖 Claude Code 从安装配置到高级多代理工作流的完整使用流程，包括 扩展思考、Chrome 浏览器自动化、Checkpoints 回滚、Skills 技能系统、隐藏实用命令（/btw、/insights、/simplify、/branch、/loop、/remote-control 等）以及 常用快捷键 等特性，助你将 AI 从简单的代码生成工具转变为可编排的智能开发团队。

⚠️ 版本与命令可用性说明

Claude Code 更新很快，本文保留了大量实践经验和社区发现。涉及隐藏命令、实验功能、模型模式、Desktop / Mobile 能力和订阅权益时，请以当前版本的 /help、claude --version、官方文档和产品内显示为准。未能在官方文档中确认的功能，不建议写入团队强制流程。

零、🧭 导读：这份指南怎么读 ​

本指南按 使用者的成长路径 组织——从"装上能跑"到"指挥一支 AI 团队"。建议第一次阅读按顺序看完前三个阶段（上手 → 日常 → 定制），后面的进阶与协作章节可以按需查阅。

学习路线图：

阶段你将学会对应章节
🧠 建立框架理解 Claude Code 怎么工作、五大原语一、心智模型
🚀 上手安装、登录、第一个任务二、安装与配置
🎯 日常项目记忆、交互模式、常用命令、快捷键三、日常流程 / 四、命令与快捷键
🛠️ 定制自定义命令、Skills、MCP、IDE、插件五、定制与扩展
🧪 进阶扩展思考、Checkpoints、隐藏命令六、进阶功能
🤖 编排子代理、并行会话、Desktop、Worktrees七、多代理协调
🔗 协作GitHub Actions、Hooks、团队配置八、团队协作
✅ 收尾最佳实践、安全、排错、速查九 / 十 / 十一

按问题快速跳转：

你想解决的问题建议先看
先搞懂它到底是什么一、心智模型
第一次安装和登录二、安装、认证与基础配置
不知道怎么向 Claude Code 下任务三、日常使用流程
想查命令、快捷键四、核心命令与快捷键
想自定义命令、Skills、接入 MCP / IDE / 插件五、定制与扩展
想用扩展思考、Checkpoints、隐藏命令六、进阶功能与隐藏命令
想配置子代理、并行会话、Desktop、Worktrees七、多代理与 Desktop 协调
想做团队协作、GitHub Actions、Hooks八、团队协作与自动化
想查最佳实践、成本、安全和排错九、最佳实践、安全与故障排查
只想快速查命令模板十、快速参考卡片

一、🧠 心智模型：理解 Claude Code 怎么工作 ​

在记忆命令之前，先建立一个框架，后面所有功能都能挂在它上面。

Claude Code 是一个 agentic（自主代理）工具： 你给它一个目标，它会在"理解上下文 → 采取行动（读文件、改代码、跑命令）→ 看反馈 → 继续"的循环里推进，直到完成。用好它，本质上是管好三件事：

  • 上下文 —— 它知道什么（记忆、文件、对话历史）
  • 原语 —— 你能给它配备哪些能力
  • 编排 —— 你如何指挥一个甚至多个它

1.1 五大 Agent 系统原语 ​

Claude Code 的全部能力可以归纳为五种"原语"。本指南后续章节其实就是逐个展开它们——先记住这张表，读到对应章节时就知道它在整体里的位置。

原语用途特点本指南对应
Memories持久化上下文自动加载三、项目记忆系统
Slash Commands快速触发操作用户驱动四、命令 / 五、自定义命令
Skills程序化知识渐进式加载五、Skills / 七、Agent Skills
Subagents隔离的专门助手独立上下文七、子代理系统
MCP Servers外部资源连接服务器执行五、MCP 集成

1.2 三个贯穿全书的核心理念 ​

上下文工程（Context Engineering）

在任务的每个步骤中，用正确的信息填充 LLM 的上下文窗口的艺术和科学。

靠 持久记忆（CLAUDE.md）、智能检索（自动上下文发现）、上下文压缩（/compact）和 上下文隔离（子代理）四种手段实现。这是用好 Claude Code 的第一性原理——详见 九、最佳实践。

规范驱动开发（Spec-Driven Development）

先规划（计划模式）→ 后执行（实现模式）。

更安全（先审查再执行）、更一致（明确规范）、可追溯（规范文档可共享）。具体做法见 三、交互模式。

多代理编排（Multi-Agent Orchestration）

开发者从编码员转变为 AI 代理的指挥家。

识别可并行化的任务、分配专门化角色、协调代理协作、管理依赖关系。这是 Claude Code 的"天花板"玩法，见 七、多代理与 Desktop 协调。

二、🚀 安装、认证与基础配置 ​

2.1 安装 Claude Code ​

Claude Code 官方推荐使用 原生安装器（Native Install）——自动后台更新、无需 Node.js。根据操作系统选择对应命令：

macOS / Linux / WSL：

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

Windows PowerShell：

powershell
irm https://claude.ai/install.ps1 | iex

安装完成后，在项目目录中启动并验证：

bash
claude            # 启动交互式会话
claude --version  # 查看版本

💡 其他安装方式

  • Homebrew（macOS）：brew install --cask claude-code
  • WinGet（Windows）：winget install Anthropic.ClaudeCode
  • Linux 包管理器：官方提供签名的 apt / dnf / apk 仓库
  • npm（可选）：npm install -g @anthropic-ai/claude-code（需 Node.js 18+）

原生安装器会在后台自动更新；Homebrew / WinGet / Linux 包管理器安装需手动升级。npm 包安装的其实是与原生安装器相同的二进制文件。不要使用 sudo npm install -g——遇到 npm 全局权限错误时应修复目录权限，而非用 sudo。

2.2 认证与登录 ​

首次运行 claude 时会引导完成初始化：

  1. 选择主题 — 选择终端主题（如深色模式）
  2. 登录账户 — 在浏览器中完成认证
  3. 终端设置 — 选择推荐的默认设置或自定义
  4. 工作区信任 — 只在项目目录中运行，避免从根目录启动

登录方式：

方式说明
Claude 订阅账户（推荐）Pro / Max / Team / Enterprise，固定月费
Claude Console（API）按使用量计费，预付额度
企业云通道Amazon Bedrock、Google Vertex AI、Microsoft Foundry

要切换账户或重新认证，在运行中的会话里输入 /login 即可。

常用诊断命令：

bash
claude              # 启动会话；首次会提示登录
claude --version    # 查看版本
claude update       # 手动应用更新（原生安装通常自动后台更新）
claude doctor       # 检查安装、更新和环境状态

📌 会话内常用入口

  • /login — 登录或切换账户
  • /status — 查看版本、模型、账户状态
  • /help — 列出当前版本可用的全部命令

2.3 使用方式与渠道 ​

官方订阅（直连）：

Claude Code 支持通过 Anthropic 官方订阅（Pro / Max 等方案）或 API Key 使用，具体价格和可用模型请以 官方定价页 为准，模型迭代较快，不在此罗列。

第三方渠道（API 中转）：

如果官方直连不便，也可以通过第三方 API 中转站使用 Claude Code：

渠道类型说明
AnyRouter公益站免费额度，适合轻度体验
PackyAPI付费中转稳定可靠，按量计费
DuckCoding付费中转面向开发者的中转服务

⚠️ 第三方渠道风险

第三方 API 中转不属于 Anthropic 官方通道。Claude Code 可能读取代码、文件内容、命令输出和项目配置；涉及公司代码、客户数据、密钥、生产日志或商业机密时，应优先使用 Anthropic 官方、组织批准的企业通道或明确受信任的私有部署。

💡 使用建议

  • 日常编码推荐使用 Sonnet 系列模型（快速高效、性价比高）
  • 复杂推理和深度规划任务可选用 Opus 系列模型
  • 第三方渠道需将 API Base URL 配置为对应中转地址

三、🎯 日常使用流程 ​

3.1 项目初始化 ​

bash
# 1. 进入项目目录
cd /path/to/your/project

# 2. 启动 Claude Code
claude

# 3. 初始化项目上下文
/init

📌 /init 命令的作用

  • 自动分析整个代码库
  • 生成 CLAUDE.md 文件（项目记忆文件）
  • 包含项目架构、技术栈、关键文件、开发命令等信息

3.2 构建项目记忆系统 ​

对应五大原语中的 Memories——它决定了 Claude 默认"知道什么"。

记忆层级结构：

text
~/.claude/CLAUDE.md          # 用户级记忆（全局偏好）
./CLAUDE.md                   # 项目级记忆（团队共享）
./memory/spec/CLAUDE.md       # 自定义模块化记忆
./memory/frontend/CLAUDE.md   # 专门领域记忆

添加记忆的方法：

方法命令说明
快捷键内容 #在句尾加 # 快速添加新记忆
命令/memory打开记忆文件编辑器
手动mkdir -p memory/frontend创建模块化记忆目录

3.3 基本交互模式 ​

这是 规范驱动开发 理念的落地。

直接对话模式（快速任务）：

适用于简单问题、快速修复、单文件编辑：

  • "修复 src/utils.ts 中的 TypeScript 错误"
  • "给 calculateTotal 函数添加注释"
  • "这个项目使用什么技术栈？"

规范驱动开发模式（复杂任务）：

  1. 切换到计划模式 — 按 Shift + Tab 或在提示中明确说明"使用计划模式"
  2. 创建项目规范 — 描述功能需求，Claude 会使用网络搜索收集信息
  3. 保存规范 — 将规范保存到 memory/spec/CLAUDE.md
  4. 执行实现 — 使用 根据 @memory/spec/CLAUDE.md 实现主页网格布局

四、⚙️ 核心命令与快捷键 ​

对应五大原语中的 Slash Commands（内置部分）。本章是"开箱即用"的命令，自己造命令见 五、定制与扩展。

4.1 斜杠命令速览 ​

上下文管理命令：

命令作用使用时机
/clear清除对话历史（释放上下文空间）开始新任务时
/compact压缩对话历史（保留关键信息）上下文过载时
/context可视化当前上下文使用情况排查上下文占用时

配置与成本命令：

命令作用
/config打开配置面板（用户/项目/本地三级配置）
/cost查看当前会话成本和持续时间
/memory编辑记忆文件
/stats查看详细的会话使用统计
/status显示版本、模型、账户状态

代理与工具管理：

命令作用
/agents管理子代理（创建、编辑、删除）
/mcp管理 MCP 服务器（外部工具集成）
/hooks管理钩子（自动化工作流）
/ide安装 VS Code / JetBrains 扩展

会话与导出命令：

命令作用
/export导出当前会话为 Markdown 文件
/resume恢复之前的会话（claude --resume）
/rewind回退对话和/或代码变更（支持分别回退）
/btw在任务执行中插入旁问，不污染上下文（并行回答）
/insights生成 HTML 使用习惯分析报告，推荐自定义命令和 Skills
/simplify三合一代码审查（代码复用 / 代码质量 / 运行效率，并行审查）
/branch将当前对话分叉为新会话（原名 /fork）
/loop定时重复执行任务（如 /loop 5m 检查部署状态）
/remote-control生成远程控制 URL，可在手机上同步操作（简写 /rc）
/model opusplan隐藏模式：规划用 Opus、执行用 Sonnet，适合 Pro 用户省额度

💡 上表后半部分（/btw、/insights、/simplify 等）为高频实用与隐藏命令，详细用法见后文「六、进阶功能与隐藏命令」。

4.2 常用快捷键 ​

以下快捷键在日常使用中可以大幅提升效率：

快捷键功能
Esc + Esc触发 /rewind 回退界面
Ctrl + V直接粘贴截图（无需先保存文件再拖入）
Ctrl + J换行（在命令行输入中插入新行）
Option + Enter换行（Mac 替代方式）
Ctrl + R搜索之前输入过的所有 Prompt 历史
Ctrl + O打开 transcript viewer，查看详细执行记录
Ctrl + B将长任务或命令转入后台
Ctrl + T显示或隐藏 task list
Ctrl + U删除整行输入
Shift + Tab切换到计划模式
Alt + T切换扩展思考开关
Alt + P不清空输入的情况下切换模型
@文件路径自动补全，用于引用文件或目录
!Shell mode，运行命令并把输出加入上下文

⚠️ Mac 用户注意

粘贴截图使用的是 Ctrl + V，不是 Cmd + V。这是 Claude Code 终端的特殊处理。

💡 Debug 利器

遇到报错时，直接截屏然后 Ctrl + V 粘贴给 Claude，让它「看图说话」，比手动复制错误信息方便得多。

五、🛠️ 定制与扩展 ​

这一章把所有"让 Claude Code 更趁手"的手段集中在一起：从造自己的命令、Skills，到接入外部工具（MCP）、IDE 和插件。对应五大原语中的 Slash Commands（自定义）、Skills 和 MCP。

5.1 自定义斜杠命令（Commands） ​

Claude Code 支持两种方式创建自定义斜杠命令：Commands（轻量）和 Skills（功能更丰富）。

Commands（简单快捷）

文件位置：.claude/commands/commit-code.md（文件名即命令名）

markdown
---
description: 生成智能 Git 提交信息
---

分析 git diff，生成简洁的提交信息。
使用用户提供的提示作为主题：$ARGUMENTS

示例输出：feat: 添加自定义命令创建功能

使用：输入 /commit-code 自定义命令功能 即可触发。

📎 高级 Command 示例（带安全控制）

文件位置：.claude/commands/smart-commit.md

markdown
---
description: 带 RAG 的智能提交
allowed-tools:
  - Bash
  - Read
  - Grep
---

# 工作流程
1. 运行 `!git status` 获取当前状态
2. 运行 `!git diff` 查看更改
3. 运行 `!git log -5 --oneline` 分析历史风格
4. 生成提交信息
5. 运行 `!git add .` 和 `!git commit -m "[生成的信息]"`

💡 说明： ! 前缀表示直接执行 bash 命令；allowed-tools 实现最小权限原则

5.2 Skills（带目录结构，支持辅助脚本） ​

文件位置：.claude/skills/smart-commit/SKILL.md

yaml
---
name: smart-commit
description: 带上下文分析的智能提交
argument-hint: "[主题描述]"
allowed-tools: Bash, Read, Grep
disable-model-invocation: true
---

# 工作流程
1. 运行 `git status` 获取当前状态
2. 运行 `git diff` 查看更改
3. 运行 `git log -5 --oneline` 分析历史风格
4. 生成提交信息
5. 运行 `git add .` 和 `git commit -m "[生成的信息]"`
📎 Commands vs Skills 对比
维度CommandsSkills
文件位置.claude/commands/<name>.md.claude/skills/<name>/SKILL.md
复杂度单文件，轻量目录结构，可附带辅助脚本
Frontmatterdescriptionname, description, allowed-tools, argument-hint, disable-model-invocation 等
上下文加载整体加载渐进式加载（先头部 ~100 tokens，触发后加载完整内容）
适用场景简单的提示模板复杂工作流、需要权限控制的任务

💡 建议： 简单任务用 Commands，需要工具权限控制或附带脚本时用 Skills。Skills 作为系统原语的完整概念（与 MCP / Subagents 的权衡）见后文「七、多代理与 Desktop 协调」。

5.3 输出样式自定义 ​

创建输出样式：

bash
# 用户级样式（全局可用）
/output-style:new
提示："使用简洁的项目符号，精炼要点"

# 项目级样式（项目专属）
/output-style:new
提示："项目级样式，所有响应格式化为 YAML，包含状态、下一步、风险字段"

样式配置文件位置：

  • 用户级：~/.claude/output-styles/minimal-bullets.md
  • 项目级：./.claude/output-styles/yaml-concise.md

5.4 自定义状态栏 ​

bash
# 基础状态栏（显示输出样式）
/statusline
提示："显示当前 output-style，使用 Python 实现，通过 uv 运行"

# 高级状态栏（显示最后提示）
/statusline
提示："显示当前会话的最后一个用户提示，读取 transcript_path，过滤命令和 AI 响应"

5.5 MCP 集成（接入外部工具） ​

对应五大原语中的 MCP Servers——把数据库、文档、浏览器等外部资源接到 Claude Code。

添加 MCP 服务器：

bash
# 示例：添加 Context7（30,000+ 库的最新文档）
claude mcp add --transport http context7 https://mcp.context7.com/mcp --scope project

# 重启 Claude Code 生效
/exit
claude

使用 MCP 工具：

💡 自动使用（通过记忆规则）

在 CLAUDE.md 中添加：

text
每次我询问关于 LangGraph 的问题时，自动使用 context7 MCP

手动调用："使用 context7 查询 Next.js 14 的最新路由功能"

5.6 IDE 集成（VS Code & JetBrains） ​

Claude Code 提供了原生的 IDE 扩展，不仅仅是简单的终端包装器。

安装：

bash
/ide
# 选择 VS Code 或 JetBrains IDE

核心功能：

  1. 内联 Diff 视图：在编辑器中实时预览 Claude 的代码更改，支持 Accept/Reject。
  2. LSP 智能感知：内置语言服务器，提供代码补全和跳转。
  3. 实时同步：IDE 中的编辑会立即反映在 Claude 的感知中。

5.7 插件系统（Plugin） ​

Claude Code 支持插件系统，可从官方和社区市场发现并安装 Skills 和 Agents。

bash
# 安装插件
/plugin install @community/git-wizard

# 添加市场源
/plugin marketplace add owner/repo

六、🧪 进阶功能与隐藏命令 ​

6.1 扩展思考模式 ​

Claude Code 支持扩展思考（Extended Thinking），允许模型花费更多时间进行深度推理，适合复杂架构设计或重构任务。

bash
# 通过 /model 命令调整思考深度（左右箭头切换 effort level）
/model

# 使用 Alt+T 快捷键切换扩展思考开关

6.2 Checkpoints 自动检查点与 /rewind ​

Claude 会在执行文件修改前自动创建 Git 检查点，任何错误都可以回滚。

/rewind 支持 代码和对话分别回退，不再只能整段一起回退：

bash
# 使用 Esc+Esc 快捷键触发 rewind 界面
/rewind

# 选择菜单中会出现四个选项：
# 1. 回退代码和对话
# 2. 回退对话但保留代码
# 3. 回退代码但保留对话
# 4. 从该点开始压缩对话（释放上下文空间）

💡 实验性开发的最佳搭档

让 Claude 试一种新方案 → 不满意 → /rewind 回退代码但保留对话 → Claude 记得刚才的讨论、知道这条路不通，可以直接换方向，不用重新解释需求。

6.3 Chrome 浏览器集成（Beta） ​

允许 Claude 控制 Chrome 进行端到端测试或网页抓取。

bash
# 启动带浏览器集成的会话
claude --chrome

6.4 YOLO 模式（高风险） ​

跳过所有权限确认（仅建议在沙箱/容器环境使用）。

bash
claude --dangerously-skip-permissions

6.5 隐藏与实验性命令详解 ​

以下命令更新频繁，部分甚至是开发团队在社交媒体上随口提到才被发现的。建议定期关注 Claude Code Changelog 获取最新功能。

⚠️ 使用前先核验

隐藏命令、实验命令和模型组合模式可能随版本变化。建议在当前会话里输入 /help 或 / 搜索命令名；如果命令不可见，不要把它写入团队强制流程。

命令稳定性说明
/btw、/rc（/remote-control）、/rewind官方文档已确认稳定功能，可放心使用
/branch（原 /fork）概念已确认，入口以版本为准会话分叉
/insights、/simplify、/loop、/model opusplan社区发现，需核验可能随版本变化，不建议写入固定团队规范

/btw — 无污染旁问 ​

在 Claude 正在执行任务时插入一个旁问，回答 不会被加入对话历史，完全不中断当前任务。

bash
# Claude 正在重构大模块，你突然想确认一个信息
/btw 这个项目的抓取流程是什么？

# Claude 会并行回答你的问题
# 回答完毕后按空格或回车即可消除该回答
# 之前的任务继续执行，对话历史干干净净

💡 为什么重要

以前在长任务中插入无关问题会造成 上下文污染——Claude 回答后重新开始干活时可能跑偏。/btw 彻底解决了这个问题，而且几乎不费 token（复用当前的提示缓存）。属于 用了就回不去 的功能。

/insights — 使用习惯分析 ​

生成一份 HTML 报告，分析你过去一个月使用 Claude Code 的习惯：最常用的命令、重复性操作模式，并推荐自定义命令和 Skills。

bash
/insights
# 生成本地 HTML 报告，内容包括：
# - 命令使用频率统计
# - 重复操作模式识别
# - 翻车/回退记录
# - 记忆优化建议
# - 自定义命令 & Skills 推荐

💡 建议每月跑一次

/insights 会让你重新认识自己的使用习惯——哪些操作可以自动化、哪些记忆规则需要调整，非常有价值。

/model opusplan — 隐藏规划模式 ​

这是一个 隐藏命令，在 /model 切换模型的菜单里并不会显示。启用后，Claude Code 会在需要复杂推理时自动使用 Opus 进行规划，然后切换到 Sonnet 进行代码执行。

bash
/model opusplan
# 规划阶段 → Opus（深度思考、理解架构和依赖）
# 执行阶段 → Sonnet（快速编码、性价比高）

⚠️ 特别适合 Pro 订阅用户

Pro 用户的 Opus 额度有限，全程 Opus 容易被限速。/model opusplan 让你把宝贵的 Opus 额度用在刀刃上（规划），具体编码交给 Sonnet，两全其美。

/simplify — 三合一代码审查 ​

输入 /simplify 后，Claude Code 会同时启动 三个并行 Agent，分别从不同角度审查你的代码改动：

Agent审查角度
Agent 1代码复用性
Agent 2代码质量
Agent 3运行效率
bash
/simplify
# 三个 Agent 并行审查 → 汇总结果 → 告诉你哪些地方可以优化
# 多余的 import、重复逻辑、可用更简洁写法替代的地方，基本都能挑出来

💡 取代 /review

/simplify 的审查质量显著优于之前的 /review 命令。建议在每次写完几个大功能更新后顺手跑一遍，相当于找了三个同事帮你同时 review。

/branch — 对话分叉（原名 /fork） ​

把当前对话分叉出一个新会话，原来的会话不受影响。适合在讨论到一半时想试另一个方向的场景。

bash
/branch
# 当前对话进度被完整保留
# 新会话从当前状态开启，可以走完全不同的方向
# 打 /fork 也能用，会自动跳到 /branch

💡 与 /rewind 的区别： /rewind 是 后悔药（回退），/branch 是 平行宇宙（分叉）。你可以 /branch 两次，两个会话各走一边，最后挑效果好的那个。

/loop — 定时循环任务 ​

让 Claude 定时重复执行某个任务，结果直接在对话上下文里，Claude 可以基于结果做后续判断。

bash
/loop 5m 检查一下部署状态
# 每 5 分钟执行一次，默认间隔 10 分钟
# 定期任务在创建 3 天后自动过期
# 最后触发一次后自我删除，防止被遗忘的循环永远运行

📌 长期运行

如果需要任务一直运行下去不过期，可以使用 Claude Code Desktop 版本。

/remote-control（/rc）— 手机远程控制 ​

生成一个 URL，用手机打开后可以完全同步操作当前的 Claude Code 会话。

bash
/rc
# 或完整命令
/remote-control

# 生成 URL → 手机打开 → 完全同步
# 手机发指令 ↔ 终端实时更新
# 代码始终在本地电脑运行，手机只是遥控器
# 文件系统、MCP、项目配置全部在本地，安全可靠

💡 随时随地 Vibe Coding

离开电脑时也能通过手机给 Claude 下指令、监控任务进度。两端可以交替使用，对话历史完全一致。

/export — 导出对话为 Markdown ​

将当前整段对话导出为一个 Markdown 文件。看似简单，但在需要保存讨论成果时非常重要。

bash
/export
# 当前对话 → 导出为 .md 文件
# 适用场景：
# - 保存与 Claude 讨论架构方案的完整推敲过程
# - 导出后作为未来的详细 context
# - 跨工具协同（如导出给 Codex 做二次分析）

七、🤖 多代理与 Desktop 协调 ​

这是 多代理编排 理念的完整落地，对应五大原语中的 Subagents 和 Skills——从指挥一个 Claude，进化到指挥一支并行工作的 AI 团队。

7.1 子代理系统 ​

📌 子代理的核心概念

  • 隔离上下文 — 每个子代理有独立的上下文窗口
  • 专用工具 — 可限制子代理的工具访问权限
  • 可重用性 — 跨项目和团队共享

创建子代理：

bash
# 启动代理创建流程
/agents

# 选择范围
# - Project（项目级，保存到 .claude/agents/）
# - User（用户级，保存到 ~/.claude/agents/）

# 生成方式
# - Generate with Claude（交互式生成）
# - Manual（手动编辑）

子代理配置文件示例（.claude/agents/code-comedy-carl.md）：

yaml
---
name: code-comedy-carl
description: 当用户说 "funny review" 时，生成幽默的代码审查
model: sonnet
tools: Read, Grep, Glob
maxTurns: 30
---

# 系统提示
你是 Code Comedy Carl，一位以幽默方式审查代码的专家。

# 审查流程
1. 读取文件
2. 分析代码质量
3. 生成幽默但有建设性的反馈
4. 包含实际改进建议

调用子代理：

方式示例
单次调用"funny review @main.py"
批量调用"创建 2 个有趣的代码审查"

常用子代理类型：

类型描述工具
代码审查员执行彻底的代码审查，检查质量、安全性、性能Read, Grep, Glob
研究员进行深度技术研究，查找文档和最佳实践WebSearch, WebFetch
测试代理生成测试用例并运行测试Read, Write, Bash
图表生成器将文本概念转换为 Mermaid 流程图Read, Write

7.2 并行会话（多 Claude 实例） ​

⚠️ 使用场景

✅ 适用任务（独立任务）：

  • 修复不同模块的不相关 bug
  • 构建独立的 UI 页面（关于页面 + 联系页面）
  • 创建独立的组件（按钮组件 + 模态框组件）

❌ 避免任务（依赖任务）：

  • 一个代理构建 API，另一个构建调用该 API 的前端
  • 相互依赖的功能（会导致契约分歧和静默失败）

实施步骤：

bash
# 终端 1
cd /path/to/project
claude
# 任务："重新设计 HookCard.tsx 组件，使其更现代、视觉吸引"

# 终端 2（同一目录）
cd /path/to/project
claude
# 任务："重新设计 page.tsx 中的 hero 区域"

💡 角色转变： 开发者从 编写代码 转变为 编排 AI 代理 — 识别可并行化的任务、确定任务依赖关系、协调多个 AI 代理的工作

7.3 专门化 AI 环境 ​

挑战： 同一目录的多个实例共享配置（输出样式会相互影响）

解决方案： 为每个专门代理创建独立目录

bash
# 创建专门化工作区
mkdir -p ~/ai-agents/frontend-expert
mkdir -p ~/ai-agents/backend-expert
mkdir -p ~/ai-agents/devops-expert

# 在每个目录中配置独立的输出样式和记忆
cd ~/ai-agents/frontend-expert
claude
/output-style:new "项目级，专注于 React 最佳实践"

💡 未来愿景

每个终端窗口 = 一个命名的 AI 专家：

  • Frontend Expert — React/Next.js 专家，详细的组件建议
  • Backend Expert — API 设计，YAML 格式输出
  • DevOps Expert — 基础设施即代码，Terraform/Docker 专家
  • Security Auditor — 安全审查，CVE 扫描

7.4 Agent Skills（代理技能） ​

📌 回到五大原语

Skills 是 一、心智模型 中提到的五大原语之一——程序化知识容器，包含指令和脚本的文件夹，用于教代理如何一致地执行特定任务。这里展开它与其他原语的权衡；如何动手创建一个 Skill 见 五、Skills。

Skills 的核心优势——渐进式加载（Progressive Disclosure）：

  • 初始时只加载 Skill 的头部信息（~100 tokens）
  • 完整指令仅在代理决定使用该 Skill 时才加载（~2K tokens）
  • 极其高效的上下文利用

目录结构与 SKILL.md 示例：

text
.claude/skills/
└── git-pushing/
    ├── SKILL.md           # Skill 定义文件
    └── smart_commit.sh    # 辅助脚本
yaml
---
name: Git Smart Push
description: Automatically generate commit messages and push to remote
---

# Git Smart Push Skill

This skill handles git operations with intelligent commit message generation.

Execution command:
!bash .claude/skills/git-pushing/smart_commit.sh $arguments

Skills vs MCP vs Subagents 对比：

维度SkillsMCPSubagents
上下文消耗极低（渐进式）较高（预先定义）独立窗口
执行位置本地，主代理线程服务器（本地/云端）隔离上下文
主要用途一致的方法论外部资源连接长周期复杂任务
灵活性较低中等较高

💡 选择建议

  • Skills — 需要一致方法论、低上下文开销的短任务
  • MCP — 需要连接外部 API、数据库、浏览器自动化
  • Subagents — 重度任务、需要隔离上下文、长周期任务

7.5 Desktop 运行模式 ​

Claude Code Desktop 提供两种截然不同的运行模式：

模式特点执行环境适用场景
Local Worktree本地执行，Git Worktree本地机器日常开发、完全控制
Default (Cloud)云端容器，GitHub 集成Anthropic 服务器并行任务、无限扩展

Local Worktree 模式：

text
你的项目目录 (/project)
    ├── .git/
    ├── src/
    └── ...
         │
         │ Claude Desktop 创建 Worktree
         ▼
worktree 目录 (/zealous-jemison)
    ├── src/  (独立分支)
    └── ...

    Claude 在此独立工作

Default (Cloud) 模式：

text
1. 授权 Anthropic 访问 GitHub
2. 云代理克隆仓库到容器
3. 执行代码工作
4. 推送提交或创建 PR
5. 像远程人类开发者一样工作

7.6 Git Worktrees 并行开发 ​

📌 为什么使用 Git Worktrees？

Git Worktrees 是多代理并行工作的"协调成本"——允许多个代理同时在不同分支工作，而不会相互干扰。

常用命令：

bash
# 创建新的 worktree（基于新分支）
git worktree add ../feature-animation feature-animation

# 创建 worktree（基于远程分支）
git worktree add ../hotfix origin/hotfix -b hotfix

# 列出所有 worktrees
git worktree list

# 删除 worktree
git worktree remove ../feature-animation

# 清理已删除 worktree 的引用
git worktree prune

优势：

  • ✅ 隔离性 — 代码更改在独立目录，主分支完全不受影响
  • ✅ 并行工作 — 多代理可同时处理不同分支
  • ✅ 干净工作流 — 无需 git stash 或多次克隆仓库
  • ✅ 灵活性 — 结果好则合并，不好则删除 worktree

7.7 三重并行开发工作流 ​

同时运行三个独立的开发工作流：

任务模式工作内容
任务 AClaude Chat（云模型）研究：搜索 GitHub hooks 仓库
任务 BLocal Worktree功能开发：添加 UI 动画
任务 CDefault（云端）远程开发：更新 Hero 区域

协调流程：

bash
# 任务 A: 在 Claude Desktop 聊天界面
找出最流行的 Claude Code hooks 开源仓库

# 任务 B: 在 Local Worktree 模式
# Claude 自动创建 worktree（如 zealous-jemison/）
为主页添加入场动画效果

# 任务 C: 在 Default（云端）模式
在 project/hookhub 分支上更新 Hero 区域

7.8 合并多代理工作 ​

步骤 1: 提交各自的工作

bash
# 在每个 worktree 中提交
cd ~/worktrees/zealous-jemison
git add . && git commit -m "feat: add entrance animations"

cd ~/worktrees/vigilant-feistel
git add . && git commit -m "feat: update hooks database"

步骤 2: 推送到 GitHub

bash
git push origin zealous-jemison
git push origin vigilant-feistel

步骤 3: 让 Claude 执行合并

text
将以下分支合并到 project/hookhub：
- zealous-jemison (动画功能)
- vigilant-feistel (数据库更新)
- anthropic-hero-design-xxx (云端 hero 更新)

请：
1. 检出 project/hookhub
2. 依次合并这些分支
3. 解决任何冲突
4. 运行测试验证

步骤 4: 验证并推送

bash
npm run dev  # 验证
git push origin project/hookhub  # 推送

7.9 Claude Code Mobile ​

📌 移动端特点

  • 通过 Claude iOS/Android 应用使用
  • 强制使用 Default（云容器）模式
  • 适合简单任务和紧急修复

移动端工作流：

text
📱 移动端发起任务
    ↓ (云容器执行)
    ↓ 克隆仓库 → 检出分支 → 执行任务 → 提交更改
    ↓
创建 PR / 推送代码
    ↓
💻 桌面端验证和修复
    ↓ 打开 PR → 检查分支 → 本地拉取 → 运行验证

⚠️ 注意事项

  • 默认云环境没有本地 MCP 或自定义 hooks
  • PR 可能默认指向错误的基础分支，需手动检查

八、🔗 团队协作与自动化 ​

8.1 GitHub Actions 自动化 ​

前置条件：

bash
# 1. 安装 GitHub CLI
brew install gh  # macOS

# 2. 认证 GitHub CLI
gh auth login

# 3. 确保在 Git 仓库目录中
cd /path/to/your/repo

安装 Claude GitHub App：

bash
# 在 Claude Code 中运行
/install-github-app

# 按照提示操作：
# 1. 在浏览器中授权 Claude GitHub App
# 2. 选择要集成的仓库
# 3. 选择工作流（@Claude issue 评论、自动代码审查）
# 4. 选择认证方式（使用订阅绑定的 token）

安装会自动创建 PR，添加以下文件：

text
.github/workflows/claude-issue-comment.yml
.github/workflows/claude-pr-review.yml

使用方式：

触发方式示例
Issue 评论在 GitHub Issue 中评论 @claude 能否修复这个 bug？
PR 评论在 Pull Request 中评论 @claude 请审查这个 PR

💡 最佳实践：提供上下文

在仓库中添加 CLAUDE.md，Claude 在执行 GitHub Actions 时会读取它，理解项目架构和约束。

bash
# 在本地项目中
claude
/init  # 生成 CLAUDE.md

# 提交并推送
git add CLAUDE.md
git commit -m "docs: 添加 Claude AI 项目上下文"
git push

8.2 钩子（Hooks）自动化 ​

钩子类型：

时机说明
PreToolUse工具调用执行前（可阻止）
PostToolUse工具调用成功后
SessionStart会话开始或恢复时
StopClaude 完成回复时
SubagentStop子代理完成时

配置位置： 在 settings.json 中配置（非独立文件）

json
// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-rm.sh",
            "timeout": 60
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $FILE && eslint --fix $FILE"
          }
        ]
      }
    ]
  }
}
📎 高级用法：Prompt 类型钩子

除了 command 类型，还支持 prompt（LLM 评估）和 agent（子代理验证）：

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if this edit is safe: $ARGUMENTS",
            "model": "haiku",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

九、✅ 最佳实践、安全与故障排查 ​

9.1 上下文工程原则 ​

一、心智模型 提到的"上下文工程"在这里给出可操作的策略。

分层记忆策略：

text
~/.claude/CLAUDE.md          # 个人偏好、代码风格
./CLAUDE.md                   # 项目架构、团队规范
./memory/spec/CLAUDE.md       # 功能规范
./memory/frontend/CLAUDE.md   # 领域知识（按需加载）

原则：

  • 保持记忆文件简洁（避免过载上下文）
  • 使用模块化目录结构
  • 通过 @ 语法手动加载特定记忆

动态上下文管理：

命令使用时机效果
/compact长对话时压缩历史，保留关键决策和信息，节省 token
/clear开始新任务时释放完整上下文空间，保留项目记忆

⚠️ 避免上下文污染

  • 上下文中毒 — 早期错误污染后续流程
  • 上下文混淆 — 无关信息分散注意力
  • 上下文冲突 — 矛盾信息导致困惑

解决方案： 使用子代理隔离复杂任务、定期 /compact 或 /clear、精确定义记忆内容

9.2 安全性最佳实践 ​

最小权限原则：

自定义命令：

yaml
---
allowed-tools:
  - git status
  - git diff
  # 只授予必要的工具
---

子代理：

yaml
---
tools:
  - read_file
  - grep
  # 不授予 write 或 run_terminal_cmd
---

工作区信任：

  • 始终在项目目录中运行 claude
  • 避免从根目录或敏感目录启动
  • 定期审查 Claude 的操作

9.3 成本优化策略 ​

模型选择：

日常编码推荐 Sonnet（快速、性价比高），复杂规划选用 Opus（深度推理强），详见 2.3 使用方式与渠道。

Token 节省技巧：

  • 使用 /compact 压缩历史
  • 避免重复读取大文件
  • 使用子代理隔离大型任务（子代理的 token 不计入主代理）
  • 查看当前会话成本：/cost

9.4 工作流程最佳实践 ​

📎 典型的一天工作流

早晨（项目启动）：

bash
cd ~/projects/my-app
claude
/memory  # 检查项目状态
"总结昨天的工作"  # 如果需要

日间（功能开发）：

bash
# 复杂功能：使用规范驱动
Shift+Tab  # 进入计划模式
"帮我规划用户认证系统的实现"
# 审查计划 → 批准 → 执行

# 简单任务：直接实现
"修复 UserProfile.tsx 中的 TypeScript 错误"

代码审查：

bash
"code review @src/auth/login.ts"

提交代码：

bash
/commit-code 用户认证功能

傍晚（清理和总结）：

bash
/compact  # 压缩对话历史
"今天实现了 JWT 认证，使用 jose 库而非 jsonwebtoken #"  # 添加重要记忆
📎 团队协作流程

项目初始化（团队负责人）：

bash
# 1. 创建项目记忆
/init

# 2. 添加团队规范（/memory）
# - 代码风格指南
# - Git 提交规范
# - 架构决策
# - 第三方依赖说明

# 3. 创建共享子代理
/agents
# 创建项目级代理：code-reviewer、test-generator

# 4. 配置 MCP 和钩子
claude mcp add context7 --scope project
/hooks  # 配置自动格式化

# 5. 提交配置文件
git add .claude/ CLAUDE.md
git commit -m "chore: 配置 Claude Code 团队环境"
git push

团队成员使用：

bash
git clone <repo-url>
cd <project>
claude  # 自动加载团队配置
"根据 @CLAUDE.md 实现用户注册功能"

9.5 故障排查 ​

问题解决方案
安装后命令找不到检查 PATH；运行 claude doctor 查看安装与环境状态
npm 权限错误（EACCES）修复 npm 目录权限（如 sudo chown -R $(whoami) ~/.npm），切勿用 sudo npm install -g
MCP 未加载检查配置 /mcp → 重启 Claude /exit && claude → 授予权限
子代理未触发检查文件位置（.claude/agents/）、description 字段清晰、提示词包含触发短语
状态栏显示错误查看错误信息 → 请求修复 → 手动编辑 ~/.claude/statusline.py

十、📖 快速参考卡片 ​

10.1 常用命令速查 ​

命令用途使用频率
/init初始化项目记忆项目开始时
/clear清除对话历史切换任务时
/compact压缩对话历史对话过长时
/memory编辑记忆文件需要添加规则时
/agents管理子代理创建专门代理时
/mcp管理 MCP 服务器添加外部工具时
/cost查看成本监控使用量时
/output-style:new创建输出样式自定义交互方式时
/btw无污染旁问长任务中临时提问
/insights使用习惯分析报告每月一次
/simplify三合一代码审查功能开发完毕后
/branch对话分叉想试另一个方向时
/loop定时循环任务需要定期检查时
/rc手机远程控制离开电脑时
/model opusplanOpus 规划 + Sonnet 执行Pro 用户省额度

10.2 提示词模板 ​

场景模板
功能实现根据 @memory/spec/CLAUDE.md 实现 [功能名称]
代码审查code review @[文件路径]
调试调试 @[文件路径] 中的 [问题描述]
重构重构 @[文件路径]，改进 [具体方面]
文档生成为 @[文件路径] 生成详细的文档

10.3 上下文引用语法 ​

语法作用
@文件路径引用特定文件
@目录路径引用整个目录
@memory/spec/CLAUDE.md引用特定记忆文件
#快速添加记忆（在句尾）

10.4 Git Worktrees 速查 ​

命令用途
git worktree add ../dir branch创建新 worktree
git worktree list列出所有 worktrees
git worktree remove ../dir删除 worktree
git worktree prune清理引用

10.5 Desktop 模式对比 ​

特性Local WorktreeCloud (Default)
执行环境本地机器Anthropic 服务器
MCP/Hooks✅ 可用❌ 需另配置
扩展性受限本地资源无限（预算允许）
结果交付本地 Git 分支GitHub PR/提交

十一、📚 外部参考资源 ​

💡 说明

以上资源由社区和第三方讲师制作，非 Anthropic 官方出品。学习时建议结合 Anthropic 官方文档 和 Claude Code 内置 /help 命令。

← 返回 AI 与开发工具