何雨果的知识库

外观

Claude Code 完整使用流程指南 ​

2026 年 8 月更新Local / Cloud / Remote Control

🎯 学习目标

本指南围绕 Claude Code 当前的三类执行环境展开：本地运行、云端运行与 Remote Control 远程控制。你将掌握项目指令与自动记忆、Skills、MCP、Hooks、子代理、会话分叉、Desktop 并行工作区、云端代码审查和团队自动化等能力。

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

Claude Code 以高频率更新。命令、模型、订阅权益和研究预览功能应以当前版本的 /help、claude --version、官方文档和产品内显示为准。本文不再把未被官方文档确认的“隐藏命令”写入推荐工作流。

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

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

学习路线图：

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

按问题快速跳转：

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

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

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

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

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

1.1 三类执行环境与多个交互界面 ​

先区分“Claude 在哪里运行”和“你从哪里操作”。这两个维度决定了文件、工具、会话历史和权限的边界。

执行环境代码与命令在哪里运行适合场景
Local你的电脑或本地容器使用本地文件、工具链、MCP 和项目配置
CloudAnthropic 云端环境或组织自托管环境无需保持电脑在线，适合并行和长任务
Remote Control仍在你的本地电脑从网页或手机继续控制现有本地会话

常见交互界面包括终端 CLI、Claude Desktop 的 Code 标签、VS Code / JetBrains、claude.ai/code、移动端、Slack 和 CI/CD。Remote Control 只是本地会话的远程窗口，不等同于云端执行。

1.2 四类扩展机制 ​

Claude Code 在 2026 年初已将自定义斜杠命令并入 Skills 的统一心智模型。实际使用时，可以把扩展能力理解为四类：

机制用途边界
Skills封装可复用的指令、脚本和工作流自动触发或通过 /技能名 手动调用
Subagents把任务交给隔离上下文中的专门代理适合并行研究、审查和验证
MCP / Connectors连接数据库、文档、浏览器与业务系统会扩大可访问的数据与操作范围
Hooks在固定生命周期事件执行确定性逻辑适合必须执行的检查、格式化与审计

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

上下文工程（Context Engineering）

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

靠 持久指令与自动记忆、智能检索、上下文压缩（/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 支持以下官方认证与部署路径：

路径计费与管理方式适合场景
Claude 订阅按 Pro / Max / Team / Enterprise 方案管理个人与团队日常开发
Anthropic Console API按 API 使用量计费自动化、脚本和精细成本核算
Amazon Bedrock / Google Vertex AI / Microsoft Foundry由云平台与企业策略管理企业网络、合规和集中治理

第三方代理、非官方中转和自定义网关不属于 Anthropic 官方通道，且部分能力会不可用。例如 Remote Control 要求连接官方 API 端点，不支持 API Key、Bedrock、Vertex AI、Foundry 或自定义代理。涉及公司代码、客户数据、密钥和生产日志时，应只使用组织批准的通道。

模型名称与可用档位变化很快，本文不固定推荐某个版本。使用 /model 查看当前可用模型，并按任务在响应速度、推理强度、额度和成本之间选择；支持的模型可在选择器中调整 effort level。

三、🎯 日常使用流程 ​

3.1 项目初始化 ​

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

# 2. 启动 Claude Code
claude

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

📌 /init 命令的作用

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

3.2 构建项目记忆系统 ​

Claude Code 有两套互补的持久上下文：你维护的 CLAUDE.md，以及 Claude 自动积累的 auto memory。前者放团队明确要求，后者记录构建命令、调试经验和反复出现的偏好。

记忆层级结构：

text
~/.claude/CLAUDE.md                 # 用户级指令（全局偏好）
./CLAUDE.md 或 ./.claude/CLAUDE.md  # 项目级指令（团队共享）
./CLAUDE.local.md                    # 本机私有项目指令
./.claude/rules/*.md                 # 可按路径生效的规则
~/.claude/projects/<project>/memory/ # 本机自动记忆

添加记忆的方法：

方法作用
对 Claude 说“把这条加入 CLAUDE.md”写入团队或个人明确指令
对 Claude 说“记住……”由 auto memory 判断并保存可复用经验
/memory编辑指令文件、开关 auto memory、打开自动记忆目录
/context确认本次会话实际加载了哪些指令与记忆

💡 已有 AGENTS.md 的项目

Claude Code 默认读取 CLAUDE.md。可在 CLAUDE.md 中使用 @AGENTS.md 导入现有规则，避免维护两份重复内容。长流程更适合拆成 Skills，路径相关规则更适合放入 .claude/rules/。

3.3 基本交互模式 ​

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

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

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

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

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

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

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

本章列出稳定、公开的内置命令。自定义工作流统一使用 Skills，见 五、定制与扩展。

4.1 斜杠命令速览 ​

上下文管理命令：

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

配置与成本命令：

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

代理与工具管理：

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

会话与导出命令：

命令作用
/export导出当前会话
/resume选择并恢复之前的本地会话
/rewind回退对话、文件更改，或从某点压缩上下文
/fork从当前会话创建独立分支会话
/btw打开不影响主线程的 side chat
/remote-control将当前本地会话连接到网页或移动端
/review审查当前改动
/ultrareview在云端启动并行验证式代码审查（研究预览、单独计费）

💡 内置命令会随版本变化。输入 /help 或 / 搜索当前版本可用命令，不要依赖社交媒体流传的隐藏模式。

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 + P不清空输入的情况下切换模型
@文件路径自动补全，用于引用文件或目录
!Shell mode，运行命令并把输出加入上下文

⚠️ Mac 用户注意

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

💡 Debug 利器

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

五、🛠️ 定制与扩展 ​

这一章集中介绍 Skills、MCP、IDE 和插件。自 2026 年 1 月起，Claude Code 已把旧的自定义 Slash Commands 并入 Skills，用户仍可通过 /技能名 直接调用。

5.1 Skills：统一的自定义工作流 ​

项目级 Skill 放在 .claude/skills/<skill-name>/SKILL.md，个人级 Skill 放在 ~/.claude/skills/。Claude 会根据描述自动加载相关 Skill，也可以手动输入 /smart-commit 调用。

markdown
---
name: smart-commit
description: 检查当前改动并生成符合仓库惯例的提交建议
argument-hint: "[变更主题]"
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)
disable-model-invocation: true
---

# 工作流程

1. 运行 `git status`，确认工作区范围。
2. 运行 `git diff`，只分析本次任务相关改动。
3. 运行 `git log -5 --oneline`，学习仓库提交风格。
4. 输出建议的提交标题与正文，等待用户确认。

⚠️ 提交类 Skill 不应默认写入

让 Skill 先审阅并给出建议，不要在模板中直接执行 git add .、git commit 或 git push。这能避免把无关改动、密钥或生成物误带入提交。

5.2 何时使用 Skill、Rule、Hook 或 MCP ​

需求推荐机制
可复用的多步骤方法，可能附带脚本或资料Skill
只对特定路径生效的编码规范.claude/rules/
每次工具调用或提交前必须执行的确定性检查Hook
访问外部文档、数据库、浏览器或业务系统MCP / Connector
需要隔离上下文并独立完成的任务Subagent

Skills 采用渐进式加载：先根据名称和描述判断是否相关，再按需读取完整指令与配套资源。描述应清楚写明“做什么”和“何时使用”，避免多个 Skill 触发条件重叠。

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。Desktop 中的 Connectors 是带图形化配置流程的 MCP 集成。

添加 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） ​

插件是可复用的能力包，可同时包含 Skills、Agents、Hooks、MCP Servers 和 LSP 配置。终端使用 /plugin 打开管理器；Desktop 的本地与 SSH 会话可从图形界面浏览和安装。

bash
/plugin
# 在管理器中浏览已配置 marketplace、检查插件内容，再选择作用域安装

⚠️ 安装前检查权限

社区插件中的 Hook 和 MCP 可能执行本地命令或访问外部服务。安装前审阅清单、源码和权限；云端会话需在仓库 .claude/settings.json 中声明 enabledPlugins，Desktop 本地安装的插件不会自动出现在云端会话。

六、🧪 进阶功能与会话能力 ​

6.1 推理强度与模型选择 ​

当前模型普遍采用自适应推理，Claude 会根据任务复杂度动态决定思考深度。对于支持 effort level 的模型，可在 /model 选择器中用左右方向键调整。较高强度适合架构设计、复杂调试和高风险重构，但会增加等待时间与额度消耗。

bash
/model
# 选择当前账户可用的模型，并按需要调整 effort level

6.2 Checkpoints 自动检查点与 /rewind ​

Claude Code 会按用户提示记录会话状态和文件编辑快照。这不是 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 Side chat、会话分叉与云端审查 ​

本节只保留官方文档已公开的能力。研究预览功能的价格、权限和可用范围可能变化，使用前仍应检查产品内提示。

/btw — 无污染旁问 ​

/btw 打开一个读取主线程上下文、但不会把问答写回主线程的 side chat。适合解释代码、核对假设或探索一个旁支问题。

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

# 回答留在 side chat 中，主线程可以继续原任务

💡 为什么重要

旁问不会改变主线程的后续方向。Desktop 的本地与 SSH 会话还可用快捷键打开 side chat；云端会话的界面与可用入口以当前产品为准。

/fork — 会话分叉 ​

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

bash
/fork
# 当前对话进度被完整保留
# 新会话从当前状态开启，可以走完全不同的方向

💡 与 /rewind 的区别： /rewind 是回到过去的状态，/fork 是从当前状态创建一条独立路线。分叉继承父会话上下文，但之后的消息和执行互不影响。

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

把本地 CLI 或 VS Code 会话连接到 claude.ai/code 与 Claude 移动端。代码执行、文件系统、MCP 和项目配置仍留在本机，网页和手机只是操作界面。

bash
claude remote-control  # 启动远程控制服务
/remote-control        # 在现有会话中连接

# 使用同一 Claude 账户从网页或移动端继续操作

⚠️ 本地执行不等于数据只留在本地

Remote Control 通过 Anthropic 服务同步消息和工具活动，连接期间会在服务端存储会话记录；本机只发起出站 HTTPS 连接，不开放入站端口。它要求符合条件的 Claude 订阅登录，不支持 API Key、第三方代理或云厂商端点。

/ultrareview — 云端多代理代码审查 ​

/ultrareview 会把当前分支或指定 Pull Request 送入远程沙箱，启动多个审查代理寻找并独立验证缺陷。它是研究预览功能，使用单独的 credits 计费，且会上传审查范围内的仓库状态。

bash
/ultrareview       # 审查当前分支相对默认分支的改动
/ultrareview 1234  # 审查 GitHub Pull Request #1234

适合合并前的高信号缺陷检查；一般风格检查或不能上传代码的仓库，继续使用本地 /review 与项目测试。

/export — 导出对话为 Markdown ​

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

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

七、🤖 多代理与 Desktop 协调 ​

这是 多代理编排 理念的完整落地：用 Subagents 隔离专门任务，用 Skills 固化方法，再通过会话与 Worktrees 隔离并行修改。

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（代理技能） ​

📌 Skill 的定位

Skills 是包含指令、脚本和参考资料的可复用目录，用于教主代理或子代理稳定执行某类任务。创建方法见 五、Skills。

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

  • 会话先根据 Skill 的名称与描述判断相关性
  • 触发后再读取完整指令和配套资源
  • 减少不相关流程长期占用上下文

目录结构与 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 Desktop 的 Code 标签目前支持三类环境，并在界面中提供终端、文件编辑器、可视化 Diff、应用预览、side chat 和多会话布局。

模式执行环境主要能力注意事项
Local本地电脑本地工具、MCP、Connectors、插件、自动 Worktree电脑需要保持运行
SSH远程 macOS / Linux 主机使用远程主机的文件和工具，同时保留 Desktop 界面首次连接会在远端安装 Claude Code
CloudAnthropic 云端环境关闭电脑后继续运行，适合长任务与多仓库任务本地插件和 Connectors 不会自动继承

对 Git 仓库，Desktop 的并行本地会话默认用 Worktrees 隔离，目录通常位于项目的 .claude/worktrees/。云端会话则使用独立远程环境，权限模式、网络访问和可用扩展与本地会话不同。

Desktop 还提供 Scheduled tasks、PR 监控与修复、Computer Use、Dispatch 和 Connectors；这些能力受版本、平台与订阅方案影响，应以应用内显示为准。

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 三重并行开发工作流 ​

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

任务模式工作内容
任务 A本地只读子代理研究：比较可选依赖
任务 BDesktop Local Worktree功能开发：添加 UI 动画
任务 CDesktop Cloud远程开发：更新 Hero 区域

协调流程：

bash
# 任务 A: 在主会话中委派只读研究子代理
比较三个候选动画库的维护状态、包体积和可访问性

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

# 任务 C: 在 Cloud 模式
在 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 应用可以监控和继续不同来源的任务：

  • Cloud session：代码在云端运行，电脑可离线。
  • Remote Control：手机控制仍在本机运行的 CLI / VS Code 会话。
  • Dispatch → Desktop Code session：从手机发送任务，由配对的 Desktop 环境处理。

移动端工作流：

text
📱 选择已有会话或发起任务
    ↓
确认执行位置：Cloud / Remote Control / Dispatch
    ↓
查看进度、回答问题、批准操作
    ↓
💻 桌面端验证和修复
    ↓ 检查 Diff → 运行项目验证 → 决定是否提交

⚠️ 注意事项

  • Remote Control 要求本机保持可运行状态；休眠或断网期间会暂停并在恢复后重连。
  • Cloud 不会自动拥有本机的密钥、MCP、Hooks 或插件；应显式配置云端环境。
  • 移动端适合监控和决策，合并前仍应在可信环境完成 Diff、测试和目标分支检查。

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

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                         # 项目架构、团队规范
./.claude/rules/frontend.md         # 按路径生效的领域规则
~/.claude/projects/<project>/memory # 本机 auto memory

原则：

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

动态上下文管理：

命令使用时机效果
/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 成本优化策略 ​

模型选择：

模型列表和能力会动态变化。通过 /model 查看当前账户可用项：小任务优先响应速度，复杂重构提高 effort level，高风险任务则先计划、再验证，不用模型名称代替风险控制。

Token 节省技巧：

  • 使用 /compact 压缩历史
  • 避免重复读取大文件
  • 使用子代理隔离大型任务，避免其完整中间过程占用主线程上下文；子代理仍会产生实际用量
  • 查看当前会话成本：/cost

9.4 工作流程最佳实践 ​

📎 典型的一天工作流

早晨（项目启动）：

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

日间（功能开发）：

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

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

代码审查：

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

提交前复核：

bash
git status
git diff
# 运行项目测试，再让 Claude 起草提交信息；确认范围后才提交

傍晚（清理和总结）：

bash
/compact  # 压缩对话历史
"记住：本项目的 JWT 实现使用 jose，不使用 jsonwebtoken"  # 写入 auto memory
📎 团队协作流程

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

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

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

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

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

# 5. 检查配置文件 Diff，确认没有凭据和本机路径后，再按团队流程提交
git status
git diff -- .claude/ CLAUDE.md

团队成员使用：

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无污染旁问长任务中临时提问
/fork会话分叉想试另一个方向时
/review本地代码审查功能开发完毕后
/ultrareview云端多代理缺陷审查重要改动合并前
/rc手机远程控制离开电脑时
/model切换模型与 effort level按任务调整时

10.2 提示词模板 ​

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

10.3 上下文引用语法 ​

语法作用
@文件路径引用特定文件
@目录路径引用整个目录
@docs/spec/feature.md引用特定规范文件
!命令在 Shell mode 中运行命令并加入上下文

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 环境对比 ​

特性LocalSSHCloud
执行环境本地机器远程 macOS / LinuxAnthropic 云端环境
本地文件与工具✅❌，使用远程主机资源❌，需配置云环境
Connectors / 插件✅✅，读取远程个人配置需在云端或仓库中单独配置
电脑离线后继续❌取决于远程主机✅
适合场景日常开发与本地预览远程服务器、GPU 或特殊依赖长任务、并行任务、多仓库任务

十一、📚 外部参考资源 ​

💡 说明

后面三项为社区和第三方资源，不代表 Anthropic 官方结论。遇到命令、权限和订阅差异时，以本文列出的官方文档与 Claude Code 内置 /help 为准。

← 返回 AI 知识库