3万字硬核拆解 Claude Code：从入门到工程化落地（建议收藏）

3 万字长文带你重新认识 Claude Code！从账号直连、CLI 常用工作流，到 Hooks 自动化门禁、Subagents 角色化分工，再到 MCP 安全连接外部业务，全景拆解 AI 在真实工程中的落地闭环。告别“玩具级”辅助，打造你的自动化开发工厂，技术人必读！

杨林伟

1597人浏览 · 2026-01-27 10:05:32

杨林伟 · 2026-01-27 10:05:32 发布

文章目录

第一部分：从 0 到 1（安装与上手）
第二部分：日常使用（终端命令与工作流）
第三部分：原理与边界（数据流动与安全）
第四部分：工程化落地（Hooks / Subagents / Skills）
第五部分：生态扩展（MCP / Output Styles / Plugins）
第六部分：全景总结（5W1H 与官方导航）

第一部分：从 0 到 1（安装与上手）

1.1 什么是 Claude Code？

官方文档地址：https://code.claude.com/docs

在这里插入图片描述

Claude Code 是 Anthropic 推出的 面向真实工程场景的 AI 编程助手。我们不能把 Claude Code 理解为聊天版的 AI，它其实更接近于 能直接参与项目开发的工程师，它不只是回答“怎么写代码”，而是可以 理解整个代码仓库、跨文件修改代码、运行命令、修复错误，并在真实开发环境中协助完成任务。

在实际使用中，可以把 Claude Code 当成一个工程级助手，例如：

重构复杂或历史包袱较重的代码
为现有模块补齐单元测试
修复测试失败或构建错误
优化性能瓶颈函数
理解陌生项目并给出结构说明

只需要用自然语言描述需求，Claude Code 会结合整个代码仓库给出修改方案，甚至直接提交可用的代码改动。

1.2 账号与环境准备

1.2.1 国内注册

博主不太建议直接使用国内中间代理的 Claude Code，虽然口头上说是 “直连”，其实本质是走了代理，因此也踏了不少坑，费用是直连的几倍，最终使用了直连的方式。这里不讲述如何使用国内的，网上搜索应该一大堆。

1.2.2 官方直连

直连的方式很简单，只需要 “魔法”+“注册” + “代充” 即可，相信大家都懂，费用大概一个月100多，目前 Claude Code 的量好像也增大了，相比国内的中间代理，省了不止一倍，而且不存在稳定性的问题。

怎么使用 “魔法”，这里不再阐述了，适合自己就好，现在官网并不支持注册，可以自己去某宝买一个账号，同时让他代充即可。最后登录成功的web页面如下：
在这里插入图片描述

在设置页面也能看到用量：
在这里插入图片描述

1.3 Claude Code 安装指南

至此，相信读者们都能注册 Claude Code 成功了，那么怎么使用呢？这里讲解其安装方式。

1.3.1 系统与环境要求

安装Claude Code的系统要求如下：

类型	要求
操作系统	macOS 10.15+、Ubuntu 20.04+/Debian 10+ 或 Windows 10+（带 WSL 1、WSL 2 或 Git for Windows）
硬件	4GB+ RAM
软件	Node.js 18+（仅 NPM 安装需要）
网络	认证和 AI 处理需要互联网连接
Shell	在 Bash、Zsh 或 Fish 中效果最佳
位置.	Anthropic 支持的国家/地区

1.3.2 Mac / Linux / WSL 安装

执行如下命令：

# 安装稳定版本（默认）
curl -fsSL https://claude.ai/install.sh | bash

# 安装最新版本
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 安装特定版本号
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Mac 也可以使用 Homebrew 的方式安装：

brew install --cask claude-code

1.3.3 Windows 安装

Windows PowerShell 安装方式：

# 安装稳定版本（默认）
irm https://claude.ai/install.ps1 | iex

# 安装最新版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# 安装特定版本号
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Windows CMD 安装方式：

REM 安装稳定版本（默认）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

REM 安装最新版本
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd

REM 安装特定版本号
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd

1.3.4 NPM 安装

注意：需要 Node.js 18+以上的版本

Node.js下载地址：https://nodejs.org/en/download/

下载安装好Node.js后，执行如下命令即可安装 Claude Code：

npm install -g @anthropic-ai/claude-code

1.3.5 版本更新

Claude Code 自动保持自身最新状态，如果需要禁用自动更新，在 settings.json 文件（一般在用户目录，例如Mac下在：~/.claude/settings.json）中设置 DISABLE_AUTOUPDATER 环境变量：

export DISABLE_AUTOUPDATER=1

也可以手动更新：

claude update

1.4 快速入门：CLI 实战

前面讲的可能都比较偏概念化，这里实际的来操作演示，效果可能更好。

1.4.1 初始化与授权登录

1.4.1.1 创建项目

初次使用，我们可以进入项目的根目录，这里为了方便演示，我新建了一个 html-project 的文件夹，然后执行 claude 命令如下：

mkdir html-project
cd html-project
claude

运行后，会提示选择终端风格，选默认即可：

在这里插入图片描述

1.4.1.2 登录与授权流程

接着会提示登录方式，Claude Code 提供订阅制和 API 两种登录方式。

订阅登录方式：成本固定、使用简单，适合个人日常开发；
Console（API）：登录按使用量计费，更灵活，适合高强度使用或团队与自动化场景。

选择第一种之后，会自动跳转到浏览器授权页面：
在这里插入图片描述

点击Authorize授权，授权成功后，页面会提示如下：
在这里插入图片描述

切换回终端，提示登录成功了，然后提示是否使用默认的API_KEY，这里选择推荐的No，这个KEY当然可以分享给别人共同使用，但是容易被封，个人使用的话，还是选择推荐的。
在这里插入图片描述

后续一直选择使用推荐的即可，登录成功页面如下：
在这里插入图片描述

1.4.1.3 常见问题与避坑说明

注意，授权登录需要使用魔法，且建议选择“湾湾”及非限制的国家地区，否则容易出现地区限制的问题。
在这里插入图片描述
如果页面提示成功了，但是本地403，这个时候，需要注意本地的系统，是否设置了其它的地区，建议还是“湾湾”。

1.4.2 用一句话完成一个真实需求

接下来，我们可以开发任务，例如：帮我创建一个静态的页面，打开后，是星空的动态效果。

在这里插入图片描述

可以看到，Claude Code 在执行任务的过程中，会提示用户是否要执行该操作，上述有三个选项，我们可以选择1，要经过我们同意后才可以运行，这是整个执行的过程，能看到Claude Code正在的操作，也便于我们去了解它的实现方式。
在这里插入图片描述

最后执行成功的结果如下：
在这里插入图片描述

打开生成的HTML，可以看到如下效果，效果还是挺不错的。
在这里插入图片描述

但是到这里，大家可能会有一个疑问，这些新增和改动的代码看上去太麻烦了，不可能一直使用终端，其实Claude Code支持多种使用形态，这里继续讲解。

1.5 Claude Code 的多种使用形态

1.5.1 JetBrains IDEs

详情参考文档：https://code.claude.com/docs/en/jetbrains

Claude Code 插件支持大多数 JetBrains IDEs，包括：

IntelliJ IDEA
PyCharm
Android Studio
WebStorm
PhpStorm
GoLand

在 IDEA 中安装 Claude Code 非常简单，直接进入 Settings → Plugins，搜索 Claude Code 并安装即可：

在这里插入图片描述

安装成功后，右上角会出现 Claude Code 图标，点击即可打开底部终端：

在这里插入图片描述

此时可以直接用自然语言下达指令，例如：

去除文字，增加多一个月亮

在修改过程中，可以清楚地看到代码变动的内容，效果类似于 git history / diff：

在这里插入图片描述

同时，插件执行的所有日志也会在底部控制台完整展示，一切都在 “掌握中”：

在这里插入图片描述

最后看看生成的效果（虽然有点丑😂，主要还是提示词要写好，后面博主会出 Gemini 3 的教程，效果会更好）：
在这里插入图片描述

1.5.2 VS Code

详情参考文档：https://code.claude.com/docs/en/vs-code

在这里插入图片描述

Claude Code 同样支持 VS Code，通过官方扩展即可安装使用。

核心能力与 JetBrains 版本一致：

支持直接读取当前项目上下文
使用自然语言生成、修改代码
自动生成 patch，并展示 diff 变更
可结合终端执行命令、运行测试

VS Code 版本更适合前端、Node.js 以及轻量级项目开发者，整体体验偏“无感集成”，适合日常高频使用。

1.5.3 桌面版

详情参考文档：https://code.claude.com/docs/en/desktop

在这里插入图片描述

Claude Code 桌面版是一个 本地原生应用（Preview），目标是让你无需命令行，也能管理多个 Claude Code 会话。

核心特性：

多会话并行 ：每个任务会创建独立的 Git worktree，不同任务互不影响，非常适合并行开发或实验。
支持 .worktreeinclude ：可以让 .gitignore 中被忽略的文件（如 .env）在 AI 会话中可见，方便真实环境下修改代码。
内置稳定版本 ：桌面版内置 Claude Code 稳定版本，自动更新，避免 CLI 版本不一致问题。
继承本地环境变量 ：自动读取本机 PATH，可直接调用你已安装的本地开发工具。
无缝衔接 Web 会话 ：桌面版可一键跳转 Web Claude Code，灵活在本地与云端之间切换。

1.5.4 浏览器插件

详情参考文档：https://code.claude.com/docs/en/chrome

在这里插入图片描述

Claude Code 提供 Chrome 浏览器插件（Beta），主要面向 Web 调试与自动化场景。

当前能力：

结合网页上下文使用 Claude Code
可辅助调试 Web 应用、分析 Console 日志
用于自动化网页操作和页面分析

注意事项：

目前 仅支持 Google Chrome
尚不支持 Firefox / Arc / Brave
仍处于测试阶段，更适合尝鲜和实验性使用

1.5.5 GitHub Actions

详情参考文档：https://code.claude.com/docs/en/github-actions

Claude Code 可以通过官方 GitHub Action 深度集成到 CI/CD 流程中。

典型使用方式：

在 PR / Issue 中通过 @claude 触发 AI 任务
自动进行代码审查、Bug 修复、功能实现
自动生成 Pull Request 或提交修改

优势：

无需人工介入即可完成部分开发流程
支持多种认证方式（Anthropic API / Bedrock / Vertex）
非常适合代码质量治理、自动化修复场景

1.5.6 GitLab CI/CD

详情参考文档：https://code.claude.com/docs/en/gitlab-ci-cd

GitLab CI/CD 集成目前处于 Beta 状态，定位与 GitHub Actions 类似。

核心能力：

在 CI Pipeline 中运行 Claude Code
根据 Issue 或 MR 评论触发 AI 任务
自动生成 Merge Request

适合 GitLab 重度用户，但目前功能仍在快速迭代中，建议关注官方更新。

1.5.7 Slack

详情参考文档：https://code.claude.com/docs/en/slack

Claude Code 可以直接集成到 Slack，成为“会写代码的同事”。

使用方式：

在 Slack 中 @Claude 提出需求
Claude 自动判断是否为代码任务
若是代码任务，会启动 Claude Code 会话

支持两种模式：

Code Only：所有消息都走 Claude Code
Code + Chat：智能区分聊天与代码任务，可手动切换

适合团队协作、异步开发和远程办公场景。

1.5.8 Web

详情参考文档：https://code.claude.com/docs/en/claude-code-on-the-web

在这里插入图片描述

Claude Code 提供官方 Web 版本，无需本地环境即可使用。

主要特点：

浏览器中直接授权 GitHub 仓库
Claude 在官方云端 VM 中运行代码
预装常见开发环境（Python / Node / Rust 等）
支持运行测试、修改代码、创建 PR

非常适合：

临时使用
无本地开发环境
远程 / 云端开发场景

1.6 小结

本章完成了从“认识 Claude Code”到“真正跑起来”的闭环：

账号与环境准备、安装与更新
CLI 快速上手与一次真实任务演示
IDE/桌面/云端等多种使用形态的选择建议

后续章节会逐步进入命令体系、自动化与工程化能力，把日常开发流程真正串起来。

第二部分：日常使用（终端命令与工作流）

本章聚焦 Claude Code 的终端命令体系与关键配置。
你会看到命令按“文件/目录、会话、权限与安全、成本与监控”等维度如何分类，以及每类命令在真实工程里的使用场景。
建议边看边在自己的项目里对照尝试，把常用命令沉淀成个人或团队的操作习惯。

2.1 命令汇总

claude的终端命令非常的多，可以通过最简单的方式去查看支持哪些命令，终端输入 “/” 会有提示：
在这里插入图片描述
博主已经分类好，并逐个进行讲解。

2.1.1 文件和目录管理

2.1.1.1 add-dir 命令

在这里插入图片描述

用途：将指定目录添加到当前会话的工作目录列表中，使当前会话可以同时访问和理解多个目录。

使用方法:

/add-dir <目录路径>

示例:

/add-dir ./src
/add-dir /Users/username/project/components

使用场景:

前后端分离项目中，在后端目录下将前端目录加入同一会话进行分析
多模块或多子项目结构中，需要在同一会话中同时查看不同目录的代码
不方便切换当前目录，但需要临时引入其他目录进行参考或对比

2.1.1.2 init 命令

在这里插入图片描述

用途: 在当前项目中初始化一个新的 CLAUDE.md 文件，用于存储代码库文档和上下文信息。

使用方法:

/init

说明: 创建项目级别的文档文件，帮助 Claude 更好地理解你的代码库结构和约定。

使用场景:

新项目首次接入 Claude Code 时，初始化项目的基础上下文说明
为已有项目补充 AI 可理解的项目结构、技术栈和开发约定
团队协作场景下，统一 Claude 在不同成员环境中的理解方式
项目结构复杂或模块较多时，减少 Claude 反复询问背景信息

2.1.1.3 export 命令

在这里插入图片描述

用途: 将当前对话导出到文件或剪贴板。

使用方法:

/export
/export <文件路径>

说明: 可以保存完整的对话历史，便于分享或归档。

使用场景:

将关键技术讨论或方案设计对话导出为文档进行留存
在代码评审、问题分析完成后，导出对话结果作为项目记录
与团队成员共享 Claude 的分析过程或结论内容
在撰写技术博客、文档或复盘总结时复用对话内容

2.1.1.4 clear 命令（别名: reset, new）

在这里插入图片描述

用途: 清除对话历史并释放上下文，开始全新的会话。

使用方法:

/clear
/reset
/new

注意: 此命令会清除所有对话记录，但不会删除文件系统中的任何文件。

使用场景:

当前对话内容过多、上下文混乱时，重新开始一个干净的会话
在切换到全新任务或完全不同的问题场景时使用
Claude 的回答开始偏离当前目标，需要重置上下文
希望释放上下文占用，提升后续对话的理解准确性

2.1.1.5 compact 命令

在这里插入图片描述

用途: 清除对话历史，但在上下文中保留摘要信息。

使用方法:

/compact
/compact [自定义摘要指令]

示例:

/compact
/compact 保留所有关于 API 设计的讨论

说明: 当对话过长但希望保留重要信息时使用。

使用场景:

长时间对话导致上下文过大，但仍需保留核心结论和背景信息
在进入新阶段任务前，对已有讨论进行“压缩整理”
希望继续当前话题，但移除细节性讨论以提升上下文效率
需要明确指定保留重点内容（如设计决策、接口约定）时使用

2.1.1.6 resume 命令

在这里插入图片描述

用途: 恢复之前的对话会话。

使用方法:

/resume

说明: 允许你继续之前中断的对话。

使用场景:

因关闭终端、网络中断等原因导致会话中断后继续工作
在多次短时间使用中，恢复之前尚未完成的讨论或任务
需要回到先前的分析背景，继续深入问题排查或方案设计
临时切换任务后，再回到原有会话继续处理

2.1.1.7 rewind 命令 (别名: checkpoint)

在这里插入图片描述

用途: 将代码或对话恢复到之前的某个时间点。

使用方法:

/rewind
/checkpoint

说明: 类似于"撤销"功能，可以回退到之前的状态。

使用场景:

在尝试多种方案后，希望回退到之前稳定或正确的状态
Claude 生成的修改方向不符合预期，需要撤销最近的更改
复杂调试过程中，回到某个关键节点重新分析问题
实验性修改后，快速恢复到已确认可用的版本

2.1.2 任务和代理管理

2.1.2.1 agents 命令

在这里插入图片描述

用途: 管理代理配置，查看当前运行的后台代理及其状态。

使用方法:

/agents

说明: 代理是用于在后台执行复杂、多步骤或耗时任务的专用执行单元。

使用场景:

需要 Claude 在后台执行耗时或步骤较多的任务，而不阻塞当前对话
同时处理多个任务，希望某些任务独立运行、无需持续关注
将目标明确的工作交给代理自动执行，自己继续进行其他对话或操作
运行代码审查、测试、扫描等可自动完成的任务
查看当前有哪些代理正在运行，以及各自的执行状态和进度
不适合频繁交互或即时问答的场景，此类需求直接使用普通对话即可

2.1.2.2 bashes 命令

在这里插入图片描述

用途: 列出和管理所有后台运行的 bash 任务。

使用方法:

/bashes

说明: 显示所有后台进程的 ID 和状态，可用于监控长时间运行的命令。

使用场景:

运行构建、测试、脚本等耗时命令时，查看其后台执行状态
同时启动多个 bash 任务，需要统一查看和管理进程
排查后台命令是否仍在运行、已完成或异常终止
在不阻塞当前会话的情况下执行系统命令，并随时检查进度
清理或定位遗留的后台 bash 进程，避免资源占用

2.1.2.3 todos 命令

在这里插入图片描述

用途: 列出当前的待办事项。

使用方法:

/todos

说明: 显示 Claude 正在跟踪的所有任务及其状态（待处理、进行中、已完成）。

使用场景:

在复杂对话或多步骤任务中，查看当前还有哪些事项未完成
跟踪 Claude 执行中的任务进度，避免遗漏关键步骤
在中断会话后，快速回顾当前工作清单并继续执行
检查已完成与进行中的任务，确认工作是否按预期推进
作为任务管理视角，辅助组织 Claude 协作过程中的工作流

2.1.3 上下文和资源管理

2.1.3.1 context 命令

在这里插入图片描述

用途: 以彩色网格形式可视化当前的上下文使用情况。

使用方法:

/context

说明: 帮助你了解哪些文件和目录在当前会话中，以及它们占用的上下文空间。

使用场景:

在长时间对话或大型项目中，查看当前上下文包含了哪些文件和目录
判断上下文是否过大，是否需要清理或压缩以提升响应质量
在添加多个目录或文件后，确认它们是否已成功进入上下文
排查 Claude 回答不准确时，检查是否缺少关键文件或引用了无关内容
在使用 /compact、/clear 等命令前，评估当前上下文占用情况

2.1.3.2 cost 命令

在这里插入图片描述
用途: 显示当前会话的总成本和持续时间。

使用方法:

/cost

说明: 查看 API 调用的费用统计和会话时长。

使用场景:

在长时间或高频使用 Claude Code 后，了解当前会话的费用消耗情况
评估某类任务或工作流程的成本，优化使用方式
团队或个人进行成本控制时，定期查看会话消耗
在进行大规模分析、代码生成前后，对比成本变化
排查异常消耗，确认是否存在不必要的调用或上下文占用

2.1.3.3 usage 命令

在这里插入图片描述

用途: 显示计划使用限制和当前用量。

使用方法:

/usage

说明: 查看你的订阅计划的配额使用情况。

使用场景:

定期检查当前订阅计划的使用进度，避免超出配额
在进行高强度使用前，确认是否还有足够的可用额度
排查使用受限或响应变慢时，确认是否达到计划上限
团队使用场景下，了解整体配额消耗情况以便合理安排任务
决定是否需要升级订阅计划或调整使用策略

2.1.3.4 memory 命令

在这里插入图片描述
用途: 编辑 Claude 的记忆文件。

使用方法:

/memory

说明: 管理 Claude 在会话之间记住的持久化信息。

使用场景:

希望 Claude 在不同会话中持续记住特定偏好或工作习惯
更新或修正 Claude 已保存的长期记忆内容
清理不再需要或已过期的记忆信息，避免干扰后续对话
在长期项目或持续协作场景中，维护稳定的上下文认知
控制 Claude 记忆范围，平衡便利性与隐私、安全需求

2.1.4 配置和个性化

2.1.4.1 config 命令（别名: theme）

在这里插入图片描述

用途: 打开配置面板，修改 Claude Code 设置。

使用方法:

/config
/theme

说明: 可以配置主题、编辑器偏好、快捷键等。

使用场景:

初次使用 Claude Code 时，根据个人习惯进行基础配置
调整主题样式以适应不同的使用环境（如深色/浅色模式）
配置编辑器行为或快捷键，提高日常使用效率
在不同工作场景或设备上，快速调整交互体验
排查或修改因配置不当导致的使用问题

2.1.4.2 hooks 命令

在这里插入图片描述

用途: 管理工具事件的钩子配置。

使用方法:

/hooks

说明: 设置在特定事件（如工具调用、文件编辑）发生时自动执行的命令。

使用场景:

每次 Claude 修改代码文件后，自动执行代码格式化或 lint 检查
在运行测试、构建等命令前，自动检查环境变量或依赖是否就绪
在生成或修改关键配置文件时，自动触发校验或备份操作
希望把一些“每次都会做但容易忘”的操作交给系统自动完成
团队协作中，将统一的检查或规范流程固化为自动钩子，避免人工遗漏

2.1.4.3 permissions 命令（别名: allowed-tools）

在这里插入图片描述

用途: 管理工具的允许和拒绝权限规则。

使用方法:

/permissions
/allowed-tools

说明: 控制 Claude 可以使用哪些工具，增强安全性。

使用场景:

在项目中只希望 Claude 执行只读操作，禁止文件修改或命令执行
使用 Claude 辅助分析生产环境代码时，限制其访问高风险工具
团队协作场景中，为不同成员或项目设定统一的工具使用边界
在运行自动化任务或 agent 前，明确允许其可使用的工具范围
排查异常行为时，检查是否因工具权限配置不当导致

2.1.4.4 output-style 命令

在这里插入图片描述

用途: 直接设置输出样式或从选择菜单中选择。

使用方法:

/output-style
/output-style <样式名称>

说明: 自定义 Claude 的输出格式和显示方式。

使用场景:

希望 Claude 在后续回答中统一使用特定格式（如列表、步骤说明、代码优先）
在编写技术文档或博客时，要求输出风格更加正式、结构化
在进行代码评审或方案设计时，偏好简洁、重点突出的回答形式
不同工作场景下，快速切换适合当前任务的输出风格
需要让 Claude 的回答更符合个人或团队的阅读习惯

2.1.4.5 output-style:new 命令

在这里插入图片描述

用途: 创建自定义输出样式。

使用方法:

/output-style:new

说明: 定义你自己的输出格式模板。

使用场景:

希望 Claude 的输出长期保持固定格式（如技术方案模板、评审清单）
团队协作中，统一 Claude 的输出结构，减少格式沟通成本
在代码评审、需求分析等场景下，定制符合流程的回答模板
经常重复整理相同类型内容，希望通过模板提升效率
将个人偏好的输出风格固化为可复用配置

2.1.4.6 statusline 命令

在这里插入图片描述

用途: 设置 Claude Code 的状态栏 UI。

使用方法:

/statusline

说明: 配置底部状态栏显示的信息。

使用场景:

希望在界面底部快速查看当前会话状态（如模型、上下文占用等）
在长时间工作过程中，实时感知 Claude 的运行和配置状态
根据个人习惯定制关键信息展示，减少频繁查看其他命令
在多任务或多会话切换时，快速确认当前环境是否符合预期
优化整体使用体验，让关键信息始终可见

2.1.4.7 terminal-setup 命令

在这里插入图片描述

用途: 为换行安装 Shift+Enter 键绑定。

使用方法:

/terminal-setup

说明: 配置终端快捷键，使 Shift+Enter 插入换行而不是发送消息。

使用场景:

在终端中编写较长提示词或多行指令时，避免误发送内容
经常需要组织复杂问题、分点描述需求的用户
习惯在输入框中先完整编辑内容，再统一发送给 Claude
从聊天工具或 IDE 场景迁移到终端使用时，保持一致的输入体验
提升长文本输入时的可控性和书写舒适度

2.1.4.8 vim 命令

在这里插入图片描述

用途: 在 Vim 和普通编辑模式之间切换。

使用方法:

/vim

说明: 为喜欢 Vim 键位的用户提供编辑模式切换。

使用场景:

日常使用 Vim/Neovim 的用户，希望在 Claude Code 中保持一致的编辑习惯
编写较长、多行输入内容时，利用 Vim 的高效编辑能力
在频繁修改提示词或指令内容时，提高编辑效率
从终端或 IDE 编辑环境无缝切换到 Claude Code 使用
对普通输入模式不熟悉或效率较低的用户

2.1.4.9 model 命令

在这里插入图片描述

用途: 设置 Claude Code 使用的 AI 模型。

使用方法:

/model
/model <模型名称>

示例:

/model claude-sonnet-4
/model claude-opus-4

说明: 切换不同的 Claude 模型版本。

使用场景:

在不同任务间切换时，根据复杂度选择合适的模型
需要更强推理能力或更高质量输出时，切换到高性能模型
在简单问答或高频操作场景下，使用成本更低的模型
对同一问题在不同模型下的表现进行对比验证
在成本、速度与效果之间做权衡时动态调整模型

2.1.4.10 privacy-settings 命令

在这里插入图片描述

用途: 查看和更新隐私设置。

使用方法:

/privacy-settings

说明: 管理数据使用和隐私相关配置。

使用场景:

初次使用 Claude Code 时，确认默认的数据和隐私策略
在处理敏感代码、业务逻辑或内部信息前，检查隐私配置是否符合要求
根据公司或团队的安全规范，调整数据使用相关设置
对 Claude 的数据使用范围有疑问时，进行核查和调整
在不同项目或环境下，确保隐私设置符合当前使用场景

2.1.5 账户和认证

2.1.5.1 login 命令

用途: 使用 Anthropic 账户登录。

使用方法:

/login

说明: 连接你的 Anthropic 账户以访问付费功能。

使用场景:

首次使用 Claude Code 时，完成账户登录以解锁完整功能
更换设备或重新安装环境后，重新登录账户
在需要使用高级模型或付费功能前进行登录操作
团队或企业账户场景下，切换到对应的 Anthropic 账号
登录状态异常或过期时，重新进行身份验证

2.1.5.2 logout 命令

用途: 从 Anthropic 账户登出。

使用方法:

/logout

使用场景:

在共享设备或公共环境中使用后，主动登出以保障账户安全
切换到其他 Anthropic 账户前，先退出当前登录状态
账号权限或订阅发生变更后，重新登录前执行登出操作
排查登录异常或认证问题时，作为重置步骤之一
不再继续使用 Claude Code 时，结束当前账户会话

2.1.5.3 upgrade 命令

在这里插入图片描述

用途: 升级到 Max 计划，获得更高的速率限制和更多 Opus 使用量。

使用方法:

/upgrade

说明: 打开订阅升级界面。

使用说明:

当当前订阅计划的使用额度或速率无法满足工作需求时使用
需要频繁使用高性能模型（如 Opus）进行复杂任务时进行升级
在团队或高强度开发场景中，避免因配额限制影响工作效率
升级前可结合 /usage、/cost 命令评估当前使用情况
升级操作会引导至官方订阅页面，按提示完成即可

2.1.6 GitHub 集成

2.1.6.1 install-github-app 命令

在这里插入图片描述

用途: 为仓库设置 Claude GitHub Actions。

使用方法:

/install-github-app

说明: 集成 Claude 到 GitHub 工作流中。

使用场景:

在代码仓库中引入自动化的代码审查或分析能力
希望在 Pull Request 阶段自动获得 Claude 的反馈和建议
团队协作中，将部分代码质量检查流程自动化
减少人工审查成本，提高代码评审效率和一致性
在持续集成（CI）流程中，引入 AI 辅助能力

2.1.6.2 pr-comments 命令

在这里插入图片描述

用途: 获取 GitHub Pull Request 的评论。

使用方法:

/pr-comments <PR编号>

示例:

/pr-comments 123

使用场景:

快速查看指定 PR 下的所有评论内容，无需切换到 GitHub 页面
在本地分析代码时，同步参考他人对 PR 的反馈意见
复盘或整理 PR 讨论过程，了解关键修改点和争议点
在代码修改后，确认是否有未处理的评论或待回应的问题

2.1.6.3 review 命令

在这里插入图片描述

用途: 审查 Pull Request。

使用方法:

/review
/review <PR编号>

说明: Claude 会分析 PR 的代码变更并提供反馈。

使用场景:

在合并 PR 之前，对代码变更进行一次自动化审查
辅助人工 Code Review，发现潜在问题或改进建议
对较大的 PR 进行整体结构和逻辑检查
在团队中统一代码审查标准，减少主观差异
快速了解 PR 的改动影响范围和风险点

2.1.6.4 security-review 命令

在这里插入图片描述

用途: 对当前分支上的待处理更改进行安全审查。

使用方法:

/security-review

说明: 自动检测潜在的安全问题和漏洞。

使用场景:

在代码合并前进行安全检查，降低引入漏洞的风险
对涉及鉴权、数据处理等敏感逻辑的修改进行重点审查
在发布或上线前，作为安全自检步骤之一
辅助开发者发现常见安全隐患（如输入校验、权限控制问题）
提升整体代码安全意识和质量基线

2.1.7 开发工具

2.1.7.1 ide 命令

在这里插入图片描述

用途: 管理 IDE 集成并显示状态。

使用方法:

/ide

说明: 查看和配置与各种 IDE（如 VS Code）的集成。

使用场景:

在 IDE 中使用 Claude Code 前，确认集成是否已正确连接
排查 IDE 与 Claude 之间的通信或功能异常
在多 IDE 环境中，查看当前启用的集成状态
切换开发环境或设备后，检查 IDE 集成是否需要重新配置
确认 Claude 是否能正确感知当前打开的项目和文件

2.1.7.2 mcp 命令

在这里插入图片描述

用途: 管理 MCP (Model Context Protocol) 服务器。

使用方法:

/mcp

说明: 配置和管理外部上下文提供者。

使用场景:

将外部系统（如内部文档、数据库、服务接口）接入 Claude 的上下文
在复杂项目中，引入额外的上下文来源以增强理解能力
管理和切换不同的 MCP 服务器配置
排查 Claude 无法获取某些外部信息时的上下文问题
在企业或定制化场景中，扩展 Claude 的上下文边界

2.1.8 插件和扩展

2.1.8.1 plugin 命令 (别名: plugins)

在这里插入图片描述

用途: 管理 Claude Code 插件。

使用方法:

/plugin
/plugins

说明: 安装、启用或禁用扩展功能。

使用场景:

根据项目需求安装额外功能插件，扩展 Claude Code 能力
启用或禁用插件以适配不同工作场景
排查异常行为时，检查是否由某个插件引起
在团队中统一插件配置，保证使用体验一致
尝试新插件或实验性功能，提升开发效率

2.1.9 诊断和调试

2.1.9.1 doctor 命令

在这里插入图片描述

用途: 诊断并验证 Claude Code 的安装和设置。

使用方法:

/doctor

说明: 自动检查常见问题，如配置错误、权限问题等。

使用场景:

Claude Code 无法正常工作或行为异常时进行快速自检
初次安装或升级后，确认环境和配置是否正确
排查权限、依赖或网络相关问题
在不同机器或环境中使用时，验证安装是否完整
向他人反馈问题前，先运行诊断以定位原因

2.1.9.2 status 命令

在这里插入图片描述

用途: 显示 Claude Code 状态，包括版本、模型、账户、API 连接和工具状态。

使用方法:

/status

说明: 全面的系统状态检查。

使用场景:

快速确认当前使用的 Claude Code 版本和模型
排查登录状态、API 连接或工具异常问题
在多账户或多环境下，确认当前会话配置是否正确
提交问题或反馈前，获取完整的运行状态信息
长时间运行过程中，检查整体系统健康状态

2.1.9.3 migrate-installer 命令

用途: 从全局 npm 安装迁移到本地安装。

使用方法:

/migrate-installer

说明: 更新安装方式的迁移工具。

使用场景:

Claude Code 官方推荐更新安装方式时进行迁移
从旧的全局安装方式切换到新的本地安装方案
排查因安装方式导致的权限或版本冲突问题
多项目环境下，希望不同项目使用独立的 Claude Code 安装
升级或重构开发环境时，统一调整安装方式

2.1.10 帮助和文档

2.1.10.1 help 命令

在这里插入图片描述

用途: 显示帮助信息和可用命令列表。

使用方法:

/help

2.1.10.2 feedback 命令 (别名: bug)

在这里插入图片描述

用途: 提交关于 Claude Code 的反馈。

使用方法:

/feedback
/bug

说明: 报告问题或提供改进建议。

反馈地址: https://github.com/anthropics/claude-code/issues

2.1.10.3 release-notes 命令

在这里插入图片描述

用途: 查看发布说明。

使用方法:

/release-notes

说明: 了解最新版本的新功能和改进。

2.1.10.4 exit 命令 (别名: quit)

用途: 退出 REPL（交互式命令行界面）。

使用方法:

/exit
/quit

2.1.11 自定义斜杠命令

当然大家可以在项目中创建 .claude/commands/ 目录来定义自定义命令：

.claude/
  commands/
    review-pr.md          # 自定义 PR 审查命令
    run-tests.md          # 自定义测试运行命令
    deploy.md             # 自定义部署命令

请参考: 自定义斜杠命令教程

2.2 常用工作流程

2.2.1 开始新项目

/login                    # 登录账户
/add-dir ./src           # 添加源代码目录
/init                    # 初始化 CLAUDE.md
/context                 # 检查上下文

2.2.2 代码审查流程

/review 123              # 审查 PR #123
/security-review         # 进行安全审查
/pr-comments 123         # 查看评论

2.2.3 监控和调试

/status                  # 检查系统状态
/agents                  # 查看运行中的代理
/bashes                  # 查看后台任务
/todos                   # 查看待办事项
/cost                    # 查看使用成本

2.2.4 配置和个性化

/config                  # 打开配置面板
/output-style            # 设置输出样式
/vim                     # 切换 Vim 模式
/hooks                   # 配置钩子
/permissions             # 管理权限

2.2.5 会话管理

/context                 # 查看当前上下文
/compact                 # 压缩对话保留摘要
/rewind                  # 回退到之前状态
/clear                   # 完全清除重新开始

2.3 Claudia 可视化命令（Claude Code 的“控制台 + 仪表盘”）

Claudia 官网地址：https://claudia.so

在这里插入图片描述

对于不少开发者来说，纯终端方式虽然强大，但在会话管理、上下文理解、成本监控等方面仍然存在一定心智负担。
尤其是当你：

同时运行多个 Agent
管理大量上下文文件
频繁使用 /compact、/rewind
关注 Token / Cost / Usage
希望快速回顾历史对话与操作轨迹

这时，仅靠 CLI 已经不够直观，Claudia 正是为了解决这些问题而生。

2.3.1 什么是 Claudia？

Claudia 是一个专为 Claude Code 设计的 本地可视化控制台（UI Dashboard），本质上是：

Claude Code CLI 的图形化外壳 + 会话/上下文可视化工具

它不会替代 Claude Code，而是：

复用你已有的 Claude Code 环境
直接读取 Claude Code 的状态、会话、上下文、成本等信息
将原本分散在 /status、/context、/agents、/cost 中的信息集中展示

在这里插入图片描述

一句话总结：

Claude Code 负责“能力”，Claudia 负责“可视化与掌控感”。

2.3.2 Claudia 能做什么？

结合前面 Claude Code 命令汇总，Claudia 的核心能力可以理解为 “把命令变成面板”。

2.3.2.1 会话与历史可视化（替代多次 `/resume`）

在 CLI 中，你需要靠：

/resume
/export
/clear

来管理会话，而在 Claudia 中：

所有历史会话 按时间轴展示
可直接点击查看某一次完整对话
清晰区分不同项目、不同上下文
快速回溯「当时是怎么一步步推理的」

点击首页的“CC Project”，就可以看到历史多个历史会话：
在这里插入图片描述

适合场景：

回顾复杂问题的完整推理过程
技术复盘、博客写作
找回几天前做过但忘记细节的分析

2.3.2.2 上下文可视化（/context 的图形版）

在这里插入图片描述

CLI 中的 /context 是彩色文本，而 Claudia 会：

以 文件树 / 列表形式 展示当前上下文
明确标出每个文件的上下文占比
提醒你「上下文是否已经接近上限」

这让你可以更直观地判断：

是否需要 /compact
是否引入了无关目录
Claude 为什么会“理解错”

2.3.2.3 Agent / Bash 任务监控（/agents + /bashes 的统一视图）

在这里插入图片描述

在终端里，你需要反复输入：

/agents
/bashes
/todos

而 Claudia 中：

所有 Agent 状态一屏可见
显示运行中 / 已完成 / 异常
任务之间的关系更清晰
非常适合长时间、多任务运行的场景

典型使用场景：

让 Claude 后台跑测试 / 扫描 / 重构
你同时做别的事情
回来一眼就知道哪些任务已经完成

2.3.2.4 成本 & Token 可视化（/cost + /usage 的升级版）

在这里插入图片描述

相比 CLI 中的纯文本输出，Claudia 会：

可视化 Token 消耗趋势
区分不同会话、不同模型的成本
快速发现「异常消耗」

这对以下人群尤其重要：

高频使用 Claude Code 的开发者
团队或企业账号
经常切换 Sonnet / Opus 的用户

2.3.3 Claudia 适合谁？

并不是所有人都必须使用 Claudia，它更适合以下场景：

如果项目存在如下情况，强烈推荐使用：

长时间使用 Claude Code（>1 小时/天）
同时运行多个 Agent / Bash
大型项目、多目录上下文
关注成本、上下文管理

2.3.4 Claudia vs 纯 CLI 使用建议

场景	推荐方式
快速问答、一次性任务	纯 CLI
长对话 / 架构设计	CLI + Claudia
多 Agent / 后台任务	Claudia
成本与使用监控	Claudia
博客、复盘、回顾	Claudia

2.4 小结

本章把 Claude Code 的 CLI 命令按能力域系统梳理了一遍，核心收获是：

知道“有哪些命令可用”以及各自解决什么问题
能把常用命令沉淀成固定工作流（初始化/导出/复查/权限）
理解关键配置对行为与安全边界的影响

下一章会进一步拆开“命令背后的数据流动”，把本地文件与隐私边界讲清楚。

第三部分：原理与边界（数据流动与安全）

在这里插入图片描述
本章从“一条命令”出发，拆解 Claude Code 在本地到底做了什么。

重点包括：~/.claude 与项目 .claude/ 的目录结构、配置文件的层级与优先级、命令执行的记录与快照，以及与隐私/数据安全相关的边界。

读完你应该能清楚判断：哪些数据保存在本地、哪些可能被发送到模型侧、以及如何用配置把风险控制在可接受范围内。

3.1 Claude Code 本地目录结构揭秘

当你第一次运行 claude 命令时，系统会在你的主目录下创建 ~/.claude 文件夹。让我们先看看这个目录里藏着什么秘密：

在这里插入图片描述
目录解析如下：

目录	备注
debug	调试日志和错误信息
file-history	文件修改历史记录
history.jsonl	全局命令历史（跨项目）
ide	IDE 集成相关配置
projects	项目级别的会话数据
shell-snapshots	Shell 命令执行快照
statsig	统计和特性开关数据
todos	任务列表的 JSON 数据

3.1.1 核心目录详解

3.1.1.1 projects 目录：项目数据的大本营

在这里插入图片描述

每个项目都有一个独立的子目录，命名规则是将项目路径转换为目录名（斜杠替换为连字符）。例如：

~/.claude/projects/
├── -Users-yanglinwei-Desktop-xxx/
│   ├── .timelines/                    # 时间线数据
│   ├── cca400a9-c8db-4cb0-943c-314875065f34.jsonl  # 对话会话记录
│   └── settings.json                  # 项目级配置（如果存在）

每个 .jsonl 文件记录了完整的对话历史，包括：

用户输入的命令和问题
Claude 的回复和工具调用
上下文管理和 token 使用情况
时间戳和会话元数据

3.1.1.2 history.jsonl：全局命令索引

在这里插入图片描述

这个文件记录你在所有项目中执行过的命令，格式如下：

{
  "display": "/privacy-settings ",
  "pastedContents": {},
  "timestamp": 1767777200862,
  "project": "/Users/yanglinwei/Desktop/test-project"
}

重要提示：这个文件包含你的项目路径信息，如果共享账号，其他人可以看到你曾经访问过哪些项目目录。

3.1.1.3 todos 目录：任务追踪系统

在这里插入图片描述

Claude Code 的任务管理功能会在这里存储 JSON 文件，每个文件对应一个任务列表。文件命名格式：

<session-id>-agent-<agent-id>.json

3.1.2 项目级配置目录：.claude

在这里插入图片描述

在你的项目根目录下，Claude Code 还会创建 .claude/ 配置目录：

your-project/
└── .claude/
    ├── settings.json          
    ├── settings.local.json    
    ├── CLAUDE.md              
    ├── .mcp.json              
    └── commands/             
        ├── review.md
        └── test.md

文件	描述
settings.json	团队共享配置（应提交到 Git）
settings.local.json	个人配置（不应提交，需加入 .gitignore）
CLAUDE.md	项目上下文和指令
.mcp.json	MCP 服务器配置
commands/	自定义斜杠命令

3.2 配置文件层次结构与优先级

Claude Code 使用 分层配置系统，优先级从高到低如下：

配置层级	文件路径	用途	是否提交 Git
托管配置	由 IT 部门管理	企业级策略（无法覆盖）	-
命令行参数	`claude --model=opus`	临时会话覆盖	-
本地项目配置	`.claude/settings.local.json`	个人项目设置（如 API Key）	否
共享项目配置	`.claude/settings.json`	团队共享设置	是
用户全局配置	`~/.claude/settings.json`	个人全局默认	-
遗留配置	`~/.claude.json`	旧版配置文件	-

配置示例：settings.local.json

{
  "permissions": {
    "allow": [
      "Read(//Users/yanglinwei/Library/**)",
      "Read(//Users/yanglinwei/.config/**)",
      "WebFetch(domain:code.claude.com)",
      "WebSearch"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "ask": []
  },
  "env": {
    "ANTHROPIC_API_KEY": "your-api-key-here"
  }
}

3.2.1 配置项完整说明

配置项	类型	说明	示例
permissions.allow	数组	允许的工具和路径（支持通配符）	“Read(./src/**)”
permissions.deny	数组	拒绝访问的工具和路径	“Read(./.env)”
permissions.ask	数组	需要确认的操作	“Bash(*)”
env	对象	环境变量设置	{“API_KEY”: “xxx”}
commit.attribution	字符串	Git 提交署名	“Co-Authored-By: Claude”
pr.attribution	字符串	PR 描述附加信息	“Generated by Claude”
enabledPlugins	对象	启用的插件列表	{“plugin-name@marketplace”: true}
model	字符串	默认模型选择	“claude-sonnet-4-5-20250929”

参考文档：Claude Code Settings

3.3 一条命令的完整数据流程

让我们追踪一条简单的命令 claude "帮我创建一个 README.md 文件" 的完整生命周期。

3.3.1 Step 1：命令解析与会话初始化

用户输入 → CLI 解析 → 加载配置层次 → 检查权限 → 创建会话 ID

本地文件操作：

读取 ~/.claude/settings.json 和 .claude/settings.local.json
加载 .claude/CLAUDE.md（如果存在）作为上下文
在 ~/.claude/projects/<project-hash>/ 创建新的 .jsonl 会话文件
向 ~/.claude/history.jsonl 追加命令记录

3.3.2 Step 2：网络请求与 API 交互

构建 API 请求 → 发送到 Anthropic 服务器 → 流式接收响应

上传到服务器的数据：

用户的提示词：“帮我创建一个 README.md 文件”
系统提示词：包含 Claude Code 的工具定义和行为规则
上下文内容：
- .claude/CLAUDE.md 的内容（如果存在）
- 之前的对话历史（如果是继续会话）
- 读取的文件内容（如果 Claude 请求读取）
权限配置：允许/拒绝的工具列表

不会上传的数据：

本地文件系统的完整结构
未被 Claude 明确请求读取的文件内容
其他项目的会话历史
你的 API Key 或敏感环境变量

3.3.3 Step 3：工具调用与本地执行

Claude 可能会请求使用以下工具（取决于权限配置）：

工具名称	作用	本地操作	数据上传
`Read`	读取文件	读取指定文件内容	文件内容发送到服务器
`Write`	写入文件	创建或覆盖文件	仅记录操作，不上传文件内容
`Edit`	编辑文件	字符串替换操作	仅记录操作
`Bash`	执行命令	运行 Shell 命令	命令输出发送到服务器
`Glob`	搜索文件	匹配文件路径	文件路径列表发送到服务器
`Grep`	搜索内容	搜索文件内容	匹配的行内容发送到服务器

关键安全点：

Claude 必须先调用 Read 工具才能看到文件内容
你可以通过 permissions.deny 阻止访问敏感文件
每个工具调用都会记录在 .jsonl 会话文件中

3.3.4 Step 4：响应处理与本地更新

接收流式响应 → 显示在终端 → 记录到会话文件 → 更新 token 统计

本地文件写入：

会话记录保存到 ~/.claude/projects/<project-hash>/<session-id>.jsonl
如果执行了 Write 或 Edit，修改历史保存到 ~/.claude/file-history/
Token 使用统计更新到 ~/.claude/statsig/

3.4 隐私与安全

3.4.1 共享账号是否会导致本地数据泄漏？

不会。 Claude CLI / Claude Code 的本地配置、历史记录和项目文件（如 ~/.claude/*）
只存在于当前机器，不会因为共享账号或 API Key 而同步到其他设备。

如果你在机器 A 使用 Claude，即使他人在机器 B 使用同一账号或 Key，也无法看到你机器 A 上的任何本地文件或历史记录。

3.4.2 共享账号会泄漏什么？

共享账号或 API Key 的风险，不在本地文件，而在你“发送出去的内容”。

泄漏场景	会泄漏的内容
共享账号 / API Key	你发送给 Claude 的 Prompt、代码、业务描述
使用第三方中转或代理	请求中的全部明文内容
API Key 被他人持有	他人可完全冒充你调用 Claude

简单理解：Key = 你的身份，共享 Key 就是共享“你本人”。

3.4.3 本地使用时仍需注意的风险

以下风险 只影响当前机器，与其他设备无关：

数据	存储位置	风险
对话历史	`~/.claude/projects/`	机器被共用或入侵时可被读取
使用记录	`~/.claude/history.jsonl`	暴露项目路径与使用习惯
API Key	本地配置或环境变量	被读取后可被完全滥用

3.4.4 推荐的最小安全配置

3.4.4.1 禁止读取敏感文件

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Read(./**/*.key)",
      "Read(./**/*.pem)"
    ]
  }
}

3.4.4.2 使用环境变量存放 API Key

export ANTHROPIC_API_KEY="sk-ant-xxx"

3.4.4.3 限制本地目录权限

chmod 600 ~/.claude/settings.json
chmod 700 ~/.claude/projects/

一句话总结：

本地文件不会跨设备泄漏，真正泄漏的，永远是你“主动发出去的内容”。

3.5 数据流动可视化示意图

───────────────────────────────────────────────────────────────
		                          用户输入命令                           
		                     claude "帮我创建文件"                       
───────────────────────────┬───────────────────────────────────
									                           │
                            								   ▼
───────────────────────────────────────────────────────────────
		                        本地配置加载                            
		                                                               
		   ~/.claude/settings.json ─┐                                   
		   .claude/settings.json    ├─→ 合并配置 → 权限检查            
		   .claude/CLAUDE.md       ─┘                                   
───────────────────────────┬───────────────────────────────────
                            │
                            ▼
───────────────────────────────────────────────────────────────
		                     创建本地会话记录                            
		                                                               
		   ~/.claude/projects/<project>/                               
		   └── <session-id>.jsonl   ← 开始记录                          
───────────────────────────┬───────────────────────────────────
                            │
                            ▼
───────────────────────────────────────────────────────────────
		                  构建 API 请求并发送                           
		                                                               
		   上传内容：                                                  
		   • 用户提示词                                                
		   • 系统提示词（工具定义）                                    
		   • CLAUDE.md 内容                                            
		   • 权限配置                                                  
		                                                               
		   HTTPS  →  Anthropic API 服务器                               
───────────────────────────┬───────────────────────────────────
                            │
                            ▼
───────────────────────────────────────────────────────────────
		                    Claude 流式响应                             
		                                                               
		   可能包含工具调用：                                           
		   • Read("/path/to/file")   → 读取文件                         
		   • Write(...)              → 创建 / 修改文件                 
		   • Bash("ls -la")          → 执行命令                         
───────────────────────────┬───────────────────────────────────
                            │
                            ▼
───────────────────────────────────────────────────────────────
		                      本地工具执行                               
		                                                               
		   权限检查 → 执行操作 → 返回结果                               
		   结果上传到服务器 ← 供 Claude 下一步推理使用                  
───────────────────────────┬───────────────────────────────────
                            │
                            ▼
───────────────────────────────────────────────────────────────
		                   最终响应与本地保存                           
		                                                               
		   • 显示在终端                                                
		   • 保存到 .jsonl 会话文件                                    
		   • 更新 file-history/（如有文件修改）                        
		   • 更新 history.jsonl                                        
───────────────────────────────────────────────────────────────

3.6 常见问题解答

3.6.1 Q1： Claude Code 会上传我的整个代码库吗？

A: 不会。Claude 只能访问你明确授权的文件。它需要先调用 Read 工具才能看到文件内容，且每次调用都会受到权限系统的控制。

3.6.2 Q2：我可以完全离线使用 Claude Code 吗？

A: 不可以。Claude Code 的核心推理能力依赖于 Anthropic 的云端 API。但你可以控制哪些数据被发送到服务器。

3.6.3 Q3：共享账号安全吗？

A: 不推荐。虽然 Anthropic 服务器端的数据是隔离的，但本地的 ~/.claude/ 目录会包含所有用户的项目路径和对话历史。如果多人共用同一台机器和账号，存在隐私泄漏风险。

3.6.4 Q4：如何彻底删除我的对话历史？

# 删除所有项目会话
rm -rf ~/.claude/projects/

# 删除全局命令历史
rm ~/.claude/history.jsonl

# 如果要完全重置
rm -rf ~/.claude/

3.6.5 Q5： `permissions.deny` 真的可靠吗？

根据第三方测试（参考 eesel.ai 博客），deny 规则偶尔会被忽略。最佳实践：

使用多层防护（文件权限 + deny 规则）
不要将敏感文件放在项目目录
定期审查 debug 日志

3.7 实战技巧：优化数据流动效率

3.7.1 使用 CLAUDE.md 减少重复上传

如果你有固定的项目上下文（如编码规范、架构说明），写入 .claude/CLAUDE.md：

# 项目上下文

## 技术栈
- 后端：Python + FastAPI
- 数据库：PostgreSQL
- 测试：pytest

## 编码规范
- 使用 Black 格式化
- 类型提示必填
- 测试覆盖率 > 80%

这样 Claude 会自动在每次会话开始时加载这些信息，无需每次对话都重新说明。

3.7.2 配置 Hooks 自动化流程

在 .claude/settings.json 中配置钩子，在工具执行后自动运行命令：

{
  "hooks": {
    "after:Write": [
      {
        "command": "black {file_path}",
        "if": "{file_path} matches **/*.py"
      }
    ]
  }
}

参考文档：Claude Code Hooks

3.7.3 自定义斜杠命令加速工作流

在 .claude/commands/review.md 创建命令：

请对当前项目的代码进行审查，重点关注：
1. 安全漏洞
2. 性能问题
3. 代码风格一致性

输出 Markdown 格式的报告。

使用：

claude /review

3.8 小结

本章围绕本地数据与执行链路，给出一个可操作的结论：

Claude Code 的会话/配置/日志主要落在 ~/.claude/ 与项目 .claude/
风险点在于你主动提供的上下文与可执行动作，应通过 permissions 与环境变量进行约束
用 CLAUDE.md、斜杠命令与 Hooks 把流程“固化+门禁化”，兼顾效率与安全

第四部分：工程化落地（Hooks / Subagents / Skills）

4.1 Hooks：自动化事件触发

在这里插入图片描述

本章介绍 Hooks：把“你记得做”的重复动作，变成“系统自动做”的工程化门禁。

我们会围绕 Hooks 的触发时机、命令型与提示型两类用法，以及常见落地场景（格式化/lint/单测、危险命令拦截、敏感信息校验等）展开。

目标是让 Claude Code 的每次执行都更可控、更可审计、更稳定。

4.1.1 Hooks 是什么？

Hooks 是 Claude Code 的事件驱动自动化系统：在特定事件触发时，自动执行一组 Hook。

它主要有两种形态：

命令型 Hooks（command）：运行 Shell 命令/脚本，适合自动化与校验（格式化、检查、通知、跑测试……）。
提示型 Hooks（prompt）：在 Stop / SubagentStop 事件里，让 Claude 再做一次“停下前的质量检查”，根据结果决定继续还是停止。

你可以把它理解为：

SessionStart / End：会话生命周期钩子；
PreToolUse / PostToolUse：工具执行前/后钩子（Write/Edit/Bash/Read…）；
Stop / SubagentStop：模型准备结束前的“收尾门禁”；
Notification：系统通知的自定义处理。

4.1.2 Hooks 配置（用户级 vs 项目级）

Claude Code 支持分层配置，Hooks 通常按是否团队共享来决定目录。

项目级（推荐团队共享）:

文件：{project}/.claude/settings.json
适合：团队统一的格式化、测试、危险命令拦截、质量门禁等
配套建议：把脚本也放进仓库，例如 {project}/.claude/hooks/*.sh，让团队开箱即用

项目级本地（仅自己用，不提交）:

文件：{project}/.claude/settings.local.json
适合：个人路径相关脚本、个人通知方式、私有工具等
配套建议：加入 .gitignore

用户级（跨项目生效）：

文件：~/.claude/settings.json
适合：你个人的通用 Hooks（比如任何项目都启用的通知/危险命令拦截）

小贴士：团队规范建议 “项目级为主、用户级为辅”，项目级让仓库可复制；用户级放个人偏好。

4.1.3 八种事件类型汇总

事件	触发时机	Hook 类型	常见用途
SessionStart	会话开始	命令型	初始化环境、检查依赖、打印提示
SessionEnd	会话结束	命令型	清理临时文件、记录统计
UserPromptSubmit	用户提交输入前	命令型	输入验证、关键词拦截、注入上下文
PreToolUse	工具执行前	命令型	危险命令拦截、参数校验、审计
PostToolUse	工具执行后	命令型	自动格式化、自动测试、生成变更摘要
Stop	Claude 决定停止前	提示型	质量门禁（lint/test/git status）
SubagentStop	子代理停止前	提示型	子任务验收（比如“测试是否补齐”）
Notification	Claude 发送通知时	命令型	转发通知（系统通知/Slack/飞书等）

4.1.4 命令型 Hooks

写脚本就能自动化

4.1.4.1 基础语法（最常用）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/format.sh",
            "blocking": false
          }
        ]
      }
    ]
  }
}

关键点：

matcher：用于筛选工具（通常写正则/或模式串），比如 Write|Edit、Bash。
blocking：
- true：Hook 失败会阻断当前动作（适合安全校验、门禁）
- false：Hook 失败不阻断（适合格式化、统计、通知）

4.1.4.2 Hook 能拿到什么上下文？

命令型 Hooks 通常可以通过环境变量拿到上下文（不同事件变量略有差异，常见如）：

变量名	说明
TOOL_NAME	工具名称（如 `Write`/`Edit`/`Bash`）
TOOL_INPUT	工具输入（JSON 字符串）
TOOL_INPUT_FILE_PATH	文件路径（Write/Edit 常用）
TOOL_OUTPUT	工具输出（PostToolUse 常用）
USER_MESSAGE	用户输入（UserPromptSubmit）
CLAUDE_WORKING_DIR	当前工作目录
NOTIFICATION_MESSAGE	通知内容（Notification，JSON）

更稳妥的写法：脚本里同时支持读取 stdin（JSON）与环境变量，避免某些环境差异导致取不到值。

4.1.4.3 退出码怎么控制“阻断/不阻断”？

常见约定（建议你按这个写，团队最好统一）：

exit 0   # 成功，继续
exit 2   # 阻断错误（blocking=true 时会拦下本次操作）
exit 1   # 非阻断错误（记录/提示，但不中断主流程）

4.1.5 提示型 Hooks

让 Claude 在“停下前”做质量门禁

提示型 Hooks 仅用于 Stop / SubagentStop：当 Claude 觉得“差不多可以结束了”，会先跑一次这个提示，让它自检并输出 JSON 决策。

4.1.5.1 基础语法

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查是否满足停止条件。返回 JSON: {\"decision\":\"stop\"|\"continue\",\"feedback\":\"说明\"}"
          }
        ]
      }
    ]
  }
}

4.1.5.2 响应格式（核心）

{
  "decision": "continue",
  "feedback": "请先运行测试并修复 lint。"
}

你可以用它来实现 “Claude 自己给自己验收” 的体验，不满足条件就继续把事情做完，满足才停。

4.1.6 案例模板

下面的模板尽量遵循一个原则：高风险校验 blocking=true，耗时工作 blocking=false。

依赖提示：后面的脚本示例会用到 jq 来解析 JSON（macOS 可用 brew install jq）。

4.1.6.1 案例：SessionStart 做环境体检（不阻断）

session-init.sh：检查 Node/Python/Git 状态、依赖是否安装等（按你的项目改）。

.claude/settings.json配置如下：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/session-init.sh", "blocking": false }
        ]
      }
    ]
  }
}

session-init.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

echo "🚀 Claude Code SessionStart"
echo "cwd: ${CLAUDE_WORKING_DIR:-$(pwd)}"

if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
  echo "git branch: $(git branch --show-current)"
  changes="$(git status --porcelain | wc -l | tr -d ' ')"
  if [[ "${changes}" != "0" ]]; then
    echo "⚠️  uncommitted changes: ${changes}"
  fi
fi

if [[ -f package.json ]]; then
  command -v node >/dev/null 2>&1 && echo "node: $(node --version)"
  [[ -d node_modules ]] || echo "📦 tip: run npm install"
fi

if [[ -f requirements.txt ]]; then
  command -v python >/dev/null 2>&1 && echo "python: $(python --version 2>&1 | head -n 1)"
  [[ -n "${VIRTUAL_ENV:-}" ]] || echo "🐍 tip: activate venv"
fi

4.1.6.2 案例：PreToolUse 拦截危险 Bash（阻断）

guard-bash.sh 思路：从 TOOL_INPUT（或 stdin JSON）里取出 command，匹配 rm -rf、git push --force 等高危模式，命中就 exit 2 并在 stderr 输出原因。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/guard-bash.sh", "blocking": true }
        ]
      }
    ]
  }
}

guard-bash.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

input_json="${TOOL_INPUT:-}"
if [[ -z "${input_json}" ]]; then
  input_json="$(cat || true)"
fi

cmd="$(echo "${input_json}" | jq -r '.command // empty' 2>/dev/null || true)"
if [[ -z "${cmd}" ]]; then
  exit 0
fi

if [[ "${cmd}" == *"[claude-allow-danger]"* ]]; then
  exit 0
fi

deny_patterns=(
  '(^|[[:space:]])rm[[:space:]]+-rf[[:space:]]+(/|~|\\$HOME)([[:space:]]|$)'
  '(^|[[:space:]])git[[:space:]]+push([[:space:]].*)?--force'
  '(^|[[:space:]])git[[:space:]]+reset([[:space:]].*)?--hard'
  '(^|[[:space:]])chmod[[:space:]]+-R[[:space:]]+777'
)

for pattern in "${deny_patterns[@]}"; do
  if echo "${cmd}" | grep -Eq "${pattern}"; then
    echo "❌ 已阻断高危命令（PreToolUse）：" >&2
    echo "    ${cmd}" >&2
    echo "如确认要执行，请在命令末尾加 [claude-allow-danger] 作为显式确认。" >&2
    exit 2
  fi
done

exit 0

4.1.6.3 案例：PreToolUse 做敏感信息检测（阻断）

适用场景：Write/Edit 写入内容前，扫描是否疑似 Key/密码/Token，命中直接拦截。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/check-secrets.sh", "blocking": true }
        ]
      }
    ]
  }
}

check-secrets.sh示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

input_json="${TOOL_INPUT:-}"
if [[ -z "${input_json}" ]]; then
  input_json="$(cat || true)"
fi
content="$(echo "${input_json}" | jq -r '.new_string // .content // ""' 2>/dev/null || true)"

patterns=(
  'AKIA[0-9A-Z]{16}'                  # AWS Access Key
  'ghp_[a-zA-Z0-9]{36}'               # GitHub PAT
  'sk-[a-zA-Z0-9]{32,}'               # API Key（示例）
  '(?i)password\\s*[:=]\\s*["\x27][^"\x27]+["\x27]'
  '(?i)api[_-]?key\\s*[:=]\\s*["\x27][^"\x27]+["\x27]'
)

for pattern in "${patterns[@]}"; do
  if echo "${content}" | grep -Pq "${pattern}" 2>/dev/null; then
    echo "❌ 检测到潜在敏感信息，已阻断写入（PreToolUse）" >&2
    echo "pattern: ${pattern}" >&2
    echo "建议：改用环境变量/密钥管理服务，不要把 Key 写进仓库。" >&2
    exit 2
  fi
done

exit 0

4.1.6.4 案例：PostToolUse 自动格式化 + 自动跑测试（不阻断）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/format.sh", "blocking": false },
          { "type": "command", "command": "./.claude/hooks/auto-test.sh", "blocking": false }
        ]
      }
    ]
  }
}

format.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

file="${TOOL_INPUT_FILE_PATH:-}"
[[ -n "${file}" && -f "${file}" ]] || exit 0

case "${file}" in
  *.ts|*.tsx|*.js|*.jsx|*.json)
    command -v prettier >/dev/null 2>&1 && prettier --write "${file}" >/dev/null 2>&1 || true
    command -v eslint >/dev/null 2>&1 && eslint --fix "${file}" >/dev/null 2>&1 || true
    ;;
  *.py)
    command -v black >/dev/null 2>&1 && black "${file}" >/dev/null 2>&1 || true
    command -v isort >/dev/null 2>&1 && isort "${file}" >/dev/null 2>&1 || true
    ;;
  *.go)
    command -v gofmt >/dev/null 2>&1 && gofmt -w "${file}" >/dev/null 2>&1 || true
    ;;
  *.rs)
    command -v rustfmt >/dev/null 2>&1 && rustfmt "${file}" >/dev/null 2>&1 || true
    ;;
esac

exit 0

auto-test.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

file="${TOOL_INPUT_FILE_PATH:-}"
[[ -n "${file}" && -f "${file}" ]] || exit 0

if echo "${file}" | grep -Eq '(\\.test\\.|\\.spec\\.|/tests?/|__tests__)'; then
  exit 0
fi

if [[ -f package.json ]] && command -v npm >/dev/null 2>&1; then
  if echo "${file}" | grep -Eq '\\.(ts|tsx|js|jsx)$'; then
    echo "🧪 running minimal js/ts tests (best effort)"
    npm test --silent 2>/dev/null || true
  fi
fi

if [[ -f pyproject.toml || -f requirements.txt ]] && command -v pytest >/dev/null 2>&1; then
  if echo "${file}" | grep -Eq '\\.py$'; then
    echo "🧪 running minimal python tests (best effort)"
    pytest -q 2>/dev/null || true
  fi
fi

exit 0

建议：

格式化脚本按后缀选择 prettier/black/gofmt/rustfmt
测试脚本“只跑与当前文件相关的最小集合”，避免每次都全量测试拖慢体验

4.1.6.5 案例：Notification 做系统通知（不阻断）

notify.sh（macOS）可以用 osascript 或 terminal-notifier，从 NOTIFICATION_MESSAGE 里取 title/message 发系统通知。

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/notify.sh", "blocking": false }
        ]
      }
    ]
  }
}

notify.sh 示例脚本如下：

#!/usr/bin/env bash
set -euo pipefail

msg_json="${NOTIFICATION_MESSAGE:-}"
if [[ -z "${msg_json}" ]]; then
  msg_json="$(cat || true)"
fi

title="$(echo "${msg_json}" | jq -r '.title // "Claude Code"' 2>/dev/null || echo "Claude Code")"
message="$(echo "${msg_json}" | jq -r '.message // empty' 2>/dev/null || true)"
[[ -n "${message}" ]] || exit 0

if command -v terminal-notifier >/dev/null 2>&1; then
  terminal-notifier -title "${title}" -message "${message}" -group "claude-code" >/dev/null 2>&1 || true
  exit 0
fi

osascript -e "display notification \"${message}\" with title \"${title}\"" >/dev/null 2>&1 || true
exit 0

4.1.7 常见问题

问题一：Hook 不执行

可以通过如下方式排查：

开调试：

claude --debug="hooks"

检查脚本可执行权限：

chmod +x ./.claude/hooks/*.sh

脚本自测（用 stdin 模拟 JSON）：

echo '{"sessionId":"test"}' | ./.claude/hooks/session-init.sh

问题二：无故被阻断

blocking=true 的 Hook 一定要做到：

只在命中明确条件时才 exit 2
stderr 输出清晰原因（让 Claude 能把“为什么被拦”解释给你）

问题三：变慢很明显

把耗时任务（全量测试、扫描整个仓库）改成 blocking=false 或改成“增量/抽样”
在脚本里加超时/短路条件（比如只对特定目录、特定后缀执行）

4.1.8 小结

本章小结：Hooks 是把质量与安全“流程化”的关键部件。

用 command hooks 自动化格式化/lint/测试与通知
用 prompt hooks 在 Stop 阶段做最终自检与门禁
通过阻断/后台/提醒三种策略，让自动化既严格又不拖慢效率

下一章将进入 Subagents：把角色与职责工程化，提升复杂任务的并行与可验收性。

4.2 Subagents：AI 角色工程化

在这里插入图片描述
本章讲 Subagents：把常见“工种”固化成可复用的子代理，让主对话负责编排、子代理负责专业产出。

我们会重点看角色拆分的收益（降低上下文污染、避免自审自过、提升复用性）、Subagent 的配置方式与权限边界，以及在真实任务里的协作模式。

读完你可以按团队需要定义测试/安全/代码评审/文档等专职角色，并稳定复用。

4.2.1 Subagents 是什么？

Subagents（子代理）是预配置的 AI 人格，每个 Subagent 都有：

独立的指令与风格：可以理解为一个长期雇佣的 “测试工程师/安全审计/文档工程师”
相对隔离的上下文：减少对主对话的污染，让主对话保持 “编排者” 角色
独立的工具权限：比如只允许 Read/Grep，禁止 Bash/Write）

可以把主 Claude 理解成 Tech Lead / Orchestrator：拆任务、分派子代理、汇总结果、把子代理当成 “专职工种”。

4.2.2 Subagents 配置

Subagents 本质上就是一组 Markdown 文件，按作用域放两种位置：

用户级（跨项目复用）：

目录：~/.claude/agents/
适合：你个人常用的通用角色（比如安全审计、代码审查、文档写作）

项目级（推荐团队共享）：

目录：{project}/.claude/agents/
适合：和项目强绑定的角色（比如“本项目测试工程师：约定 Jest + 特定目录结构”）

团队最佳实践：把项目级 Agents 版本化提交到 Git，让新同学克隆仓库即可拥有同一套“AI 工种”。

如果把 Subagents、Hooks、Commands 都落到项目里，结构通常长这样：

your-project/
├── .claude/
│   ├── settings.json
│   ├── agents/
│   │   ├── test-writer.md
│   │   ├── code-reviewer.md
│   │   └── security-auditor.md
│   ├── hooks/
│   │   ├── format.sh
│   │   ├── auto-test.sh
│   │   └── guard-bash.sh
│   └── commands/
│       ├── review.md
│       └── test.md
└── CLAUDE.md

4.2.2.1 配置格式

Subagent 文件是 “带 YAML Frontmatter 的 Markdown”，结构非常固定，例如：

---
name: test-writer
description: 专门编写单元测试和集成测试的 AI 助手
tools: Read, Write, Bash, Grep
model: sonnet
permissionMode: inherit
skills: api-testing
---

# Test Writer Agent

你是一位测试专家，专注于编写高质量的测试代码。
...

可以把它理解为：

YAML 区：机器可读（名字、权限、模型、技能）
正文：人类可读（角色定义、工作流程、输出格式、约束条件）

4.2.2.2 核心配置

下面是最常用也最影响效果的四组字段。

4.2.2.2.1 tools（让子代理“能做什么”）

tools 是最直观的安全边界与能力边界：

Read/Grep：读代码、搜代码（适合审查类）
Write/Edit：写代码、改代码（适合实现类）
Bash：跑命令（适合测试/构建/脚手架类）

建议：能不开放就不开放。比如“安全审计”大多数时候只需要 Read, Grep。

4.2.2.2.2 permissionMode（让子代理“默认怎么申请权限”）

常见模式：

inherit：继承主会话的权限策略（最常用、最稳）
allow-all / deny-all / ask-all：按字面意思理解

建议：团队场景以 inherit 为主；确实需要强约束时再用 deny-all（例如“纯审查只读”）。

4.2.2.2.3 model（让子代理“用哪个模型”）

如果你的团队对成本/速度/质量有分层策略，可以这样用：

主对话用更强模型负责编排与关键决策
子代理按角色选择模型：例如测试/文档用更快模型，安全审计用更强模型

具体模型名建议用你在 settings 里配置的别名（便于后续统一切换）。

4.2.2.2.4 skills（把可复用步骤注入到子代理）

Skills 更像“标准作业程序（SOP）模板”，Subagent 更像“岗位说明书”：

Skill：如何做（步骤/命令/输出结构）
Subagent：谁来做（角色、边界、口吻、工具权限）

把 Skill 挂到 Subagent 上，能让团队把重复流程 “标准化”：例如 api-testing、db-migration、release-checklist。

4.2.3 Subagents 用法

交互式的用法如下，输入以下命令：

/agents

通过这个命令，可以：

创建新 Agent
选择某个 Agent 执行任务
查看正在运行/已完成的 Agent 状态

当然也可以通过CLI 直接指定：

claude --agents test-writer "为 src/api/user.js 编写测试"

也可以用 JSON 临时定义一个轻量代理（适合临时任务）：

claude --agents '{"name":"reviewer","tools":["Read","Grep"]}' "审查 src/ 下的潜在安全问题"

当多个 Agent 并行干活时，可以理解/agents 就是 “任务面板”，把 “后台任务” 变得可见，也可以通过如下方式判断是否适合使用Subagent：

适合 Subagent：审查/测试/文档/重构这类“有固定输出结构、可重复执行”的工种

适合 Subagent：你希望它有严格边界（只读/禁 Bash/固定输出格式）

不适合 Subagent：你还在探索需求、频繁变更方向（主对话更灵活）

不适合 Subagent：一次性小任务（新建文件改两行），直接主对话更快

4.2.4 最佳实践

4.2.4.1 实践原则

让子代理“可控、可复用、可验收”

① 子代理的提示不要写成“百科全书”

Subagent 的正文更像岗位说明书：只放长期有效的原则、约束、输出格式；项目细节放到 CLAUDE.md 或 Skill 里。

② 给每个 Agent 定一个“硬输出格式”

没有格式，主对话就很难汇总；一旦输出结构固定，主对话就能做到：

并行启动多个 Agent
把结果汇总成统一报告
快速定位“必须修”的条目

③ 用工具权限做“最小能力原则”

审查类：尽量只读（Read/Grep）
写代码类：再开放 Write/Edit
跑命令类：再开放 Bash（并配合 Hooks 做危险命令拦截）

④ 让主对话负责编排，子代理负责产出

推荐的协作方式：

主对话拆解任务与验收标准
子代理按角色产出（测试/审查/文档）
主对话统一验收与合并决策

这样做的好处是：责任边界清晰，质量更稳定。

4.2.4.2 Subagents、Hooks、Skills 组合工作

Subagents 解决的是“角色复用与并行”，Hooks 解决的是“自动触发与门禁”，Skills 解决的是“步骤模板”。

一个团队常见的组合拳是：

Subagent：test-writer 负责补齐测试
Hook：PostToolUse 自动格式化/跑测试（不阻断）
Hook：Stop 做最终质量门禁（测试是否通过、lint 是否干净、git status 是否干净）
Subagent：code-reviewer 只读审查给出必须修清单

4.2.4.3 案例模板

4.2.4.3.1 security-auditor（只读安全审计）

---
name: security-auditor
description: 安全审计与合规检查（只读）
tools: Read, Grep
permissionMode: deny-all
---

# Security Auditor

目标：找出高风险漏洞与可利用路径，并给出可执行修复建议。

输出格式（必须遵守）：
1) Critical（必须立刻修）
2) High（优先修）
3) Medium（建议修）
每条包含：文件路径 + 风险说明 + 复现/攻击思路 + 修复建议

4.2.4.3.2 test-writer（写测试 + 跑测试）

---
name: test-writer
description: 为变更补齐单测/集成测试，并尽量跑一遍验证
tools: Read, Write, Edit, Grep, Bash
permissionMode: inherit
---

# Test Writer

规则：
- 只改测试相关文件，避免改业务逻辑（除非确实需要测试注入点）
- 测试命名清晰，覆盖主路径 + 关键异常路径

输出格式：
- 新增/修改了哪些测试文件
- 运行了哪些测试命令（若无法运行，说明原因与替代建议）

4.2.4.3.3 code-reviewer（代码审查官）

---
name: code-reviewer
description: 严格代码审查（只读），给出可执行的 review checklist
tools: Read, Grep
permissionMode: deny-all
---

# Code Reviewer

重点检查：
- 逻辑正确性（边界/异常/并发）
- 可维护性（命名/结构/重复）
- 性能（热路径/无谓 IO/复杂度）
- 安全（注入/鉴权/敏感信息）

输出格式：
1) 必须修复（带原因与建议）
2) 建议优化
3) 可选风格

4.2.4.3.4 refactor-engineer（重构工程师）

---
name: refactor-engineer
description: 面向可维护性的重构（小步、可验证）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---

# Refactor Engineer

原则：
- 每次重构只解决一个主题（例如“拆分函数”“去重复”“收敛边界”）
- 先加测试/保持行为等价，再动结构

输出格式：
- 重构目标与范围
- 关键改动点（按文件列出）
- 风险点与回滚策略

4.2.4.3.5 doc-writer（文档工程师）

---
name: doc-writer
description: 为功能/模块补齐开发者文档（README/ADR/使用示例）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---

# Doc Writer

要求：
- 用最短路径让新同学跑起来：安装 → 配置 → 运行 → 常见错误
- 每个关键命令给出示例

输出格式：
- 新增/修改了哪些文档文件
- 文档中新增了哪些“可复制命令”

4.2.5 小结

本章小结：Subagents 让复杂任务具备“角色分工、上下文隔离、权限可控”的工程属性。

主对话负责拆解与编排，子代理负责专职输出
用权限边界降低误操作风险，用隔离降低上下文污染
把测试/安全/评审/文档等角色沉淀为可复用配置

下一章将进入 Skills：把流程与输出标准写成 SOP，保证交付稳定一致。

4.3 Skills：可复用的标准操作流程

在这里插入图片描述
本章讲 Skills：把一类任务的标准步骤、检查清单与输出格式写成 SOP，让 Claude Code “每次都按同一套标准交付”。

我们会覆盖 Skill 的结构、触发方式、如何与 Subagents/Hooks 组合，以及如何把团队规范（风险/回滚/测试证据等）固化为可复用资产。

目标是把“会用 AI”升级为“可复制的工程流程”。

4.3.1 Skills 是什么？

Skills 是一个独立的任务模板，核心由三部分组成：

触发语义：description 描述 “什么时候用我”
执行流程：正文写 “怎么做（步骤/清单/约束）”
能力边界：allowed-tools 约束 “能用哪些工具”

它可以：

手动调用（最可控）
自动触发（依赖 description 匹配）
被 Subagent 引用（把 SOP 固化到某个岗位上）

4.3.2 如何理解 Skills、Subagents、Hooks

把这三个概念分清楚，你就知道 “该用 Skill 还是该用 Subagent”：

能力	它更像	解决的问题	适合什么场景
Skills	SOP/作业指导书	让输出结构稳定、流程可复制	审查清单、迁移模板、文档生成、PR 总结
Subagents	岗位/专职工种	让角色边界清晰、上下文更干净	测试工程师、安全审计、文档工程师、重构工程师
Hooks	事件触发器/门禁	让流程自动发生、能阻断风险	代码格式化、危险命令拦截、Stop 质量门禁

总结：Skill 定“怎么做”，Subagent 定“谁来做”，Hook 定“什么时候做/能不能继续”。

如果结合5w1h图，可能就更容易理解了，Skills → HOW | Subagent → WHO | Hooks → WHEN。
在这里插入图片描述

4.3.3 Skills 配置

Skill 的基本结构是：一个文件夹 + SKILL.md。

用户级（跨项目复用）配置示例：

~/.claude/skills/
└── code-reviewer/
    └── SKILL.md

适合：你个人通用的 SOP（安全审查、变更总结、周报整理）。

项目级（推荐团队共享）配置示例：

{project}/.claude/skills/
├── api-doc-generator/
│   └── SKILL.md
└── db-migration-helper/
    └── SKILL.md

适合：强依赖项目结构与技术栈的 SOP（路由风格、目录规范、测试命令、迁移框架）。

团队最佳实践：项目级 Skills 提交到 Git；个人覆盖放 settings.local.json 或用户级 skills。

4.3.3.1 SKILL.md 结构

Skill 定义文件是 SKILL.md（Markdown + YAML frontmatter），示例：

---
name: Code Review Assistant
description: Perform comprehensive code reviews focusing on security, performance, and best practices
user-invocable: true
context: fork
model: opus
allowed-tools:
  - Read
  - Grep
  - Bash
---

# Code Review Instructions

你是一位资深工程师，目标是产出可执行的 Review 报告。

## Checklist
- Security
- Performance
- Best Practices

## Output Contract
1) Summary
2) Must Fix
3) Suggestions
4) Test Evidence

理解重点：

YAML 区决定“运行方式”（能否在菜单出现、是否隔离上下文、用哪个模型、允许哪些工具）
正文决定“产出质量”（流程/清单/约束/输出契约）

4.3.3.2 关键字段解析

4.3.3.2.1 name、description

name：展示名（给人看）

description：触发语义（给 Claude 判断“何时用”），建议写法：

写清楚 “Use when … / 当用户要 … 时使用”
把关键词写进去（review/security/changelog/migration/docs/test）
不要写成一句很空的口号（例如 “helps with coding”）

4.3.3.2.2 user-invocable

作用：是否显示在 /skills 列表

默认：true
建议：
- 团队对外入口：true
- 内部中间件 Skill（只给 Subagent 引用）：可以设为 false，减少干扰

4.3.3.2.3 context: fork

作用：让 Skill 在“隔离的 fork 上下文”运行（减少污染主对话）

建议：

审查/总结/报告类默认 fork
需要连续交互、多轮拿上下文才能完成的任务，谨慎使用（否则主对话看不到细节，只拿到结果）

4.3.3.2.4 model

作用：指定 Skill 的模型（建议用你配置过的别名）

团队建议：

高频 SOP（文档/总结）用更快模型
高风险（安全审计/迁移门禁）用更强模型或主对话复核

4.3.3.2.5 allowed-tools

作用：白名单：Skill 只能使用这些工具

最小权限原则：

只读审查：Read, Grep
文档生成：Read, Grep, Write
迁移生成：Read, Write（Bash 能不开就不开；确实需要再加）

4.3.4 Skills 用法

4.3.4.1 Skills 命令调用

可以通过如下命令手动调用 Skills：

/skills

从列表里选择某个 Skill 执行即可（最可控、最可复现）。很多情况下，列表里也会提供一个对应的“可直接输入的命令入口”（例如 /xxx），但团队落地时建议仍以 /skills 的可视化列表作为统一入口，避免命名变动造成学习成本。

当然，当输入的需求与某个 Skills 的 description 足够匹配，Claude 也会尝试自动触发它。

4.3.4.2 Subagent 引用 Skills

在 Subagent 的 YAML 里绑定 skills，例如：

---
name: api-tester
description: API 测试专家
skills: api-testing, change-summary
---

这类输出会更稳定，也更像团队工作流。

4.3.4.3 Skills 定义规范

① 推荐命名规范（减少调用成本）：

Skill 目录名：kebab-case，语义明确（change-summary/、api-doc-generator/）
name：给人看的标题（可以更友好）
description：像搜索关键词一样写（可触发、可理解）

② 把“输出契约”写死（让结果可验收）：

Summary（3~5 行）
Deliverables（产物清单：文件/命令/链接）
Risks（风险与回滚）
Test Evidence（测试证据）
Next Actions（下一步）

③ 把 Skill 当作“流程资产”版本化：

提交 Git（像提交脚本一样）
PR 审核 Skill 变更（因为它影响“团队的默认产出方式”）
和 Hooks/Subagents 一起形成 .claude/ 目录的“开箱即用工程规范”

④ 工具边界：建议先收紧 allowed-tools，不够用再放开

⑤ Skill 编写 Checklist：

description` 可触发：明确 Use when / 当用户要…时使用（别写空话）
输出契约固定：Summary/Deliverables/Risks/Test Evidence/Next Actions
步骤可执行：每一步都能落到“读哪些文件/产出什么内容”
工具最小化：只给完成任务所需的最小 allowed-tools
能兜底：写清“信息不足时要反问什么/要我提供什么”

4.3.4.3 案例模板

4.3.4.3.1 change-summary（PR 描述/发布说明生成器）

---
name: Change Summary Generator
description: Generate PR description / release notes / changelog from code changes. Use when user asks for summary, changelog, release notes, or PR description.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
---

# Change Summary

目标：把变更整理成“可直接粘贴到 PR/发布说明”的结构化内容。

输出契约（必须遵守）：
1) Summary（3~5 行）
2) User Impact（谁会受影响）
3) Risk & Rollback（风险与回滚策略）
4) Test Evidence（跑了什么/没跑为什么）
5) Notes（兼容性/配置变更/迁移说明）

4.3.4.3.2 api-doc-generator（API 文档生成器）

---
name: API Documentation Generator
description: Generate API documentation from routes/types/comments. Use when user asks to create API docs or document endpoints.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
  - Write
---

# API Documentation

对每个 endpoint 输出（必须完整）：
- Method / Path / Description
- Auth（是否需要登录/权限）
- Request（Headers/Params/Body Schema）
- Response（Success Schema + Error Codes）
- curl Example（可复制）

额外要求：
- 如果找不到路由定义，说明你查了哪些文件/模式（便于我补上下文）

4.3.4.3.3 db-migration-helper（数据库迁移助手：必须可回滚）

---
name: Database Migration Helper
description: Help create safe and reversible database migrations with explicit up/down. Use when user needs to modify database schema.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Write
  - Bash
---

# Database Migration Helper

原则：
1) 必须可回滚（必须有 Down）
2) 高风险操作必须显式标注（drop/rename/backfill）
3) 考虑性能与锁表风险（索引/大表 DDL）

输出契约：
1) Migration Plan（步骤 + 风险点）
2) Up Migration（完整内容）
3) Down Migration（完整内容）
4) Rollout Notes（上线建议：分批/灰度/监控项）
5) Rollback Steps（回滚命令/验证点）

4.3.4.3.4 code-review-assistant（结构化代码审查：可执行清单）

---
name: Code Review Assistant
description: Perform comprehensive code reviews focusing on security, correctness, performance, and maintainability. Use when user asks to review code or audit changes.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
---

# Code Review Assistant

审查范围：
- Correctness（边界/异常/并发）
- Security（鉴权/注入/敏感信息）
- Performance（热路径/IO/复杂度）
- Maintainability（命名/结构/重复/可测试性）

输出契约（必须遵守）：
1) Summary（一段话）
2) Must Fix（每条：文件 + 问题 + 影响 + 修复建议）
3) Should Fix（同上）
4) Nice to Have（可选）
5) Test Suggestions（建议补哪些测试）

4.3.4.4 与 Hooks/Subagents 组合：把流程做成“装配线”

如果只做 Skills，会得到“更稳定的模板”；但如果把 Skills、Subagents、Hooks 组合起来，就能得到“自动化流水线”，一个最容易落地的团队组合拳：

Subagent：test-writer（岗位）绑定 Test Generator 类 Skill（SOP）
Hook：PostToolUse(Write|Edit) 自动格式化 + 最小测试（不阻断）
Hook：Stop 做最终门禁（测试/lint/git status）
Skill：change-summary 在最后生成 PR 描述（结构化输出）

这样基本能做到：每次交付都带 测试证据、风险与回滚、可直接粘贴的 PR 总结。

4.3.5 小结

本章小结：Skills 解决的是“稳定交付”，把团队规范固化为可复用的 SOP。

Skill 定义标准步骤、检查清单与输出结构
Subagents 做分工，Hooks 做门禁，Skills 做流程模板
组合起来可以让交付可复用、可验收、可追溯

下一章将进入 MCP：把能力扩展到外部系统，但仍保持可控与可审计。

第五部分：生态扩展（MCP / Output Styles / Plugins）

5.1 MCP：连接外部真实系统

在这里插入图片描述
本章讲 MCP（Model Context Protocol）：让 Claude Code 从“改本地仓库”扩展到“安全连接外部真实系统”。我们会说明 MCP 的核心概念（Resources/Tools/Prompts）、典型接入形态（HTTP/stdio）、以及落地时必须重视的权限、鉴权、审计与风险隔离。建议按“先只读、后写入、全程可追溯”的策略逐步放开能力。

5.1.1 MCP 是什么？

5.1.1.1 概念

MCP（Model Context Protocol） 是一个标准化协议，用于让 Claude 连接外部服务。你可以把它理解成：

外部服务提供一个 MCP Server
MCP Server 暴露 Tools / Resources / Prompts
Claude Code 通过 MCP 把这些能力当成“可调用工具”使用

在 Claude Code 里，MCP 主要用于扩展两类能力：

读：把外部数据源作为上下文（比如查数据库、读 PR、读告警）
写：对外部系统执行动作（比如创建 Issue、发消息、更新工单）

5.1.1.2 Tools / Resources / Prompts

MCP 的核心概念通常按这三类理解：

概念	可以理解为	示例
Tools	可调用的 “动作”	`github.create_issue`、`db.query`、`sentry.list_errors`
Resources	可读取的 “数据源”	PR 列表、某条告警详情、某张表的数据
Prompts	预定义的 “提示模板”	固定的“事故复盘模板”“发布检查模板”

注意：MCP 并不是“自动帮你做事”，而是提供一个规范接口，让 Claude 能安全、可控地访问外部能力。

5.1.1.3 传输方式

Claude Code 里常见的 MCP 传输方式主要有两种：

5.1.1.3.1 HTTP（推荐）

适合：GitHub、Sentry、Slack、内部平台（有服务端、可复用）
优点：部署在统一环境、便于权限与审计、多人共享
典型配置字段：transport: "http" + url

5.1.1.3.2 stdio（本地进程）

适合：本地快速试验、数据库连接、本地脚本封装成 MCP
优点：启动简单、无需单独部署服务
风险：凭证/环境变量/本地网络访问更分散；团队复用成本更高
典型配置字段：transport: "stdio" + command + args + env

选型建议（团队落地版）：

团队要长期用、要审计、要统一权限：优先 HTTP
个人本地工具、短期实验：用 stdio

5.1.2 MCP 配置

Claude Code 常见的 MCP 配置入口有种。

① 全局配置（用户级）：

位置：~/.claude.json
字段：mcpServers
适合：你个人跨项目复用的 MCP（比如 GitHub、个人数据库等）

示例（节选）：

{
  "mcpServers": {
    "user": {
      "github": {
        "transport": "http",
        "url": "https://github-mcp.example.com"
      },
      "database": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"]
      }
    },
    "local": {}
  }
}

② 项目配置（项目级）：

位置：{project}/.mcp.json
字段：mcpServers
适合：团队共享、与项目强绑定的 MCP（内部 API、项目专用服务）

示例（节选）：

{
  "mcpServers": {
    "github": {
      "transport": "http",
      "url": "https://github-mcp.example.com"
    }
  }
}

团队最佳实践：项目级 .mcp.json 可提交 Git；个人密钥用环境变量，不要写死在配置里。

5.1.3 MCP 用法

5.1.3.1 安装/添加 MCP Server

# HTTP 服务器
claude mcp add --transport http github https://api.github.com/mcp

# stdio 服务器（本地进程）
claude mcp add --transport stdio weather -- npx @modelcontextprotocol/server-weather

带环境变量示例（stdio）：

claude mcp add --transport stdio database \
  --env DB_HOST=localhost \
  --env DB_PORT=5432 \
  --env DB_USER=admin \
  -- node ./mcp-servers/database.js

项目级安装示例：

claude mcp add --scope project slack-bot https://slack.company.com/mcp

5.1.3.2 管理命令

claude mcp list
claude mcp get weather
claude mcp remove weather

你可以在会话里查看 MCP 状态、并对需要认证的服务器完成 OAuth 流程（如果该 server 配置了 OAuth），命令如下：

/mcp

5.1.3.3 案例模板

推荐的项目目录布局（MCP + Claude 配置）：

your-project/
├── .claude/
│   ├── settings.json
│   ├── settings.local.json        # 个人环境变量（不提交）
│   ├── agents/
│   ├── skills/
│   ├── hooks/
│   └── commands/
├── .mcp.json                      # MCP 服务器配置（可提交）
└── CLAUDE.md

{project}/.mcp.json：

{
  "mcpServers": {
    "github": {
      "transport": "http",
      "url": "https://github-mcp.example.com",
      "auth": {
        "type": "oauth2",
        "clientId": "${GITHUB_CLIENT_ID}",
        "clientSecret": "${GITHUB_CLIENT_SECRET}"
      }
    },
    "database": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "transport": "http",
      "url": "https://sentry-mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer ${SENTRY_TOKEN}"
      }
    }
  }
}

建议：

.mcp.json 里只写“连接方式”，凭证一律从环境变量注入
如果你用 settings.local.json 管理环境变量，别把它提交到 Git

5.1.3.4 Hooks / Subagents / Skills 使用 MCP

MCP 单独用当然可以，如果结合Claude，可以实现“系统化编排”，下面讲解几个场景。

5.1.3.4.1 MCP + Subagent

这种方式可以理解为：专职工种操作外部系统

例子：你可以定义一个只负责“处理告警”的子代理（只开放必要工具 + MCP）。

子代理负责：查 Sentry、定位错误、创建 Issue、回填链接
主对话负责：确认策略、决定是否上线修复、做最终把关

5.1.3.4.2 MCP + Skills

这种方式可以理解为：把外部操作变成 SOP

例子：做一个 incident-triage Skill（事故分诊 SOP）：

输出契约固定为：

Incident Summary（现象与影响面）
Evidence（Sentry 错误、关键日志、相关 PR）
Hypothesis（最可能原因）
Actions（创建 Issue/PR/通知）
Rollback & Mitigation（缓解与回滚）

有了 MCP 之后，Skill 不再只是“写文字”，而是能拉取证据、完成动作。

5.1.3.4.3 MCP + Hook

这种方式可以理解为：把通知与门禁接到团队系统

可以用 Notification Hook 做系统通知：

让 Hook 把关键事件转发到 Slack（通过 Slack MCP server）
在 Stop 门禁失败时自动发一条“测试没过/风险提示”到团队

注意：Hook 执行外部动作一定要谨慎，建议默认 blocking=false，并加入明确的白名单/开关。

5.1.3.5 安全性问题

MCP 的能力越强，越要把 “安全边界” 先立起来，建议如下：

① 凭证管理：只用环境变量，不写死：

.mcp.json / ~/.claude.json 里不要直接写 Token，推荐：

OAuth：走 /mcp 完成授权
Header/Token：用 ${ENV:...} 或 ${VAR} 形式引用（具体以你们配置规范为准）

② 最小权限原则：能只读就只读

只做查询：尽量只开放读取型工具
必须写入：让操作变成显式动作（最好让主对话确认）

③ 建议的权限落地顺序（先收住“写操作”）

如果第一次接 MCP，建议按“风险从低到高”开放：

只读型 MCP：读 PR、读告警、读数据库查询（先跑通证据链）
低风险写入：发通知、写评论（可逆、影响小）
高风险写入：合并 PR、改配置、删资源（必须人工确认 + 审计）

同时建议配合第四篇的 Hooks：

PreToolUse(Bash) 拦截危险命令
Stop 门禁失败时给出明确反馈（必要时通知团队）

④ 企业策略（Managed Settings）

企业场景里，常见做法是把 MCP server 的范围/白名单锁到托管配置里，例如：

只允许连接批准的 MCP 域名
强制开启审计日志
锁定 mcpServers 不允许用户修改

5.1.3.6 主流 MCP 资源导航

如果想找“主流 MCP Server/SDK/生态工具”，建议优先从官方入口开始（最权威、更新也最快）：

MCP 官方站点（协议与生态入口）：https://modelcontextprotocol.io
MCP 开源组织（代码与生态聚合）：https://github.com/modelcontextprotocol
官方/社区 MCP Servers 汇总仓库（按需挑选接入）：https://github.com/modelcontextprotocol/servers
Claude Code 的 MCP 文档（Claude 侧接入方式）：https://code.claude.com/docs/en/mcp

建议：不同 MCP Server 的鉴权、能力范围、写操作风险差异很大，团队落地时建议先接只读能力，再逐步放开写入，并配合审计与门禁。

5.1.4 小结

本章小结：MCP 的价值是“把外部系统能力安全引入 Claude Code”。

以协议为边界，把数据读取与动作执行标准化
以权限/鉴权/审计为前提，控制写操作风险
建议按“先只读、后写入”的节奏渐进落地

下一章将进入 Output Styles：用系统级规则让交互与输出长期一致。

5.2 Output Styles：系统提示词与风格

参考官方文档： https://code.claude.com/docs/en/output-styles

在这里插入图片描述

本章聚焦 Output Styles：它不是“回答更好看”的皮肤，而是把 system prompt 以可维护的方式固化下来。我们会讲清 Output Style 能改变什么（角色、默认行为、输出契约）、不能改变什么（工具权限与执行边界），以及如何把它和 CLAUDE.md / Skills / Subagents 组合成稳定的工作方式。目标是让同类任务的输出结构长期一致、可验收、可复用。

5.2.1 Output Styles 是什么？

5.2.1.1 概念

在这里插入图片描述

一句话总结：Output Styles 通过“修改 Claude Code 的 system prompt”，把 Claude Code 变成不同类型的 Agent。

官方定义里强调了两点：

Claude Code 的核心能力依然保留，例如：运行本地脚本、读写文件、追踪 TODO。

输出/交互方式会被“风格化”，不局限于软件工程师助手，也就是说不只是仅开发人员可以使用，其它人也能使用。

为了更好理解，可以把 Output Styles 当作：

“长期生效的输出契约”：要求它每次都按某种固定结构输出（标题/表格/清单/风险提示/确认口径）。
“默认工作方式的开关”：比如要不要先问问题、要不要先出计划、要不要教育性讲解、要不要把关键步骤留给你做。
“身份 + SOP 的最小集合”：它不替代 Skills 的完整流程，但能把 “每次都必须遵守的交互规则”固化下来。

5.2.1.2 三种内置风格

Claude Code 自带 3 种风格的 Output Styles：

Default（默认）：偏执行、偏高效、偏落地（默认 system prompt）的工程师风格。
Explanatory（讲解型）：会在干活过程中插入教育性 “Insights”，适合看懂代码库、理解实现选择、快速熟悉模式。
Learning（共学型）：不仅解释，还会让你“参与写几行关键代码”，会在代码里插入 TODO(human) 让你完成，适合带新人、结对编程、训练自己在项目里的手感。

在这里插入图片描述

5.2.1.3 如何理解？

这里举一个例子来加深对 Output Styles 的理解。例如：用同一个请求做 A/B 测试最直观，这个时候会对 Claude 说：

“请帮我把一个 POST /orders 接口补上幂等（Idempotency-Key），并告诉我为什么这样设计。”

如果选择不同的Output Styles，会看到如下的差异：

Default：倾向直接落地改动（要改哪里、怎么做、怎么验证），解释更少。
Explanatory：会在关键选择点插入解释（幂等键存哪里、冲突怎么返回、重试语义）。
Learning：会把关键一两处留 TODO(human)（例如“你来补：幂等键表的唯一索引/冲突处理分支”），并引导完成。

如果你“看不出差异”，通常不是你没理解，而是：你给的任务太小/太确定（比如“把变量名改一下”），任何风格都差不多。用这种更“有选择空间”的任务测试最有效。

5.2.1.4 易混淆点（统一对照）

下表从作用位置、影响范围、适用场景三个核心维度，对 Output Styles、CLAUDE.md、--append-system-prompt、Subagents 与自定义 Slash Commands 进行统一对照：

能力/机制	作用到哪里	影响范围	典型用途
Output Styles	System Prompt（主对话）	主 agent 的整体角色、语气、输出契约	从“工程师助手”切换到产品、运维、写作、法务等身份
CLAUDE.md	User Message（system 之后）	项目级约束与背景信息	项目规范、目录结构、流程约定、注意事项
`--append-system-prompt`	System Prompt	当前会话的行为强化	临时试验、一次性强化、对比测试
Subagents（Agents）	子 agent（被调用）	具体任务的模型、工具、权限边界	任务分工、能力隔离、自动化流程
自定义 Slash Commands	触发指令	单次流程或模板化操作	快捷执行固定步骤或提示词

一句话理解以上易混淆的概念点:

Output Styles 决定“你在和谁对话”

CLAUDE.md 决定“这个项目有哪些约束”

Subagents 决定“任务怎么分工、用什么能力做”

Slash Commands 决定“什么时候快速跑一套流程”

--append-system-prompt 只是临时改一下脑回路

5.2.2 Output Styles 的工作原理

官方文档里有几条结论，我们把它当成“规则”记住：

Output styles 直接修改 system prompt ；
所有 output styles 都会去掉“高效输出”的那部分指令（例如“尽量简洁”）；
自定义 output style 默认也会去掉“编码相关指令”（例如“跑测试验证”），除非设置 keep-coding-instructions: true
风格指令会被追加到 system prompt 末尾，并在对话过程中反复提醒 Claude 遵守

用人话说就是：

如果想要 “简洁 / 固定格式 / 先问再做 / 先列计划 / 必须给检查清单”，都要在 Output Styles 里明确写出来；否则你以为的“默认行为”，可能已经被关掉了。

很多人看完文档还是懵，核心原因是：你以为 Output Style 只改“措辞”，但它可能连“工程化习惯”也一起改掉。

可以这样去理解：

keep-coding-instructions: true：更像“换一种表达/协作方式，但仍按工程师方式做事”
典型表现：会主动建议/运行测试、会按改动范围做验证、会更谨慎处理写入操作。
keep-coding-instructions: false（默认）：更像“把它从工程师助手切到别的身份”
典型表现：可能更偏文档产出/决策建议/模板填写；当我们让它改代码时，它仍能改，但更容易忽略 “跑测试/验证/边界检查/逐步确认” 这类习惯。

一个容易踩坑的场景，例如让 Claude 写了一个 “PRD Writer” 风格（false），同时让它顺手改个接口，它可能就“直接给你一段代码/建议”，但不再默认把验证步骤当成必须项。

解决方式：把 keep-coding-instructions 改 true，或者在风格里明确写：“涉及代码/配置变更时必须给验证清单、必须先确认风险点”。

5.2.3 Output Styles 用法

5.2.3.1 命令行使用

官方提供了两种方式使用Output Styles。

5.2.3.1.1 命令

运行/output-style 打开菜单选择或者直接 /output-style explanatory（举例）：
在这里插入图片描述

另外 /config 菜单里也能进到同一个入口。
在这里插入图片描述

5.2.3.1.2 配置文件

切换会保存到项目级别的 .claude/settings.local.json，也可以在不同层级 settings 文件里手动改 outputStyle 字段（比如想给整个项目默认一个风格）。

示例（节选）：

{
  "outputStyle": "explanatory"
}

5.2.3.2 自定义 Style

自定义 Output Style 本质是一个 Markdown 文件：

frontmatter（可选元数据）
正文（会被追加到 system prompt）

存放位置两种（官方推荐）：

用户级：~/.claude/output-styles
项目级：.claude/output-styles（更适合团队共享，能进 Git）

5.2.3.2.1 官方推荐模板

---
name: My Custom Style
description:
  A brief description of what this style does, to be displayed to the user
keep-coding-instructions: false
---

# Custom Style Instructions

[你的风格指令写在这里]

## Specific Behaviors

[具体行为约束写在这里]

frontmatter 字段要点（官方表格）：

name：显示名（不写就继承文件名）
description：仅用于 /output-style UI 展示
keep-coding-instructions：是否保留“编码相关 system prompt 指令”（默认 false）

5.2.3.2.2 如何写 Style

写 Output Style 时，建议按下面 5 件事组织（缺了就容易“感觉没变化”或“容易跑偏”）：

目标：一句话说明它要把对话变成什么（例如“可发群的纪要”“可执行的事故处置清单”）。
输入澄清规则：先问几个问题？不足时必须先问而不是瞎编？
输出结构（最关键）：固定小节标题/表格字段/清单项（最好“严格包含”，没有就写“暂无”）。
行动边界：什么情况必须先征求确认？什么情况禁止执行？要不要提供回滚/风险？
简洁度/语气：要短句、要表格、要不讲科普、还是要教学式解释？

可以把它理解为：把“你每次都要反复提醒 Claude 的话”，搬进 Output Style 里，让它自动记住。

5.2.3.3 案例模板

下面举例三个Output Style案例，这些案例可以放到 .claude/output-styles/。

5.2.3.3.1 事故分诊风格

建议配合 MCP使用，incident-triage.md 模板如下：

---
name: Incident Triage
description: 用于线上事故分诊与处置建议（先证据后结论）
keep-coding-instructions: true
---

# Custom Style Instructions

你是“线上事故分诊官”。目标：快速收敛问题、降低影响面、推动可执行动作。
默认保持回答简洁，避免长篇科普。

## Specific Behaviors

- 永远先问清楚：时间范围、影响面、是否可回滚、当前缓解措施。
- 永远先给出“你还缺哪些关键证据”，并给出最小可行的获取方式。
- 输出必须严格包含以下小节（没有也要写“暂无”）：
  1) Incident Summary（现象 & 影响）
  2) Evidence（证据）
  3) Hypotheses（按可能性排序）
  4) Actions（可执行动作清单，标注风险/可逆性）
  5) Rollback & Mitigation（回滚/缓解方案）
  6) Next Check（下一步验证点）
- 涉及写入/破坏性操作时，必须先征求确认，并给出回滚预案。

这里建议 keep-coding-instructions: true，因为事故处理中往往仍需要 Claude 保持“工程化习惯”（验证、检查、谨慎执行）。

5.2.3.3.2 PRD 写作风格

prd-writer.md模板如下：

---
name: PRD Writer
description: 用于需求分析与 PRD 产出（结构化、可评审）
keep-coding-instructions: false
---

# Custom Style Instructions

你是资深产品经理 + 技术合作者，负责把需求写成“可评审、可落地”的 PRD。

## Specific Behaviors

- 先问 3~7 个澄清问题（不足就不要直接写 PRD）。
- PRD 必须包含：背景、目标、非目标、用户故事、范围、交互/流程、埋点、验收标准、风险与灰度方案、里程碑。
- 每个验收标准必须可测试、可观察，避免空话。
- 输出尽量短句，表格优先。

5.2.3.3.3 会议纪要风格

meeting-notes.md 模板风格如下：

---
name: Meeting Notes
description: 会议纪要与行动项提炼（可直接发群）
keep-coding-instructions: false
---

# Custom Style Instructions

你是会议记录员。目标：把讨论变成对齐材料与行动项。

## Specific Behaviors

- 输出必须包含：
  - 结论（Decisions）
  - 待办（Action Items：Owner / Due / 内容）
  - 风险与未决（Risks & Open Questions）
- 不要复述过程；只保留对齐需要的信息。
- 行动项不超过 10 条，超过就合并/聚类。

5.2.4 小结

本章小结：Output Styles 是可维护的 system prompt，把“临时提示”变成“长期规则”。

定义角色身份、默认行为与输出契约
与 CLAUDE.md / Skills / Subagents 组合，形成稳定的协作方式
关注边界：它影响行为与表达，但不应突破权限与安全约束

下一章将进入 Plugins：把这些能力打包分发，沉淀为团队级资产。

5.3 Plugins：打包与分发能力

本章讲 Plugins：把你在项目里跑通的 commands / agents / hooks / skills / mcp 等能力，标准化打包与分发。
我们会围绕插件的目录结构、安装与发现、权限与版本化，以及团队协作时如何避免重复/覆盖等常见问题展开。
目标是把个人经验沉淀为团队资产，并做到可升级、可审计。

5.3.1 Plugins 是什么？

一句话总结：Plugin = 一个目录 + 一个清单文件 .claude-plugin/plugin.json + 一堆你要分发的能力（commands / agents / hooks / Skills / MCP / LSP）。

大白话就是：你把 Claude Code 当成一台“可扩展的工作台”，.claude/ 适合你自己在当前项目里折腾，而Plugin 更像一个“可安装的扩展包”，可以跨项目复用，还能发给团队/社区。

5.3.1.1 Plugin 命名空间

Plugin 的 slash command 一律 带命名空间，如果文件叫 commands/hello.md，插件名（plugin.json 里的 name）叫 my-first-plugin，那么最终命令就是：/my-first-plugin:hello

为什么要 namespace命名空间？ 因为装了多个插件后，都叫 /review、/hello 的概率太高了，使用命名空间就能防止冲突。

5.3.1.2 Plugin 什么时候使用？

什么时候用 Plugin，什么时候继续用 .claude/？官方给的对比非常直白：

你现在的需求	更适合
我就自己用、在单个项目里调试、想快	`.claude/`（Standalone）
要给同事用、要跨项目复用、要版本管理	Plugin
我很在意命令短：`/review`、`/hello`	`.claude/`
我能接受命令带前缀：`/team-tools:review`	Plugin

一个很实际的路径是：先在 .claude/ 里把东西跑通 → 再打包成 Plugin 分享，这比一上来就写插件舒服很多。

5.3.1.3 Plugin 包含什么？

插件不是只能装“命令”，它更像一个能力集合，把它理解成“一个团队最佳实践包”，包含如下内容。

5.3.1.3.1 Commands（自定义 slash commands）

详情参考：2. Claude Code 完整指南：终端命令全解析（收藏级）

放在 commands/ 下，每个文件一个命令
写法是 Markdown + frontmatter（--- description: ... ---）
适合：把常用提示词/流程固化成一条命令，比如 /team:review、/team:release-notes

5.3.1.3.2 Hooks（事件触发器）

详情参考：4. Claude Code 完整指南：Hooks（自动化事件触发）

放在 hooks/hooks.json（也可以写到 plugin.json 里）
适合：让 Claude Code 在某些事件后自动跑动作（比如“写文件后自动跑格式化/测试”）

5.3.1.3.3 Agents（子代理 / 子角色）

详情参考：5. Claude Code 完整指南：Subagents（AI 角色工程化）

放在 agents/ 下
适合：把“专精角色”做成可复用资源，比如“安全审计 agent”“SQL 优化 agent”

5.3.1.3.4 Skills（可复用 SOP）

详情参考：6. Claude Code 完整指南：Skills（可复用的标准操作流程）

放在 skills/ 下（每个 Skill 一个目录，里面有 SKILL.md）
适合：把可重复的标准流程沉淀下来，让模型自动触发（例如：事故分诊、PR 检查、日志分析）

5.3.1.3.5 MCP servers（外部系统连接器）

详情参考：7. Claude Code 完整指南：MCP（让 AI 连接外部真实系统）

适合：把“连接 GitHub / Jira / Notion / Figma / 数据库”等能力，打包给团队一键安装

5.3.1.3.6 LSP servers（代码智能）

5.3.1.3.6.1 LSP 是什么？

前面没有提过 LSP 这个概念，我们可以把 LSP（Language Server Protocol）理解成一套“统一接口”，让编辑器 / 工具去问一个 语言服务进程，比如：

“这个符号定义在哪？”
“这个函数有几个引用？”
“我这段代码现在有哪些类型错误/诊断？”

VS Code 之所以能做“跳转定义、找引用、实时报错”，背后就是 LSP 这一套。Claude Code 里的 LSP 插件，本质上是在告诉 Claude Code：

“这门语言用哪个 language server（可执行程序）”
“怎么启动它、怎么跟它通信”

这样 Claude 在 改代码/读代码 的时候，就能拿到语义级信息（比纯文本搜索强很多），例如它能更可靠地定位定义、理解类型、发现编辑后引入的错误。

5.3.1.3.6.2 LSP 安装

LSP的安装步骤一般如下：

先去 /plugin 的 Discover 里找对应语言的 *-lsp 插件（官方 marketplace 里有很多常见语言）
安装后，打开 /plugin 的 Errors 看它要求的 binary 是什么
把这个 binary 装到系统（例如系统包管理器、语言自己的包管理器），保证终端里能直接运行它（也就是在 $PATH 里）

以下是几个典型 binary 名字：

Python：pyright-langserver
TypeScript：typescript-language-server
Rust：rust-analyzer
Go：gopls

5.3.2 Plugin 使用

5.3.2.1 Plugin 命令

在这里插入图片描述

在 Claude Code 里输入 /plugin，会打开插件管理器（一个带 Tab 的界面），常用的几个 Tab：

Discover：逛插件“应用商店”
Installed：你装了哪些、启用/禁用/卸载
Marketplaces：你添加了哪些“商店”
Errors：插件没生效时先看这里

如果没有 /plugin 命令，通常是版本太老，插件功能要求 Claude Code >= 1.0.33（跑一下 claude --version）。

5.3.2.2 Marketplace 是什么？

Marketplace 就是“插件目录/插件清单”。流程两步走：

先添加 marketplace（只是把商店加进来，还没安装任何插件）
再从这个 marketplace 安装某个插件

官方 marketplace（claude-plugins-official）默认可用，安装插件类似这样：

/plugin install plugin-name@claude-plugins-official

5.3.2.3 添加官方 demo marketplace

Anthropic 在 anthropics/claude-code 仓库里维护了一个 demo marketplace（名字叫 claude-code-plugins），你可以手动加一下：

/plugin marketplace add anthropics/claude-code

在这里插入图片描述

然后你就能在 Discover 里看到 demo 插件，点安装即可；也可以用命令行直接装，例如：

/plugin install commit-commands@anthropics-claude-code

5.3.2.4 安装范围

插件安装有 scope（和 Claude Code 其它配置的 scope 是一套体系）：

user：装在 ~/.claude/settings.json，自己所有项目都能用（默认）
project：装在 .claude/settings.json，团队随仓库一起共享
local：装在 .claude/settings.local.json，只在本机生效，且一般会被 gitignore

你可以用 CLI 装，并指定 scope：

# 默认 user
claude plugin install formatter@my-marketplace

# 团队共享（project）
claude plugin install formatter@my-marketplace --scope project

# 仅本机（local）
claude plugin install formatter@my-marketplace --scope local

5.3.3 自定义 Plugin

5.3.3.1 目录结构

首先需要知道插件目录的结构，.claude-plugin/ 里只能放 plugin.json，其它目录都在插件根目录，标准结构如下：

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json
└── commands/
    └── hello.md

5.3.3.2 编写 Plugin

了解清楚后，可以写plugin.json，例如：my-first-plugin/.claude-plugin/plugin.json （官方 quickstart）：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

其中 name 很关键：它既是插件 ID，也是 slash command 的命名空间前缀。

接着写一个命令，my-first-plugin/commands/hello.md 示例（官方 quickstart）：

---
description: Greet the user with a friendly message
---

# Hello Command

Greet the user warmly and ask how you can help them today.

开发/调试时，不需要把插件丢进 marketplace，可以直接用 --plugin-dir 加载本地目录：

claude --plugin-dir ./my-first-plugin

然后在会话里运行：

/my-first-plugin:hello

也可以同时加载多个本地插件（多写几次 --plugin-dir）。如果插件不加载、命令不出现，先做两件事：

打开 /plugin → 看 Errors tab
跑校验：claude plugin validate 或 /plugin validate

5.3.3.3 打包

如果你已经在 .claude/ 里有一套东西，迁移的目标其实很简单：搬家 + 加一个清单文件，迁移后最明显的变化（官方对照表）：

Standalone（`.claude/`）	Plugin
只能在一个项目里用	可以通过 marketplace 共享
`.claude/commands/`	`plugin-name/commands/`
hooks 在 `settings.json`	hooks 在 `hooks/hooks.json`
分享靠手动复制	用 `/plugin install` 安装

注意：如果 “原来的 .claude/ 文件还在”，又“插件也加载了”，可能会出现重复/覆盖，官方建议是迁移稳定后，把原来的 .claude/ 相关文件删掉，避免重复。

5.3.4 小结

本章小结：Plugins 用“标准化封装 + 可安装分发”把能力从项目配置升级为可复用资产。

将 commands/agents/hooks/skills/mcp 等统一打包、版本化与共享
通过安装与升级机制降低团队复制成本
落地时注意避免与原 .claude/ 配置重复或互相覆盖

下一章会用 5W1H 做全景总结，帮助你按场景选工具、按边界做治理。

第六部分：全景总结（5W1H 与官方导航）

最后一章用 5W1H（What / Why / Who / When / Where / How）把 Claude Code 的核心能力串成一套可落地的心智模型。你可以把它当作“全系列索引”：知道在不同场景下该用哪种机制（CLI、Hooks、Subagents、Skills、MCP、Plugins、Output Styles），以及它们如何组合成完整工程闭环。

6.1 【WHAT】：Claude Code 是什么？

Claude Code 不是“聊天机器人”，更像一个 能在你电脑和代码仓库里做事的工程师，它的核心能力可以拆成 4 层：

一、核心执行层（能读、能改、能跑）

读仓库：读文件、搜代码、理解目录结构与依赖。
改仓库：跨文件写/改代码与配置（不是只给建议）。
跑命令：跑测试/构建/脚本，拿到报错再继续修。

这三件事决定了它能做“真实交付”，而不是“纸上谈兵”。

二、会话与上下文层（让它“持续把一件事做完”）

在 Claude Code 的一段持续对话可以理解为一个会话（Session）。
会话会累积上下文（Context）：包括文件内容、你输入的信息、以及必要的运行结果。
上下文太多会变贵、变慢、变容易跑偏，所以会话管理（恢复/回滚/压缩）很重要。

三、工程化编排层（把能力变成“流程”）

这一层是 Claude Code 和普通“代码补全/聊天 AI”最大的差异：

Hooks：把关键动作自动化，甚至做“门禁”（能阻断危险/低质量操作）。
Subagents：把工作拆给不同“岗位”，减少上下文污染与角色混乱。
Skills：把 SOP 固化成模板，让输出结构稳定、验收可重复。

四、扩展与分发层（连接外部系统 + 让团队复用）

MCP：连接外部真实系统（GitHub、数据库、监控、知识库……）。
Plugins：把 commands/hooks/agents/skills/mcp/lsp 打包分发给团队/多个项目。

6.2 【WHY】：为什么要用 Claude Code

一、它解决的不是“会不会写代码”，而是“交付效率”

现实里最耗时的往往不是写某一行代码，而是：

找到需要修改的真正位置（跨文件定位）
改完之后跑测试、修报错、再跑、再修（闭环）
做 Review、补文档、写变更说明、做风险/回滚说明（交付材料）

Claude Code 的优势是：它能在同一个工作台里把闭环跑完 。

二、它能把“经验”变成默认流程（这是团队价值）

个人用 Claude Code 的收益是 “快”；团队用的收益是 “稳”：

Hooks 把“必须做的检查”固化（格式化/测试/危险拦截）。
Skills 把“必须交付的结构”固化（风险/验证/回滚/证据）。
Subagents 把“必须分工的角色”固化（测试官/审计官/文档工程师）。

三、为什么要理解数据流动与安全边界

因为它会读文件、会写文件、会跑命令，还会在本地落盘记录，在真实团队环境里，需要考虑：

它会在本地留下些什么？会不会暴露项目路径/历史操作？
哪些文件默认可读？敏感信息如何阻止被读入上下文？
哪些操作必须先确认（写文件/跑命令/外部系统写入）？

6.3 【WHO】：谁适合用、怎么分工

一、谁适合用？

个人开发者：写代码 + 跑测试 + 快速复盘（效率提升明显）。
团队技术负责人/Tech Lead：把流程固化，减少交付不一致。
测试/运维/安全：通过角色化（Subagents）与模板化（Skills）参与研发闭环。
非纯研发角色：通过 Output Styles 把主对话变成“产品/写作/排障”等身份。

二、团队里怎么分工（Subagents 的视角）

你可以把主对话当成“编排者/Tech Lead”，把子代理当成“岗位工种”：

security-auditor（安全审计官）：只读（Read/Grep），输出风险清单与修复建议。
test-writer（测试工程师）：Write + Bash，补测试并给出跑测证据。
code-reviewer（代码审查官）：只读为主，输出结构化 Review（必须修/建议/风险/验证点）。
doc-writer（文档工程师）：只写文档目录，产出说明与教程。

这种分工的好处是：

避免“同一会话什么都干”导致的上下文污染
避免“自己写自己审”的自我通过
让每个岗位的工具权限更可控（审计类通常不应有 Write/Bash）

三、Skills 在分工里扮演什么角色

如果 Subagent 解决“谁来做”，Skill 解决“怎么做”：
把团队 SOP（发布检查、迁移可回滚、PR 必须有证据）固化成 Skill，挂在对应 Subagent 上，就能让交付稳定。

6.4 【WHEN】：什么时候用哪些能力？

把能力按“时间点”组织，读者会更容易形成直觉：什么时候该用 Hook，什么时候该用 Skill，什么时候该用 Subagent。

一、会话开始（SessionStart）：先把“环境与规则”亮出来

适合做：

环境体检（Node/Python 版本、依赖是否安装）
打印项目约束/团队规范提示
确认权限策略是否符合预期

二、做任何危险事之前（PreToolUse）：门禁点

适合做：

拦截危险 Bash（rm -rf、git push --force 等）
敏感信息检测（避免把密钥读进上下文/写进仓库）
参数校验与审计记录

三、写/改文件之后（PostToolUse）：自动化点

适合做：

自动格式化（失败不阻断但要提示）
自动跑最小测试（尽量给证据）
自动生成变更摘要（方便写 PR）

四、准备停止之前（Stop/SubagentStop）：收尾验收点

适合做：

“停下前质量门禁”：有没有跑测试？有没有未解决报错？有没有未提交改动？
对子任务做验收：例如子代理说“测试写完了”，那就要求给测试命令与结果

一句话总结 WHEN： Hooks 管“什么时候发生”，Skills 管“怎么做才算完成”，Subagents 管“谁来负责”。

6.5 【WHERE】：它在本地/项目里“放在哪、存在哪、接在哪”

这一部分解决“它到底在哪些地方动了我的东西”的问题（也是最容易让新人困惑的点）。

一、存在哪：用户级目录 ~/.claude/

你可以把这里理解成“跨项目的个人工作台数据”，常见包含：

项目会话记录（按项目分目录）
全局命令索引 history.jsonl（可能包含项目路径信息）
todos（任务列表 JSON）
debug/shell-snapshots/ide 等辅助目录

结论：这就是为什么共享账号/共享环境要谨慎。

二、放在哪：项目级目录 {project}/.claude/

这是团队最该沉淀规范的地方（因为它能跟仓库一起走）：

settings.json：团队共享配置（建议提交 Git）
settings.local.json：个人覆盖（不要提交）
CLAUDE.md：项目背景/规范/常用命令（强烈建议有）
commands/：自定义斜杠命令（把流程做成入口）
.mcp.json：项目 MCP 配置（团队共享外部连接器）

三、接在哪：入口与集成（Where you use）

Claude Code 的使用入口并不只有 CLI：

IDE（VS Code / JetBrains）
桌面版/Web
CI/CD（GitHub Actions/GitLab CI）
IM（Slack 等）

但无论入口是什么，底层都绕不开：权限、配置、上下文、工具调用。

6.6 【HOW】：怎么从 0 到工程化落地

这一章按“循序渐进”的方式给出落地路线：先能用，再好用，再团队化，再平台化。

Step1：先把“边界”画出来（权限最小化）

读仓库默认允许（否则它没法理解）
敏感文件明确 deny（.env、secrets/、证书、私钥等）
写文件/跑命令默认 ask（尤其是前期）

Step2：让它“看懂你的项目”（CLAUDE.md）

目标：减少你重复解释、减少上下文浪费、减少误改，建议写进 CLAUDE.md 的最小集合：

项目是什么（业务一句话）
目录结构（核心模块在哪）
如何运行/测试/构建（命令）
代码规范与约束（比如必须跑哪些测试、提交规范）

Step3：把日常需求变成可控闭环（CLI + 会话管理）

目标：把“说一句话”变成“交付闭环”：

让 Claude 做改动（限定范围与目标）
让 Claude 跑测试/构建拿证据
根据报错继续修
导出摘要/变更说明（用于 PR）

关键习惯：

会话变长要压缩（避免越聊越飘）
走错路要回滚（不要硬聊到崩）

Step4：把“必须做的事”自动化（Hooks）

目标：把返工成本最高的环节系统化：

PreToolUse：危险拦截（阻断）
PostToolUse：自动格式化 + 最小测试（不阻断但要提示）
Stop：停下前质量门禁（强提醒或阻断）

Step5：把“角色”工程化（Subagents）

目标：让一个 Claude 像一个团队一样工作：

业务实现（主对话编排）
测试由 test-writer 负责（给证据）
安全由 security-auditor 负责（只读）
文档由 doc-writer 负责（写文档目录）

Step6：把“流程”标准化（Skills）

目标：让输出稳定、可验收、可复制，推荐你优先沉淀的 4 类 Skill：

PR/变更总结（风险/验证/回滚/影响面）
结构化 Code Review（必须修/建议/风险/验证点）
数据库迁移（强制可回滚）
文档生成（API/运行手册/排障手册）

Step7：连接外部系统（MCP）

目标：从“改本地仓库”扩展到“操作真实系统”：

查外部数据作为上下文（Resources）
执行动作（Tools）
固化模板（Prompts）

建议：优先 HTTP 形态（便于统一权限与审计）。

Step8：把能力变成团队资产（Plugins）

目标：跨项目复用、版本化管理、统一升级，把你在 .claude/ 里跑通的这些东西打包

commands + hooks + agents + skills + mcp + lsp

6.7 官方文档导航

前面九章的内容基本把 Claude Code 核心的内容覆盖了，可能会有缺漏的知识点，这里整理官方的文档，按以下三层来整理：

怎么用起来：安装/快速上手/各种入口（IDE/桌面/Web/CI/IM）
怎么工程化：CLI 参考、常用工作流、Hooks/Subagents/Skills、Output styles
怎么在团队与企业里安全运行：安全/数据使用/合规、网络与 IAM、成本与监控、插件生态与外部系统（MCP）

入门与安装：

Overview：https://code.claude.com/docs/en/overview
Quickstart：https://code.claude.com/docs/en/quickstart
Setup：https://code.claude.com/docs/en/setup
Changelog（版本更新）：https://code.claude.com/docs/en/changelog

使用入口（IDE/桌面/Web）：

VS Code：https://code.claude.com/docs/en/vs-code
JetBrains：https://code.claude.com/docs/en/jetbrains
Desktop：https://code.claude.com/docs/en/desktop
Claude Code on the Web：https://code.claude.com/docs/en/claude-code-on-the-web
Chrome extension：https://code.claude.com/docs/en/chrome

CLI 与日常工作流（查命令/查用法/查最佳实践）：

CLI reference（命令全集）：https://code.claude.com/docs/en/cli-reference
Common workflows（常用工作流）：https://code.claude.com/docs/en/common-workflows
Slash commands（自定义斜杠命令）：https://code.claude.com/docs/en/slash-commands
Output styles：https://code.claude.com/docs/en/output-styles
Statusline：https://code.claude.com/docs/en/statusline
Terminal config：https://code.claude.com/docs/en/terminal-config
Model config：https://code.claude.com/docs/en/model-config
Memory：https://code.claude.com/docs/en/memory

自动化（Hooks）：

Hooks：https://code.claude.com/docs/en/hooks
Hooks guide：https://code.claude.com/docs/en/hooks-guide

角色与 SOP（Subagents / Skills）：

Sub-agents：https://code.claude.com/docs/en/sub-agents
Skills：https://code.claude.com/docs/en/skills
Agent SDK / Subagents：https://code.claude.com/docs/en/agent-sdk/subagents

连接外部系统（MCP）：

MCP：https://code.claude.com/docs/en/mcp

插件生态（Plugins）：

Plugins（概览）：https://code.claude.com/docs/en/plugins
Discover plugins（发现/安装）：https://code.claude.com/docs/en/discover-plugins
Plugins reference（参考手册）：https://code.claude.com/docs/en/plugins-reference
Plugin marketplaces：https://code.claude.com/docs/en/plugin-marketplaces

集成（CI/IM/第三方）：

GitHub Actions：https://code.claude.com/docs/en/github-actions
GitLab CI/CD：https://code.claude.com/docs/en/gitlab-ci-cd
Slack：https://code.claude.com/docs/en/slack
Third-party integrations：https://code.claude.com/docs/en/third-party-integrations

安全、合规与网络（团队/企业最常查）：

Security：https://code.claude.com/docs/en/security
Data usage：https://code.claude.com/docs/en/data-usage
Legal and compliance：https://code.claude.com/docs/en/legal-and-compliance
Sandboxing：https://code.claude.com/docs/en/sandboxing
Network config：https://code.claude.com/docs/en/network-config
IAM：https://code.claude.com/docs/en/iam
LLM gateway：https://code.claude.com/docs/en/llm-gateway

成本、用量与分析（想控预算/看趋势）：

Costs：https://code.claude.com/docs/en/costs
Monitoring usage：https://code.claude.com/docs/en/monitoring-usage
Analytics：https://code.claude.com/docs/en/analytics

企业/云平台接入（Bedrock / Vertex / Foundry）：

Amazon Bedrock：https://code.claude.com/docs/en/amazon-bedrock
Google Vertex AI：https://code.claude.com/docs/en/google-vertex-ai
Microsoft Foundry：https://code.claude.com/docs/en/microsoft-foundry

运行形态与容器（自动化/远程/容器化）：

Headless：https://code.claude.com/docs/en/headless
Devcontainer：https://code.claude.com/docs/en/devcontainer

排障：

Troubleshooting：https://code.claude.com/docs/en/troubleshooting

6.8 总结

通过 5W1H 的视角，可以把 Claude Code 看成一套“可执行的工程系统”，而不是更强的聊天工具：

What：跨文件理解与修改、运行命令、自动化与集成
How：CLI 做入口，Hooks 做门禁，Subagents/Skills 做分工与 SOP，MCP/Plugins 做扩展与分发，Output Styles 做交互契约
Why：把质量、安全与交付稳定性从“自觉”升级为“流程与机制”

把这套机制按你的团队规范组合起来，Claude 才能长期稳定地参与真实工程闭环。

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

AI产品经理-大模型的智力之源与能力边界

大模型的时代，从来不是 “唯技术论” 的时代，而是技术 + 业务深度融合的时代。想要让大模型真正产生价值，不是盲目追求最新、最强的模型，而是先搞懂它的原理和边界，再结合业务痛点，找到合适的结合点。作为 AI 产品经理，我们的核心竞争力，从来不是单纯的懂 AI 或懂业务，而是把 AI 的能力，精准转化为解决业务问题的方案。搞懂大模型的智力之源与能力边界，只是第一步，而真正的落地，藏在每一次的实操、每

2048 AI社区

AI专著生成工具哪家强？详细测评为你选出最佳写作帮手

2048 AI社区

AI写专著必备！专业工具大揭秘，开启高效专著撰写之旅

2048 AI社区

所有评论(0)

查看更多评论

杨林伟

@qq_20042935

已为社区贡献61条内容

3万字硬核拆解 Claude Code：从入门到工程化落地（建议收藏）

杨林伟

文章目录

第一部分：从 0 到 1（安装与上手）

1.1 什么是 Claude Code？

1.2 账号与环境准备

1.2.1 国内注册

1.2.2 官方直连

1.3 Claude Code 安装指南

1.3.1 系统与环境要求

1.3.2 Mac / Linux / WSL 安装

1.3.3 Windows 安装

1.3.4 NPM 安装

1.3.5 版本更新

1.4 快速入门：CLI 实战

1.4.1 初始化与授权登录

1.4.1.1 创建项目

1.4.1.2 登录与授权流程

1.4.1.3 常见问题与避坑说明

1.4.2 用一句话完成一个真实需求

1.5 Claude Code 的多种使用形态

1.5.1 JetBrains IDEs

1.5.2 VS Code

1.5.3 桌面版

1.5.4 浏览器插件

1.5.5 GitHub Actions

1.5.6 GitLab CI/CD

1.5.7 Slack

1.5.8 Web

1.6 小结

第二部分：日常使用（终端命令与工作流）

2.1 命令汇总

2.1.1 文件和目录管理

2.1.1.1 add-dir 命令

2.1.1.2 init 命令

2.1.1.3 export 命令

2.1.1.4 clear 命令（别名: reset, new）

2.1.1.5 compact 命令

2.1.1.6 resume 命令

2.1.1.7 rewind 命令 (别名: checkpoint)

2.1.2 任务和代理管理

2.1.2.1 agents 命令

2.1.2.2 bashes 命令

2.1.2.3 todos 命令

2.1.3 上下文和资源管理

2.1.3.1 context 命令

2.1.3.2 cost 命令

2.1.3.3 usage 命令

2.1.3.4 memory 命令

2.1.4 配置和个性化

2.1.4.1 config 命令（别名: theme）

2.1.4.2 hooks 命令

2.1.4.3 permissions 命令 （别名: allowed-tools）

2.1.4.4 output-style 命令

2.1.4.5 output-style:new 命令

2.1.4.6 statusline 命令

2.1.4.7 terminal-setup 命令

2.1.4.8 vim 命令

2.1.4.9 model 命令

2.1.4.10 privacy-settings 命令

2.1.5 账户和认证

2.1.5.1 login 命令

2.1.5.2 logout 命令

2.1.5.3 upgrade 命令

2.1.6 GitHub 集成

2.1.6.1 install-github-app 命令

2.1.6.2 pr-comments 命令

2.1.6.3 review 命令

2.1.6.4 security-review 命令

2.1.7 开发工具

2.1.7.1 ide 命令

2.1.7.2 mcp 命令

2.1.8 插件和扩展

2.1.8.1 plugin 命令 (别名: plugins)

2.1.9 诊断和调试

2.1.9.1 doctor 命令

2.1.9.2 status 命令

2.1.9.3 migrate-installer 命令

2.1.10 帮助和文档

2.1.10.1 help 命令

2.1.4.3 permissions 命令（别名: allowed-tools）

2.3.2.1 会话与历史可视化（替代多次 `/resume`）

3.6.2 Q2：我可以完全离线使用 Claude Code 吗？

3.6.3 Q3：共享账号安全吗？

3.6.4 Q4：如何彻底删除我的对话历史？

3.6.5 Q5： `permissions.deny` 真的可靠吗？