官方文档地址：https://code.claude.com/docs
Claude Code 是 Anthropic 推出的 面向真实工程场景的 AI 编程助手。我们不能把 Claude Code 理解为聊天版的 AI， 它其实更接近于 能直接参与项目开发的工程师，它不只是回答“怎么写代码”，而是可以 理解整个代码仓库、跨文件修改代码、运行命令、修复错误，并在真实开发环境中协助完成任务。
在实际使用中，可以把 Claude Code 当成一个工程级助手，例如：
只需要用自然语言描述需求，Claude Code 会结合整个代码仓库给出修改方案，甚至直接提交可用的代码改动。
博主不太建议直接使用国内中间代理的 Claude Code，虽然口头上说是 “直连”，其实本质是走了代理，因此也踏了不少坑，费用是直连的几倍，最终使用了直连的方式。这里不讲述如何使用国内的，网上搜索应该一大堆。
直连的方式很简单，只需要 “魔法”+“注册” + “代充” 即可，相信大家都懂，费用大概一个月100多，目前 Claude Code 的量好像也增大了，相比国内的中间代理，省了不止一倍，而且不存在稳定性的问题。
怎么使用 “魔法”，这里不再阐述了，适合自己就好，现在官网并不支持注册，可以自己去某宝买一个账号，同时让他代充即可。最后登录成功的web页面如下：
在设置页面也能看到用量：
至此，相信读者们都能注册 Claude Code 成功了，那么怎么使用呢？这里讲解其安装方式。
安装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 支持的国家/地区 |
执行如下命令：
# 安装稳定版本（默认）
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.58Mac 也可以使用 Homebrew 的方式安装：
brew install --cask claude-codeWindows 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.58Windows 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注意：需要 Node.js 18+以上的版本
Node.js下载地址：https://nodejs.org/en/download/
下载安装好Node.js 后，执行如下命令即可安装 Claude Code：
npm install -g @anthropic-ai/claude-codeClaude Code 自动保持自身最新状态，如果需要禁用自动更新，在 settings.json 文件（一般在用户目录，例如Mac下在：~/.claude/settings .json）中设置 DISABLE_AUTOUPDATER 环境变量：
export DISABLE_AUTOUPDATER=1也可以手动更新：
claude update前面讲的可能都比较偏概念化，这里实际的来操作演示，效果可能更好。
初次使用，我们可以进入项目的根目录，这里为了方便演示，我新建了一个 html-project 的文件夹，然后执行 claude 命令如下：
mkdir html-project
cd html-project
claude运行后，会提示选择终端风格，选默认即可：
接着会提示登录方式，Claude Code 提供订阅制和 API 两种登录方式。
选择第一种之后，会自动跳转到浏览器授权页面：
点击Authorize授权，授权成功后，页面会提示如下：
切换回终端，提示登录成功了，然后提示是否使用默认的API_KEY，这里选择推荐的No，这个KEY当然可以分享给别人共同使用，但是容易被封，个人使用的话，还是选择推荐的。
后续一直选择使用推荐的即可，登录成功页面如下：
注意，授权登录需要使用魔法，且建议选择“湾湾”及非限制的国家地区，否则容易出现地区限制的问题。
如果页面提示成功了，但是本地403，这个时候，需要注意本地的系统，是否设置了其它的地区，建议还是“湾湾”。
接下来，我们可以开发任务，例如：帮我创建一个静态的页面，打开后，是星空的动态效果。
可以看到，Claude Code 在执行任务的过程中，会提示用户是否要执行该操作，上述有三个选项，我们可以选择1，要经过我们同意后才可以运行，这是整个执行的过程，能看到Claude Code正在的操作，也便于我们去了解它的实现方式。
最后执行成功的结果如下：
打开生成的HTML，可以看到如下效果，效果还是挺不错的。
但是到这里，大家可能会有一个疑问，这些新增和改动的代码看上去太麻烦了，不可能一直使用终端，其实Claude Code支持多种使用形态，这里继续讲解。
详情参考文档：https://code.claude.com/docs/en/jetbrains
Claude Code 插件支持大多数 JetBrains IDEs，包括：
在 IDEA 中安装 Claude Code 非常简单，直接进入 Settings → Plugins，搜索 Claude Code 并安装即可：
安装成功后，右上角会出现 Claude Code 图标，点击即可打开底部终端：
此时可以直接用自然语言下达指令，例如：
去除文字，增加多一个月亮
在修改过程中，可以清楚地看到代码变动的内容，效果类似于 git history / diff：
同时，插件执行的所有日志也会在底部控制台完整展示，一切都在 “掌握中”：
最后看看生成的效果（虽然有点丑😂，主要还是提示词要写好，后面博主会出 Gemini 3 的教程，效果会更好）：
详情参考文档：https://code.claude.com/docs/en/vs-code
Claude Code 同样支持 VS Code，通过官方扩展即可安装使用。
核心能力与 JetBrains 版本一致：
VS Code 版本更适合前端、Node.js 以及轻量级项目开发者，整体体验偏“无感集成”，适合日常高频使用。
详情参考文档：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，灵活在本地与云端之间切换。
详情参考文档：https://code.claude.com/docs/en/chrome
Claude Code 提供 Chrome 浏览器插件（Beta），主要面向 Web 调试与自动化场景。
当前能力：
注意事项：
详情参考文档：https://code.claude.com/docs/en/github-actions
Claude Code 可以通过官方 GitHub Action 深度集成到 CI/CD 流程中。
典型使用方式：
@claude 触发 AI 任务优势：
详情参考文档：https://code.claude.com/docs/en/gitlab-ci-cd
GitLab CI/CD 集成目前处于 Beta 状态，定位与 GitHub Actions 类似。
核心能力：
适合 GitLab 重度用户，但目前功能仍在快速迭代中，建议关注官方更新。
详情参考文档：https://code.claude.com/docs/en/slack
Claude Code 可以直接集成到 Slack，成为“会写代码的同事”。
使用方式：
@Claude 提出需求支持两种模式：
适合团队协作、异步开发和远程办公场景。
详情参考文档：https://code.claude.com/docs/en/claude-code-on-the-web
Claude Code 提供官方 Web 版本，无需本地环境即可使用。
主要特点：
非常适合：
本章完成了从“认识 Claude Code”到“真正跑起来”的闭环：
后续章节会逐步进入命令体系、自动化与工程化能力，把日常开发流程真正串起来。
本章聚焦 Claude Code 的终端命令体系与关键配置。
你会看到命令按“文件/目录、会话、权限与安全、成本与监控”等维度如何分类，以及每类命令在真实工程里的使用场景。
建议边看边在自己的项目里对照尝试，把常用命令沉淀成个人或团队的操作习惯。
claude的终端命令非常的多，可以通过最简单的方式去查看支持哪些命令，终端输入 “/” 会有提示：
博主已经分类好，并逐个进行讲解。
用途：将指定目录添加到当前会话的工作目录列表中，使当前会话可以同时访问和理解多个目录。
使用方法:
/add-dir <目录路径>示例:
/add-dir ./src
/add-dir /Users/username/project/components使用场景:
用途: 在当前项目中初始化一个新的 CLAUDE.md 文件，用于存储代码库文档和上下文信息。
使用方法:
/init说明: 创建项目级别的文档文件，帮助 Claude 更好地理解你的代码库结构和约定。
使用场景:
用途: 将当前对话导出到文件或剪贴板。
使用方法:
/export
/export <文件路径>说明: 可以保存完整的对话历史，便于分享或归档。
使用场景:
用途: 清除对话历史并释放上下文，开始全新的会话。
使用方法:
/clear
/reset
/new注意: 此命令会清除所有对话记录，但不会删除文件系统中的任何文件。
使用场景:
用途: 清除对话历史，但在上下文中保留摘要信息。
使用方法:
/compact
/compact [自定义摘要指令]示例:
/compact
/compact 保留所有关于 API 设计的讨论说明: 当对话过长但希望保留重要信息时使用。
使用场景:
用途: 恢复之前的对话会话。
使用方法:
/resume说明: 允许你继续之前中断的对话。
使用场景:
用途: 将 代码 或对话恢复到之前的某个时间点。
使用方法:
/rewind
/checkpoint说明: 类似于"撤销"功能，可以回退到之前的状态。
使用场景:
用途: 管理代理配置，查看当前运行的后台代理及其状态。
使用方法:
/agents说明: 代理是用于在后台执行复杂、多步骤或耗时任务的专用执行单元。
使用场景:
用途: 列出和管理所有后台运行的 bash 任务。
使用方法:
/bashes说明: 显示所有后台进程的 ID 和状态，可用于监控长时间运行的命令。
使用场景:
用途: 列出当前的待办事项。
使用方法:
/todos说明: 显示 Claude 正在跟踪的所有任务及其状态（待处理、进行中、已完成）。
使用场景:
用途: 以彩色网格形式可视化当前的上下文使用情况。
使用方法:
/context说明: 帮助你了解哪些文件和目录在当前会话中，以及它们占用的上下文空间。
使用场景:
/compact、/clear 等命令前，评估当前上下文占用情况
用途: 显示当前会话的总成本和持续时间。
使用方法:
/cost说明: 查看 API 调用的费用统计和会话时长。
使用场景:
用途: 显示计划使用限制和当前用量。
使用方法:
/usage说明: 查看你的订阅计划的配额使用情况。
使用场景:
用途: 编辑 Claude 的记忆文件。
使用方法:
/memory说明: 管理 Claude 在会话之间记住的持久化信息。
使用场景:
用途: 打开配置面板，修改 Claude Code 设置。
使用方法:
/config
/theme说明: 可以配置主题、编辑器偏好、快捷键等。
使用场景:
用途: 管理工具事件的钩子配置。
使用方法:
/hooks说明: 设置在特定事件（如工具调用、文件编辑）发生时自动执行的命令。
使用场景:
用途: 管理工具的允许和拒绝权限规则。
使用方法:
/permissions
/allowed-tools说明: 控制 Claude 可以使用哪些工具，增强安全性。
使用场景:
用途: 直接设置输出样式或从选择菜单中选择。
使用方法:
/output-style
/output-style <样式名称>说明: 自定义 Claude 的输出格式和显示方式。
使用场景:
用途: 创建自定义输出样式。
使用方法:
/output-style:new说明: 定义你自己的输出格式模板。
使用场景:
用途: 设置 Claude Code 的状态栏 UI。
使用方法:
/statusline说明: 配置底部状态栏显示的信息。
使用场景:
用途: 为换行安装 Shift+Enter 键绑定。
使用方法:
/terminal-setup说明: 配置终端快捷键，使 Shift+Enter 插入换行而不是发送消息。
使用场景:
用途: 在 Vim 和普通编辑模式之间切换。
使用方法:
/vim说明: 为喜欢 Vim 键位的用户提供编辑模式切换。
使用场景:
用途: 设置 Claude Code 使用的 AI 模型。
使用方法:
/model
/model <模型名称>示例:
/model claude-sonnet-4
/model claude-opus-4说明: 切换不同的 Claude 模型版本。
使用场景:
用途: 查看和更新隐私设置。
使用方法:
/privacy-settings说明: 管理数据使用和隐私相关配置。
使用场景:
用途: 使用 Anthropic 账户登录。
使用方法:
/login说明: 连接你的 Anthropic 账户以访问付费功能。
使用场景:
用途: 从 Anthropic 账户登出。
使用方法:
/logout使用场景:
用途: 升级到 Max 计划，获得更高的速率限制和更多 Opus 使用量。
使用方法:
/upgrade说明: 打开订阅升级界面。
使用说明:
/usage、/cost 命令评估当前使用情况
用途: 为仓库设置 Claude GitHub Actions。
使用方法:
/install-github-app说明: 集成 Claude 到 GitHub 工作流中。
使用场景:
用途: 获取 GitHub Pull Request 的评论。
使用方法:
/pr-comments <PR编号>示例:
/pr-comments 123使用场景:
用途: 审查 Pull Request。
使用方法:
/review
/review <PR编号>说明: Claude 会分析 PR 的代码变更并提供反馈。
使用场景:
用途: 对当前分支上的待处理更改进行安全审查。
使用方法:
/security-review说明: 自动检测潜在的安全问题和漏洞。
使用场景:
用途: 管理 IDE 集成并显示状态。
使用方法:
/ide说明: 查看和配置与各种 IDE（如 VS Code）的集成。
使用场景:
用途: 管理 MCP (Model Context Protocol) 服务器。
使用方法:
/mcp说明: 配置和管理外部上下文提供者。
使用场景:
用途: 管理 Claude Code 插件。
使用方法:
/plugin
/plugins说明: 安装、启用或禁用扩展功能。
使用场景:
用途: 诊断并验证 Claude Code 的安装和设置。
使用方法:
/doctor说明: 自动检查常见问题，如配置错误、权限问题等。
使用场景:
用途: 显示 Claude Code 状态，包括版本、模型、账户、API 连接和工具状态。
使用方法:
/status说明: 全面的系统状态检查。
使用场景:
用途: 从全局 npm 安装迁移到本地安装。
使用方法:
/migrate-installer说明: 更新安装方式的迁移工具。
使用场景:
用途: 显示帮助信息和可用命令列表。
使用方法:
/help
用途: 提交关于 Claude Code 的反馈。
使用方法:
/feedback
/bug说明: 报告问题或提供改进建议。
反馈地址: https://github.com/anthropics/claude-code/issues
用途: 查看发布说明。
使用方法:
/release-notes说明: 了解最新版本的新功能和改进。
用途: 退出 REPL（交互式命令行界面）。
使用方法:
/exit
/quit当然大家可以在项目中创建 .claude/commands/ 目录来定义自定义命令：
.claude/
commands/
review-pr.md # 自定义 PR 审查命令
run-tests.md # 自定义测试运行命令
deploy.md # 自定义部署命令请参考: 自定义斜杠命令教程
/login # 登录账户
/add-dir ./src # 添加源代码目录
/init # 初始化 CLAUDE.md
/context # 检查上下文/review 123 # 审查 PR #123
/security-review # 进行安全审查
/pr-comments 123 # 查看评论/status # 检查系统状态
/agents # 查看运行中的代理
/bashes # 查看后台任务
/todos # 查看待办事项
/cost # 查看使用成本/config # 打开配置面板
/output-style # 设置输出样式
/vim # 切换 Vim 模式
/hooks # 配置钩子
/permissions # 管理权限/context # 查看当前上下文
/compact # 压缩对话保留摘要
/rewind # 回退到之前状态
/clear # 完全清除重新开始Claudia 官网地址：https://claudia.so
对于不少开发者来说，纯终端方式虽然强大，但在会话管理、上下文理解、成本监控等方面仍然存在一定心智负担。
尤其是当你：
/compact、/rewind这时，仅靠 CLI 已经不够直观，Claudia 正是为了解决这些问题而生。
Claudia 是一个专为 Claude Code 设计的 本地可视化控制台（UI Dashboard），本质上是：
Claude Code CLI 的图形化外壳 + 会话/上下文可视化工具
它不会替代 Claude Code，而是：
/status、/context、/agents、/cost 中的信息集中展示
一句话总结：
Claude Code 负责“能力”，Claudia 负责“可视化与掌控感”。
结合前面 Claude Code 命令汇总，Claudia 的核心能力可以理解为 “把命令变成面板”。
/resume）在 CLI 中，你需要靠：
/resume
/export
/clear来管理会话，而在 Claudia 中：
点击首页的“CC Project”，就可以看到历史多个历史会话：
适合场景：
CLI 中的 /context 是彩色文本，而 Claudia 会：
这让你可以更直观地判断：
/compact
在终端里，你需要反复输入：
/agents
/bashes
/todos而 Claudia 中：
典型使用场景：
相比 CLI 中的纯文本输出，Claudia 会：
这对以下人群尤其重要：
并不是所有人都 必须 使用 Claudia，它更适合以下场景：
如果项目存在如下情况，强烈推荐使用：
| 场景 | 推荐方式 |
|---|---|
| 快速问答、一次性任务 | 纯 CLI |
| 长对话 / 架构设计 | CLI + Claudia |
| 多 Agent / 后台任务 | Claudia |
| 成本与使用监控 | Claudia |
| 博客、复盘、回顾 | Claudia |
本章把 Claude Code 的 CLI 命令按能力域系统梳理了一遍，核心收获是：
下一章会进一步拆开“命令背后的数据流动”，把本地文件与隐私边界讲清楚。
本章从“一条命令”出发，拆解 Claude Code 在本地到底做了什么。
重点包括：~/.claude 与项目 .claude/ 的目录结构、配置文件的层级与优先级、命令执行的记录与快照，以及与隐私/数据安全相关的边界。
读完你应该能清楚判断：哪些数据保存在本地、哪些可能被发送到模型侧、以及如何用配置把风险控制在可接受范围内。
当你第一次运行 claude 命令时，系统会在你的主目录下创建 ~/.claude 文件夹。让我们先看看这个目录里藏着什么秘密：
目录解析如下：
| 目录 | 备注 |
|---|---|
| debug | 调试日志和错误信息 |
| file-history | 文件修改历史记录 |
| history.jsonl | 全局命令历史（跨项目） |
| ide | IDE 集成相关配置 |
| projects | 项目级别的会话数据 |
| shell-snapshots | Shell 命令执行快照 |
| statsig | 统计和特性开关数据 |
| todos | 任务列表的 JSON 数据 |
每个项目都有一个独立的子目录，命名规则是将项目路径转换为目录名（斜杠替换为连字符）。例如：
~/.claude/projects/
├── -Users-yanglinwei-Desktop-xxx/
│ ├── .timelines/ # 时间线数据
│ ├── cca400a9-c8db-4cb0-943c-314875065f34.jsonl # 对话会话记录
│ └── settings.json # 项目级配置（如果存在）每个 .jsonl 文件记录了完整的对话历史，包括：
这个文件记录你在所有项目中执行过的命令，格式如下：
{
"display": "/privacy-settings ",
"pastedContents": {},
"timestamp": 1767777200862,
"project": "/Users/yanglinwei/Desktop/test-project"
}重要提示：这个文件包含你的项目路径信息，如果共享账号，其他人可以看到你曾经访问过哪些项目目录。
Claude Code 的任务管理功能会在这里存储 JSON 文件，每个文件对应一个任务列表。文件命名格式：
<session-id>-agent-<agent-id>.json
在你的项目根目录下，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/ | 自定义斜杠命令 |
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"
}
}| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| 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
让我们追踪一条简单的命令 claude "帮我创建一个 README.md 文件" 的完整生命周期。
用户输入 → CLI 解析 → 加载配置层次 → 检查权限 → 创建会话 ID本地文件操作：
~/.claude/settings.json 和 .claude/settings.local.json.claude/CLAUDE.md（如果存在）作为上下文~/.claude/projects/<project-hash>/ 创建新的 .jsonl 会话文件~/.claude/history.jsonl 追加命令记录构建 API 请求 → 发送到 Anthropic 服务器 → 流式接收响应上传到服务器的数据：
.claude/CLAUDE.md 的内容（如果存在）不会上传的数据：
Claude 可能会请求使用以下工具（取决于权限配置）：
| 工具名称 | 作用 | 本地操作 | 数据上传 |
|---|---|---|---|
Read |
读取文件 | 读取指定文件内容 | 文件内容发送到服务器 |
Write |
写入文件 | 创建或覆盖文件 | 仅记录操作，不上传文件内容 |
Edit |
编辑文件 | 字符串替换操作 | 仅记录操作 |
Bash |
执行命令 | 运行 Shell 命令 | 命令输出发送到服务器 |
Glob |
搜索文件 | 匹配文件路径 | 文件路径列表发送到服务器 |
Grep |
搜索内容 | 搜索文件内容 | 匹配的行内容发送到服务器 |
关键安全点：
Read 工具才能看到文件内容permissions.deny 阻止访问敏感文件.jsonl 会话文件中接收流式响应 → 显示在终端 → 记录到会话文件 → 更新 token 统计本地文件写入：
~/.claude/projects/<project-hash>/<session-id>.jsonlWrite 或 Edit，修改历史保存到 ~/.claude/file-history/~/.claude/statsig/不会。 Claude CLI / Claude Code 的本地配置、历史记录和项目文件（如 ~/.claude/*）
只存在于当前机器，不会因为共享账号或 API Key 而同步到其他设备。
如果你在机器 A 使用 Claude， 即使他人在机器 B 使用同一账号或 Key， 也无法看到你机器 A 上的任何本地文件或历史记录。
共享账号或 API Key 的风险，不在本地文件，而在你“发送出去的内容”。
| 泄漏场景 | 会泄漏的内容 |
|---|---|
| 共享账号 / API Key | 你发送给 Claude 的 Prompt、代码、业务描述 |
| 使用第三方中转或代理 | 请求中的全部明文内容 |
| API Key 被他人持有 | 他人可完全冒充你调用 Claude |
简单理解：Key = 你的身份，共享 Key 就是共享“你本人”。
以下风险 只影响当前机器，与其他设备无关：
| 数据 | 存储位置 | 风险 |
|---|---|---|
| 对话历史 | ~/.claude/projects/ |
机器被共用或入侵时可被读取 |
| 使用记录 | ~/.claude/history.jsonl |
暴露项目路径与使用习惯 |
| API Key | 本地配置或环境变量 | 被读取后可被完全滥用 |
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./secrets/**)",
"Read(./**/*.key)",
"Read(./**/*.pem)"
]
}
}export ANTHROPIC_API_KEY="sk-ant-xxx"chmod 600 ~/.claude/settings.json
chmod 700 ~/.claude/projects/一句话总结：
本地文件不会跨设备泄漏，真正泄漏的，永远是你“主动发出去的内容”。
───────────────────────────────────────────────────────────────
用户输入命令
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
───────────────────────────────────────────────────────────────A: 不会。Claude 只能访问你明确授权的文件。它需要先调用 Read 工具才能看到文件内容，且每次调用都会受到权限系统的控制。
A: 不可以。Claude Code 的核心推理能力依赖于 Anthropic 的云端 API。但你可以控制哪些数据被发送到服务器。
A: 不推荐。虽然 Anthropic 服务器端的数据是隔离的，但本地的 ~/.claude/ 目录会包含所有用户的项目路径和对话历史。如果多人共用同一台机器和账号，存在隐私泄漏风险。
# 删除所有项目会话
rm -rf ~/.claude/projects/
# 删除全局命令历史
rm ~/.claude/history.jsonl
# 如果要完全重置
rm -rf ~/.claude/permissions.deny 真的可靠吗？根据第三方测试（参考 eesel.ai 博客），deny 规则偶尔会被忽略。最佳实践：
如果你有固定的项目上下文（如编码规范、架构说明），写入 .claude/CLAUDE.md：
# 项目上下文
## 技术栈
- 后端：Python + FastAPI
- 数据库：PostgreSQL
- 测试：pytest
## 编码规范
- 使用 Black 格式化
- 类型提示必填
- 测试覆盖率 > 80%这样 Claude 会自动在每次会话开始时加载这些信息，无需每次对话都重新说明。
在 .claude/settings.json 中配置钩子，在工具执行后自动运行命令：
{
"hooks": {
"after:Write": [
{
"command": "black {file_path}",
"if": "{file_path} matches **/*.py"
}
]
}
}参考文档：Claude Code Hooks
在 .claude/commands/review.md 创建命令：
请对当前项目的代码进行审查，重点关注：
1. 安全漏洞
2. 性能问题
3. 代码风格一致性
输出 Markdown 格式的报告。使用：
claude /review本章围绕本地数据与执行链路，给出一个可操作的结论：
~/.claude/ 与项目 .claude/permissions 与环境变量进行约束
本章介绍 Hooks：把“你记得做”的重复动作，变成“系统自动做”的工程化门禁。
我们会围绕 Hooks 的触发时机、命令型与提示型两类用法，以及常见落地场景（格式化/lint/单测、危险命令拦截、敏感信息校验等）展开。
目标是让 Claude Code 的每次执行都更可控、更可审计、更稳定。
Hooks 是 Claude Code 的事件驱动自动化系统：在特定事件触发时，自动执行一组 Hook。
它主要有两种形态：
Stop / SubagentStop 事件里，让 Claude 再做一次“停下前的质量检查”，根据结果决定继续还是停止。你可以把它理解为：
Claude Code 支持分层配置，Hooks 通常按是否团队共享来决定目录。
项目级（推荐团队共享）:
{project}/.claude/settings.json{project}/.claude/hooks/*.sh，让团队开箱即用项目级本地（仅自己用，不提交）:
{project}/.claude/settings.local.json.gitignore用户级（跨项目生效）：
~/.claude/settings.json小贴士：团队规范建议 “项目级为主、用户级为辅”，项目级让仓库可复制；用户级放个人偏好。
| 事件 | 触发时机 | Hook 类型 | 常见用途 |
|---|---|---|---|
| SessionStart | 会话开始 | 命令型 | 初始化环境、检查依赖、打印提示 |
| SessionEnd | 会话结束 | 命令型 | 清理临时文件、记录统计 |
| UserPromptSubmit | 用户提交输入前 | 命令型 | 输入验证、关键词拦截、注入上下文 |
| PreToolUse | 工具执行前 | 命令型 | 危险命令拦截、参数校验、审计 |
| PostToolUse | 工具执行后 | 命令型 | 自动格式化、自动测试、生成变更摘要 |
| Stop | Claude 决定停止前 | 提示型 | 质量门禁（lint/test/git status） |
| SubagentStop | 子代理停止前 | 提示型 | 子任务验收（比如“测试是否补齐”） |
| Notification | Claude 发送通知时 | 命令型 | 转发通知（系统通知/Slack/飞书等） |
写脚本就能自动化
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "./.claude/hooks/format.sh",
"blocking": false
}
]
}
]
}
}关键点：
matcher：用于筛选工具（通常写正则/或模式串），比如 Write|Edit、Bash。blocking：
true：Hook 失败会阻断当前动作（适合安全校验、门禁）false：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）与环境变量，避免某些环境差异导致取不到值。
常见约定（建议你按这个写，团队最好统一）：
exit 0 # 成功，继续
exit 2 # 阻断错误（blocking=true 时会拦下本次操作）
exit 1 # 非阻断错误（记录/提示，但不中断主流程）让 Claude 在“停下前”做质量门禁
提示型 Hooks 仅用于 Stop / SubagentStop：当 Claude 觉得“差不多可以结束了”，会先跑一次这个提示，让它自检并输出 JSON 决策。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "检查是否满足停止条件。返回 JSON: {\"decision\":\"stop\"|\"continue\",\"feedback\":\"说明\"}"
}
]
}
]
}
}{
"decision": "continue",
"feedback": "请先运行测试并修复 lint。"
}你可以用它来实现 “Claude 自己给自己验收” 的体验，不满足条件就继续把事情做完，满足才停。
下面的模板尽量遵循一个原则：高风险校验 blocking=true，耗时工作 blocking=false。
依赖提示：后面的脚本示例会用到
jq来解析 JSON（macOS 可用brew install jq）。
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
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适用场景：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{
"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 0auto-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
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问题一：Hook 不执行
可以通过如下方式排查：
开调试：
claude --debug="hooks"检查脚本可执行权限：
chmod +x ./.claude/hooks/*.sh脚本自测（用 stdin 模拟 JSON）：
echo '{"sessionId":"test"}' | ./.claude/hooks/session-init.sh问题二：无故被阻断
blocking=true 的 Hook 一定要做到：
exit 2问题 三：变慢很明显
blocking=false 或改成“增量/抽样”本章小结：Hooks 是把质量与安全“流程化”的关键部件。
下一章将进入 Subagents：把角色与职责工程化，提升复杂任务的并行与可验收性。
本章讲 Subagents：把常见“工种”固化成可复用的子代理，让主对话负责编排、子代理负责专业产出。
我们会重点看角色拆分的收益（降低上下文污染、避免自审自过、提升复用性）、Subagent 的配置方式与权限边界，以及在真实任务里的协作模式。
读完你可以按团队需要定义测试/安全/代码评审/文档等专职角色，并稳定复用。
Subagents（子代理）是预配置的 AI 人格，每个 Subagent 都有：
可以把主 Claude 理解成 Tech Lead / Orchestrator：拆任务、分派子代理、汇总结果、把子代理当成 “专职工种”。
Subagents 本质上就是一组 Markdown 文件，按作用域放两种位置：
用户级（跨项目复用）：
~/.claude/agents/项目级（推荐团队共享）：
{project}/.claude/agents/团队最佳实践：把项目级 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.mdSubagent 文件是 “带 YAML Frontmatter 的 Markdown”，结构非常固定，例如：
---
name: test-writer
description: 专门编写单元测试和集成测试的 AI 助手
tools: Read, Write, Bash, Grep
model: sonnet
permissionMode: inherit
skills: api-testing
---
# Test Writer Agent
你是一位测试专家，专注于编写高质量的测试代码。
...可以把它理解为：
下面是最常用也最影响效果的四组字段。
tools 是最直观的安全边界与能力边界：
Read/Grep：读代码、搜代码（适合审查类）Write/Edit：写代码、改代码（适合实现类）Bash：跑命令（适合测试/构建/脚手架类）建议：能不开放就不开放。比如“安全审计”大多数时候只需要 Read, Grep。
常见模式：
inherit：继承主会话的权限策略（最常用、最稳）allow-all / deny-all / ask-all：按字面意思理解建议：团队场景以 inherit 为主；确实需要强约束时再用 deny-all（例如“纯审查只读”）。
如果你的团队对成本/速度/质量有分层策略，可以这样用：
具体模型名建议用你在 settings 里配置的别名（便于后续统一切换）。
Skills 更像“标准作业程序（SOP）模板”，Subagent 更像“岗位说明书”：
把 Skill 挂到 Subagent 上，能让团队把重复流程 “标准化”：例如 api-testing、db-migration、release-checklist。
交互式的用法如下，输入以下命令：
/agents通过这个命令，可以：
当然也可以通过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：一次性小任务（新建文件改两行），直接主对话更快
让子代理“可控、可复用、可验收”
① 子代理的提示不要写成“百科全书”
CLAUDE.md 或 Skill 里。② 给每个 Agent 定一个“硬输出格式”
没有格式，主对话就很难汇总；一旦输出结构固定，主对话就能做到：
③ 用工具权限做“最小能力原则”
④ 让主对话负责编排，子代理负责产出
推荐的协作方式：
这样做的好处是：责任边界清晰，质量更稳定。
Subagents 解决的是“角色复用与并行”，Hooks 解决的是“自动触发与门禁”，Skills 解决的是“步骤模板”。
一个团队常见的组合拳是：
test-writer 负责补齐测试PostToolUse 自动格式化/跑测试（不阻断）Stop 做最终质量门禁（测试是否通过、lint 是否干净、git status 是否干净）code-reviewer 只读审查给出必须修清单---
name: security-auditor
description: 安全审计与合规检查（只读）
tools: Read, Grep
permissionMode: deny-all
---
# Security Auditor
目标：找出高风险漏洞与可利用路径，并给出可执行修复建议。
输出格式（必须遵守）：
1) Critical（必须立刻修）
2) High（优先修）
3) Medium（建议修）
每条包含：文件路径 + 风险说明 + 复现/攻击思路 + 修复建议---
name: test-writer
description: 为变更补齐单测/集成测试，并尽量跑一遍验证
tools: Read, Write, Edit, Grep, Bash
permissionMode: inherit
---
# Test Writer
规则：
- 只改测试相关文件，避免改业务逻辑（除非确实需要测试注入点）
- 测试命名清晰，覆盖主路径 + 关键异常路径
输出格式：
- 新增/修改了哪些测试文件
- 运行了哪些测试命令（若无法运行，说明原因与替代建议）---
name: code-reviewer
description: 严格代码审查（只读），给出可执行的 review checklist
tools: Read, Grep
permissionMode: deny-all
---
# Code Reviewer
重点检查：
- 逻辑正确性（边界/异常/并发）
- 可维护性（命名/结构/重复）
- 性能（热路径/无谓 IO/复杂度）
- 安全（注入/鉴权/敏感信息）
输出格式：
1) 必须修复（带原因与建议）
2) 建议优化
3) 可选风格---
name: refactor-engineer
description: 面向可维护性的重构（小步、可验证）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---
# Refactor Engineer
原则：
- 每次重构只解决一个主题（例如“拆分函数”“去重复”“收敛边界”）
- 先加测试/保持行为等价，再动结构
输出格式：
- 重构目标与范围
- 关键改动点（按文件列出）
- 风险点与回滚策略---
name: doc-writer
description: 为功能/模块补齐开发者文档（README/ADR/使用示例）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---
# Doc Writer
要求：
- 用最短路径让新同学跑起来：安装 → 配置 → 运行 → 常见错误
- 每个关键命令给出示例
输出格式：
- 新增/修改了哪些文档文件
- 文档中新增了哪些“可复制命令”本章小结：Subagents 让复杂任务具备“角色分工、上下文隔离、权限可控”的工程属性。
下一章将进入 Skills：把流程与输出标准写成 SOP，保证交付稳定一致。
本章讲 Skills：把一类任务的标准步骤、检查清单与输出格式写成 SOP，让 Claude Code “每次都按同一套标准交付”。
我们会覆盖 Skill 的结构、触发方式、如何与 Subagents/Hooks 组合，以及如何把团队规范（风险/回滚/测试证据等）固化为可复用资产。
目标是把“会用 AI”升级为“可复制的工程流程”。
Skills 是一个独立的任务模板，核心由三部分组成：
description 描述 “什么时候用我”allowed-tools 约束 “能用哪些工具”它可以：
description 匹配）把这三个概念分清楚，你就知道 “该用 Skill 还是该用 Subagent”：
| 能力 | 它更像 | 解决的问题 | 适合什么场景 |
|---|---|---|---|
| Skills | SOP/作业指导书 | 让输出结构稳定、流程可复制 | 审查清单、迁移模板、文档生成、PR 总结 |
| Subagents | 岗位/专职工种 | 让角色边界清晰、上下文更干净 | 测试工程师、安全审计、文档工程师、重构工程师 |
| Hooks | 事件触发器/门禁 | 让流程自动发生、能阻断风险 | 代码格式化、危险命令拦截、Stop 质量门禁 |
总结：Skill 定“怎么做”，Subagent 定“谁来做”，Hook 定“什么时候做/能不能继续”。
如果结合5w1h图，可能就更容易理解了，Skills → HOW | Subagent → WHO | Hooks → WHEN。
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。
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理解重点：
name：展示名（给人看）
description：触发语义（给 Claude 判断“何时用”），建议写法：
作用：是否显示在 /skills 列表
truetruefalse，减少干扰作用：让 Skill 在“隔离的 fork 上下文”运行（减少污染主对话）
建议：
fork作用：指定 Skill 的模型（建议用你配置过的别名）
团队建议：
作用：白名单：Skill 只能使用这些工具
最小权限原则：
Read, GrepRead, Grep, WriteRead, Write（Bash 能不开就不开；确实需要再加）可以通过如下命令手动调用 Skills：
/skills从列表里选择某个 Skill 执行即可（最可控、最可复现）。 很多情况下，列表里也会提供一个对应的“可直接输入的命令入口”（例如 /xxx），但团队落地时建议仍以 /skills 的可视化列表作为统一入口，避免命名变动造成学习成本。
当然，当输入的需求与某个 Skills 的 description 足够匹配，Claude 也会尝试自动触发它。
在 Subagent 的 YAML 里绑定 skills，例如：
---
name: api-tester
description: API 测试专家
skills: api-testing, change-summary
---这类输出会更稳定，也更像团队工作流。
① 推荐命名规范（减少调用成本）：
kebab-case，语义明确（change-summary/、api-doc-generator/）name：给人看的标题（可以更友好）description：像搜索关键词一样写（可触发、可理解）② 把“输出契约”写死（让结果可验收）：
③ 把 Skill 当作“流程资产”版本化：
.claude/ 目录的“开箱即用工程规范”④ 工具边界：建议先收紧 allowed-tools，不够用再放开
⑤ Skill 编写 Checklist：
allowed-tools---
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（兼容性/配置变更/迁移说明）---
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（可复制）
额外要求：
- 如果找不到路由定义，说明你查了哪些文件/模式（便于我补上下文）---
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（回滚命令/验证点）---
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（建议补哪些测试）如果只做 Skills，会得到“更稳定的模板”；但如果把 Skills、Subagents、Hooks 组合起来，就能得到“自动化流水线”，一个最容易落地的团队组合拳：
test-writer（岗位）绑定 Test Generator 类 Skill（SOP）PostToolUse(Write|Edit) 自动格式化 + 最小测试（不阻断）Stop 做最终门禁（测试/lint/git status）change-summary 在最后生成 PR 描述（结构化输出）这样基本能做到：每次交付都带 测试证据、风险与回滚、可直接粘贴的 PR 总结。
本章小结：Skills 解决的是“稳定交付”，把团队规范固化为可复用的 SOP。
下一章将进入 MCP：把能力扩展到外部系统，但仍保持可控与可审计。
本章讲 MCP（Model Context Protocol）：让 Claude Code 从“改本地仓库”扩展到“安全连接外部真实系统”。我们会说明 MCP 的核心概念（Resources/Tools/Prompts）、典型接入形态（HTTP/stdio）、以及落地时必须重视的权限、鉴权、审计与风险隔离。建议按“先只读、后写入、全程可追溯”的策略逐步放开能力。
MCP（Model Context Protocol） 是一个标准化协议，用于让 Claude 连接外部服务。你可以把它理解成：
在 Claude Code 里，MCP 主要用于扩展两类能力：
MCP 的核心概念通常按这三类理解：
| 概念 | 可以理解为 | 示例 |
|---|---|---|
| Tools | 可调用的 “动作” | github.create_issue、db.query、sentry.list_errors |
| Resources | 可读取的 “数据源” | PR 列表、某条告警详情、某张表的数据 |
| Prompts | 预定义的 “提示模板” | 固定的“事故复盘模板”“发布检查模板” |
注意：MCP 并不是“自动帮你做事”，而是提供一个规范接口，让 Claude 能安全、可控地访问外部能力。
Claude Code 里常见的 MCP 传输方式主要有两种：
transport: "http" + urltransport: "stdio" + command + args + env选型建议（团队落地版）：
Claude Code 常见的 MCP 配置入口有种。
① 全局配置（用户级）：
~/.claude.jsonmcpServers示例（节选）：
{
"mcpServers": {
"user": {
"github": {
"transport": "http",
"url": "https://github-mcp.example.com"
},
"database": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
}
},
"local": {}
}
}② 项目配置（项目级）：
{project}/.mcp.jsonmcpServers示例（节选）：
{
"mcpServers": {
"github": {
"transport": "http",
"url": "https://github-mcp.example.com"
}
}
}团队最佳实践：项目级
.mcp.json可提交 Git；个人密钥用环境变量，不要写死在配置里。
# 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/mcpclaude mcp list
claude mcp get weather
claude mcp remove weather你可以在会话里查看 MCP 状态、并对需要认证的服务器完成 OAuth 流程（如果该 server 配置了 OAuth），命令如下：
/mcp推荐的项目目录布局（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 管理环境变量，别把它提交到 GitMCP 单独用当然可以，如果结合Claude，可以实现“系统化编排”，下面讲解几个场景。
这种方式可以理解为：专职工种操作外部系统
例子：你可以定义一个只负责“处理告警”的子代理（只开放必要工具 + MCP）。
这种方式可以理解为：把外部操作变成 SOP
例子：做一个 incident-triage Skill（事故分诊 SOP）：
输出契约固定为：
有了 MCP 之后，Skill 不再只是“写文字”，而是能拉取证据、完成动作。
这种方式可以理解为：把通知与门禁接到团队系统
可以用 Notification Hook 做系统通知：
Stop 门禁失败时自动发一条“测试没过/风险提示”到团队注意：Hook 执行外部动作一定要谨慎，建议默认
blocking=false，并加入明确的白名单/开关。
MCP 的能力越强，越要把 “安全边界” 先立起来，建议如下：
① 凭证管理：只用环境变量，不写死：
.mcp.json / ~/.claude.json 里不要直接写 Token，推荐：
/mcp 完成授权${ENV:...} 或 ${VAR} 形式引用（具体以你们配置规范为准）② 最小权限原则：能只读就只读
③ 建议的权限落地顺序（先收住“写操作”）
如果第一次接 MCP，建议按“风险从低到高”开放：
同时建议配合第四篇的 Hooks：
PreToolUse(Bash) 拦截危险命令Stop 门禁失败时给出明确反馈（必要时通知团队）④ 企业策略（Managed Settings）
企业场景里，常见做法是把 MCP server 的范围/白名单锁到托管配置里，例如：
mcpServers 不允许用户修改如果想找“主流 MCP Server/SDK/生态工具”，建议优先从官方入口开始（最权威、更新也最快）：
建议：不同 MCP Server 的鉴权、能力范围、写操作风险差异很大，团队落地时建议先接只读能力，再逐步放开写入，并配合审计与门禁。
本章小结：MCP 的价值是“把外部系统能力安全引入 Claude Code”。
下一章将进入 Output Styles：用系统级规则让交互与输出长期一致。
本章聚焦 Output Styles：它不是“回答更好看”的皮肤，而是把 system prompt 以可维护的方式固化下来。我们会讲清 Output Style 能改变什么（角色、默认行为、输出契约）、不能改变什么（工具权限与执行边界），以及如何把它和 CLAUDE.md / Skills / Subagents 组合成稳定的工作方式。目标是让同类任务的输出结构长期一致、可验收、可复用。
一句话总结：Output Styles 通过“修改 Claude Code 的 system prompt”，把 Claude Code 变成不同类型的 Agent。
官方定义里强调了两点：
- Claude Code 的核心能力依然保留，例如：运行本地脚本、读写文件、追踪 TODO。
- 输出/交互方式会被“风格化”，不局限于 软件工程师助手，也就是说不只是仅开发人员可以使用，其它人也能使用。
为了更好理解，可以把 Output Styles 当作：
Claude Code 自带 3 种风格的 Output Styles：
TODO(human) 让你完成，适合带新人、结对编程、训练自己在项目里的手感。
这里举一个例子来加深对 Output Styles 的理解。例如：用同一个请求做 A/B 测试最直观，这个时候会对 Claude 说：
“请帮我把一个
POST /orders接口补上幂等（Idempotency-Key），并告诉我为什么这样设计。”
如果选择不同的Output Styles，会看到如下的差异：
TODO(human)（例如“你来补：幂等键表的唯一索引/冲突处理分支”），并引导完成。如果你“看不出差异”，通常不是你没理解，而是：你给的任务太小/太确定（比如“把变量名改一下”），任何风格都差不多。用这种更“有选择空间”的任务测试最有效。
下表从作用位置、影响范围、适用场景三个核心维度，对 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只是临时改一下脑回路
官方文档里有几条结论，我们把它当成“规则”记住：
keep-coding-instructions: true用人话说就是：
如果想要 “简洁 / 固定格式 / 先问再做 / 先列计划 / 必须给检查清单”，都要在 Output Styles 里明确写出来；否则你以为的“默认行为”，可能已经被关掉了。
很多人看完文档还是懵，核心原因是：你以为 Output Style 只改“措辞”，但它可能连“工程化习惯”也一起改掉。
可以这样去理解：
keep-coding-instructions: true：更像“换一种表达/协作方式，但仍按工程师方式做事”keep-coding-instructions: false（默认）：更像“把它从工程师助手切到别的身份”一个容易踩坑的场景，例如让 Claude 写了一个 “PRD Writer” 风格（false），同时让它顺手改个接口，它可能就“直接给你一段代码/建议”，但不再默认把验证步骤当成必须项。
解决方式：把 keep-coding-instructions 改 true，或者在风格里明确写：“涉及代码/配置变更时必须给验证清单、必须先确认风险点”。
官方提供了两种方式使用Output Styles。
运行/output-style 打开菜单选择或者直接 /output-style explanatory（举例）：
另外 /config 菜单里也能进到同一个入口。
切换会保存到项目级别的 .claude/settings.local.json，也可以在不同层级 settings 文件里手动改 outputStyle 字段（比如想给整个项目默认一个风格）。
示例（节选）：
{
"outputStyle": "explanatory"
}自定义 Output Style 本质是一个 Markdown 文件：
存放位置两种（官方推荐）：
~/.claude/output-styles.claude/output-styles（更适合团队共享，能进 Git）---
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）写 Output Style 时，建议按下面 5 件事组织（缺了就容易“感觉没变化”或“容易跑偏”）：
可以把它理解为：把“你每次都要反复提醒 Claude 的话”，搬进 Output Style 里，让它自动记住。
下面举例三个Output Style案例，这些案例可以放到 .claude/output-styles/。
建议配合 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 保持“工程化习惯”（验证、检查、谨慎执行）。
prd-writer.md模板如下：
---
name: PRD Writer
description: 用于需求分析与 PRD 产出（结构化、可评审）
keep-coding-instructions: false
---
# Custom Style Instructions
你是资深产品经理 + 技术合作者，负责把需求写成“可评审、可落地”的 PRD。
## Specific Behaviors
- 先问 3~7 个澄清问题（不足就不要直接写 PRD）。
- PRD 必须包含：背景、目标、非目标、用户故事、范围、交互/流程、埋点、验收标准、风险与灰度方案、里程碑。
- 每个验收标准必须可测试、可观察，避免空话。
- 输出尽量短句，表格优先。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 条，超过就合并/聚类。本章小结：Output Styles 是可维护的 system prompt，把“临时提示”变成“长期规则”。
下一章将进入 Plugins：把这些能力打包分发，沉淀为团队级资产。
本章讲 Plugins：把你在项目里跑通的 commands / agents / hooks / skills / mcp 等能力，标准化打包与分发。
我们会围绕插件的目录结构、安装与发现、权限与版本化，以及团队协作时如何避免重复/覆盖等常见问题展开。
目标是把个人经验沉淀为团队资产，并做到可升级、可审计。
一句话总结：Plugin = 一个目录 + 一个清单文件 .claude-plugin/plugin.json + 一堆你要分发的能力（commands / agents / hooks / Skills / MCP / LSP）。
大白话就是：你把 Claude Code 当成一台“可扩展的工作台”，.claude/ 适合你自己在当前项目里折腾，而Plugin 更像一个“可安装的扩展包”，可以跨项目复用，还能发给团队/社区。
Plugin 的 slash command 一律 带命名空间，如果文件叫 commands/hello.md，插件名（plugin.json 里的 name）叫 my-first-plugin，那么最终命令就是：/my-first-plugin:hello
为什么要 namespace命名空间？ 因为装了多个插件后，都叫 /review、/hello 的概率太高了，使用命名空间就能防止冲突。
什么时候用 Plugin，什么时候继续用 .claude/？官方给的对比非常直白：
| 你现在的需求 | 更适合 |
|---|---|
| 我就自己用、在单个项目里调试、想快 | .claude/（Standalone） |
| 要给同事用、要跨项目复用、要版本管理 | Plugin |
我很在意命令短：/review、/hello |
.claude/ |
我能接受命令带前缀：/team-tools:review |
Plugin |
一个很实际的路径是：先在 .claude/ 里把东西跑通 → 再打包成 Plugin 分享，这比一上来就写插件舒服很多。
插件不是只能装“命令”，它更像一个能力集合，把它理解成“一个团队最佳实践包”，包含如下内容。
commands/ 下，每个文件一个命令--- description: ... ---）/team:review、/team:release-noteshooks/hooks.json（也可以写到 plugin.json 里）agents/ 下skills/ 下（每个 Skill 一个目录，里面有 SKILL.md）前面没有提过 LSP 这个概念，我们可以把 LSP（Language Server Protocol）理解成一套“统一接口”，让编辑器 / 工具去问一个 语言服务进程，比如：
VS Code 之所以能做“跳转定义、找引用、实时报错”，背后就是 LSP 这一套。Claude Code 里的 LSP 插件，本质上是在告诉 Claude Code：
这样 Claude 在 改代码/读代码 的时候，就能拿到语义级信息（比纯文本搜索强很多），例如它能更可靠地定位定义、理解类型、发现编辑后引入的错误。
LSP的安装步骤一般如下：
/plugin 的 Discover 里找对应语言的 *-lsp 插件（官方 marketplace 里有很多常见语言）/plugin 的 Errors 看它要求的 binary 是什么$PATH 里）以下是几个典型 binary 名字：
pyright-langservertypescript-language-serverrust-analyzergopls
在 Claude Code 里输入 /plugin，会打开插件管理器（一个带 Tab 的界面），常用的几个 Tab：
如果没有 /plugin 命令，通常是版本太老，插件功能要求 Claude Code >= 1.0.33（跑一下 claude --version）。
Marketplace 就是“插件目录/插件清单”。流程两步走：
官方 marketplace（claude-plugins-official）默认可用，安装插件类似这样：
/plugin install plugin-name@claude-plugins-officialAnthropic 在 anthropics/claude-code 仓库里维护了一个 demo marketplace（名字叫 claude-code-plugins），你可以手动加一下：
/plugin marketplace add anthropics/claude-code
然后你就能在 Discover 里看到 demo 插件，点安装即可；也可以用命令行直接装，例如：
/plugin install commit-commands@anthropics-claude-code插件安装有 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首先需要知道插件目录的结构，.claude-plugin/ 里只能放 plugin.json，其它目录都在插件根目录，标准结构如下：
my-first-plugin/
├── .claude-plugin/
│ └── plugin.json
└── commands/
└── hello.md了解清楚后，可以写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 tabclaude plugin validate 或 /plugin validate如果你已经在 .claude/ 里有一套东西，迁移的目标其实很简单：搬家 + 加一个清单文件，迁移后最明显的变化（官方对照表）：
Standalone（.claude/） |
Plugin |
|---|---|
| 只能在一个项目里用 | 可以通过 marketplace 共享 |
.claude/commands/ |
plugin-name/commands/ |
hooks 在 settings.json |
hooks 在 hooks/hooks.json |
| 分享靠手动复制 | 用 /plugin install 安装 |
注意：如果 “原来的 .claude/ 文件还在”，又“插件也加载了”，可能会出现重复/覆盖，官方建议是迁移稳定后，把原来的 .claude/ 相关文件删掉，避免重复。
本章小结：Plugins 用“标准化封装 + 可安装分发”把能力从项目配置升级为可复用资产。
.claude/ 配置重复或互相覆盖下一章会用 5W1H 做全景总结，帮助你按场景选工具、按边界做治理。
最后一章用 5W1H（What / Why / Who / When / Where / How）把 Claude Code 的核心能力串成一套可落地的心智模型。你可以把它当作“全系列索引”：知道在不同场景下该用哪种机制（CLI、Hooks、Subagents、Skills、MCP、Plugins、Output Styles），以及它们如何组合成完整工程闭环。
Claude Code 不是“聊天机器人”，更像一个 能在你电脑和代码仓库里做事的工程师，它的核心能力可以拆成 4 层：
一、核心执行层（能读、能改、能跑）
这三件事决定了它能做“真实交付”，而不是“纸上谈兵”。
二、会话与上下文层（让它“持续把一件事做完”）
三、工程化编排层（把能力变成“流程”）
这一层是 Claude Code 和普通“代码补全/聊天 AI”最大的差异：
四、 扩展与分发层（连接外部系统 + 让团队复用）
一、 它解决的不是“会不会写代码”，而是“交付效率”
现实里最耗时的往往不是写某一行代码，而是：
Claude Code 的优势是：它能在同一个工作台里把闭环跑完 。
二、 它能把“经验”变成默认流程（这是团队价值）
个人用 Claude Code 的收益是 “快”；团队用的收益是 “稳”：
三、为什么要理解数据流动与安全边界
因为它会读文件、会写文件、会跑命令，还会在本地落盘记录，在真实团队环境里，需要考虑：
一、谁适合用？
二、团队里怎么分工（Subagents 的视角）
你可以把主对话当成“编排者/Tech Lead”，把子代理当成“岗位工种”：
这种分工的好处是：
三、Skills 在分工里扮演什么角色
如果 Subagent 解决“谁来做”，Skill 解决“怎么做”：
把团队 SOP（发布检查、迁移可回滚、PR 必须有证据）固化成 Skill，挂在对应 Subagent 上，就能让交付稳定。
把能力按“时间点”组织，读者会更容易形成直觉：什么时候该用 Hook，什么时候该用 Skill，什么时候该用 Subagent。
一、会话开始（SessionStart）：先把“环境与规则”亮出来
适合做：
二、做任何危险事之前（PreToolUse）：门禁点
适合做：
rm -rf、git push --force 等）三、写/改文件之后（PostToolUse）：自动化点
适合做：
四、准备停止之前（Stop/SubagentStop）：收尾验收点
适合做：
一句话总结 WHEN： Hooks 管“什么时候发生”，Skills 管“怎么做才算完成”，Subagents 管“谁来负责”。
这一部分解决“它到底在哪些地方动了我的东西”的问题（也是最容易让新人困惑的点）。
一、存在哪：用户级目录 ~/.claude/
你可以把这里理解成“跨项目的个人工作台数据”，常见包含：
history.jsonl（可能包含项目路径信息）结论：这就是为什么共享账号/共享环境要谨慎。
二、放在哪：项目级目录 {project}/.claude/
这是团队最该沉淀规范的地方（因为它能跟仓库一起走）：
settings.json：团队共享配置（建议提交 Git）settings.local.json：个人覆盖（不要提交）CLAUDE.md：项目背景/规范/常用命令（强烈建议有）commands/：自定义斜杠命令（把流程做成入口）.mcp.json：项目 MCP 配置（团队共享外部连接器）三、接在哪：入口与集成（Where you use）
Claude Code 的使用入口并不只有 CLI：
但无论入口是什么，底层都绕不开：权限、配置、上下文、工具调用。
这一章按“循序渐进”的方式给出落地路线：先能用，再好用，再团队化，再平台化。
Step1：先把“边界”画出来（权限最小化）
.env、secrets/、证书、私钥等）Step2：让它“看懂你的项目”（CLAUDE.md）
目标：减少你重复解释、减少上下文浪费、减少误改，建议写进 CLAUDE.md 的最小集合：
Step3：把日常需求变成可控闭环（CLI + 会话管理）
目标：把“说一句话”变成“交付闭环”：
关键习惯：
Step4：把“必须做的事”自动化（Hooks）
目标：把返工成本最高的环节系统化：
Step5：把“角色”工程化（Subagents）
目标：让一个 Claude 像一个团队一样工作：
Step6：把“流程”标准化（Skills）
目标：让输出稳定、可验收、可复制，推荐你优先沉淀的 4 类 Skill：
Step7：连接外部系统（MCP）
目标：从“改本地仓库”扩展到“操作真实系统”：
建议：优先 HTTP 形态（便于统一权限与审计）。
Step8：把能力变成团队资产（Plugins）
目标：跨项目复用、版本化管理、统一升级，把你在 .claude/ 里跑通的这些东西打包
前面九章的内容基本把 Claude Code 核心的内容覆盖了，可能会有缺漏的知识点，这里整理官方的文档，按以下三层来整理：
入门与安装：
使用入口（IDE/桌面/Web）：
CLI 与日常工作流（查命令/查用法/查最佳实践）：
自动化（Hooks）：
角色与 SOP（Subagents / Skills）：
连接外部系统（MCP）：
插件生态（Plugins）：
集成（CI/IM/第三方）：
安全、合规与网络（团队/企业最常查）：
成本、用量与分析（想控预算/看趋势）：
企业/云平台接入（Bedrock / Vertex / Foundry）：
运行形态与容器（自动化/远程/容器化）：
排障：
通过 5W1H 的视角，可以把 Claude Code 看成一套“可执行的工程系统”，而不是更强的聊天工具：
把这套机制按你的团队规范组合起来，Claude 才能长期稳定地参与真实工程闭环。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。