Vibe Coding 笔记-中篇

第三部分：Claude Code 深度使用与进阶技巧

好，到这里你已经能把 Claude Code 跑起来了。前面两部分你完成了：

• 第零部分：准备好了开发环境（Node.js、Git、VS Code 等）
• 第二部分：了解了AI编程工具生态，安装并配置好了 Claude Code，也理解了不同模型的特点与选型策略

但很多人就停在了这一步——会用，但用得不顺手。用久了你会发现三个问题：

0. 它怎么把文件改坏了？ → 你得学会管住它
1. 用着用着怎么变笨了？ → 你得学会管理上下文
2. 它对每个人都一样，怎么让它懂我？ → 你得学会个性化配置

本部分就是解决这三个问题的。先了解全局框架，再逐个深入。

Claude Code 的能力可以按 7 层扩展（Harness） 来理解。Anthropic 官方在 2026 年 5 月的企业级指南中总结了这个框架：

0. CLAUDE.md — 项目说明书，每次会话自动加载
1. Hooks — 事件触发器，在特定时机自动执行
2. Skills — 专业知识包，AI 按需加载
3. Plugins — 把 Skills + Hooks + MCP 打包分发
4. LSP — 给 AI 装上 IDE 级的代码导航
5. MCP — 连接外部工具和数据源
6. 子 Agent — 独立上下文并行干活

这 7 层从底向上，每一层建立在前一层之上。前 3 层是基础配置，后 4 层是高级扩展。本部分和第四部分会逐个展开。

官方反复强调一个观点：模型能力是地板，配置质量才是天花板。花时间把配置做好，比追最新模型版本更有实际收益。

3.1 模型选择与切换

配置好API后，你可能会问："这么多模型，我该用哪个？"这一节帮你解答。

Claude 模型家族对比：

成本估算参考（2026-05-18 核对）：

在 Claude Code 中切换模型（四种方式）：

Claude Code 提供了四种模型切换方式，按优先级从高到低排列：

方法一：启动时指定（临时使用）

# 使用模型别名（推荐，自动指向最新版本）$ claude --model opus # 最强推理$ claude --model sonnet# 日常编码（默认）$ claude --model haiku # 快速轻量​# 使用具体模型名时，请以当前服务商官方文档为准$ claude --model opus$ claude --model "deepseek-v4-pro[1m]"

方法二：运行中切换（使用斜杠命令）

在 Claude Code 对话中直接输入：

> /model# 打开模型选择器（交互式）> /model sonnet# 直接切换到 Sonnet> /model opus# 直接切换到 Opus

选择后会保存到用户设置，下次启动也会生效。

方法三：环境变量持久设置

# 设置默认使用的模型（支持别名或具体名称）export ANTHROPIC_MODEL="sonnet"

方法四：配置文件持久设置（推荐）

在 settings.json 中设置 model 字段，重启即生效：

// ~/.claude/settings.json（全局生效）{ "model": "sonnet"}

// 项目/.claude/settings.json（仅该项目生效）{ "model": "opus"}

配置文件层级说明：

不同模型的使用建议：

实际对比实验：

用同一个任务测试不同模型的表现，帮你直观感受差异：

测试任务：用 Express.js 创建一个简单的 RESTful API，包含 GET 和 POST 两个端点。

> 请用 Express.js 创建一个简单的待办事项 API，包含：> 1. GET /todos - 获取所有待办事项> 2. POST /todos - 创建新的待办事项> 数据存在内存中即可，不需要数据库。

3.2 核心配置详解

Claude Code 有多层配置体系，从全局到项目级，层层覆盖。

配置层级：

全局配置（影响所有项目）└── ~/.claude/settings.json​项目级配置（只影响当前项目）└── 项目根目录/.claude/settings.json​项目上下文文件（告诉AI项目背景信息）└── 项目根目录/CLAUDE.md ← 最重要！

3.2.1 settings.json 配置文件

Claude Code 的配置文件位于 ~/.claude/settings.json（全局）或项目目录下的 .claude/settings.json（项目级）。

常用配置项：

{ // 允许 Claude Code 执行的操作（不再需要每次确认） "permissions": {"allow": [ "Read",// 读取文件 "Write",// 写入文件 "Bash(npm *)",// 执行 npm 命令 "Bash(git *)",// 执行 git 命令 "Bash(node *)"// 执行 node 命令],"deny": [ "Bash(rm -rf *)" // 禁止执行危险的删除命令]}, // 默认使用的模型 "model": "sonnet", // 自动紧凑阈值（上下文使用超过此比例时自动压缩） "autoCompactThreshold": 80}

3.2.2 CLAUDE.md：你的项目"说明书"

CLAUDE.md 是 Claude Code 中最重要的配置文件之一。它就像你给新来的实习生写的"项目入职手册" —— 告诉AI这个项目的背景、技术栈、编码规范和当前进度。

为什么 CLAUDE.md 如此重要？

没有 CLAUDE.md 时，Claude Code 每次开始工作都要花时间"重新认识"你的项目。有了 CLAUDE.md，它一启动就知道项目的全部背景，效率大幅提升。

CLAUDE.md 模板（可直接复制修改）：

# 项目名称​## 项目概述一句话描述这个项目做什么。​## 技术栈- 前端：Next.js 14 + TypeScript + Tailwind CSS- 后端：Next.js API Routes- 数据库：Prisma + SQLite- 部署：Vercel​## 项目结构•```src/├── app/ # Next.js App Router 页面│├── api/# API 路由│├── layout.tsx # 全局布局│└── page.tsx# 首页├── components/# React 组件│├── ui/# 通用UI组件│└── features/# 业务组件├── lib/ # 工具函数和配置├── prisma/# 数据库 schema 和迁移└── types/# TypeScript 类型定义•```​## 编码规范- 使用函数式组件 + React Hooks- 组件文件使用 PascalCase 命名（如 BookmarkCard.tsx）- 工具函数使用 camelCase 命名- API 路由返回统一格式：{ success: boolean, data?: any, error?: string }- 所有数据库操作通过 Prisma Client 执行​## 当前开发状态- 项目初始化完成- 数据库 Schema 设计完成- 书签 CRUD API 开发中- 前端页面待开发- 搜索功能待开发​## 注意事项- SQLite 数据库文件在 prisma/dev.db，不要提交到 Git- 环境变量在 .env 文件中，不要提交到 Git- 所有新功能先创建 Git 分支再开发

CLAUDE.md 的三个层级（由顶向下叠加生效）：

很多人只知道 CLAUDE.md 可以放在项目根目录，其实官方设计了 3 个层级的 CLAUDE.md，它们会同时生效、不冲突：

三层叠加生效，不冲突。优先级：文件夹级 > 项目级 > 全局级。

两个官方推荐的创建姿势：

• /init 创建项目级：在项目根目录下运行 claude 后输入 /init，cc 会自动扫描项目并生成一份 CLAUDE.md 初稿，你再调整。官方建议：项目有一定规模再 /init 效果更好（太空它扫不出什么东西）。
• /memory 编辑全局级：在 cc 会话里输入 /memory 选择“全局 CLAUDE.md”，会用默认编辑器打开该文件供你修改。修改全局后需重启 cc 才生效。

最佳实践：

0. 保持更新：项目级 CLAUDE.md 应该是动态的——项目加了功能、踩了坑，就同步更新

1. 足够具体：技术栈写明具体版本号，目录结构要与实际一致

2. 写明禁忌：把"不要做什么"也写清楚（如"不要修改数据库迁移文件"）

3. 适度简洁：不要写成论文，AI需要的是关键信息而非赘述

4. 只放"顶层不变原则" ：随着实践你会发现，CLAUDE.md 不该塞太多。卡帕西发布的「claude.skills」几百行通用规则就能拿 10 万+ Star——写点 “顶层、不变、须严守" 的东西就够了。

   https://github.com/multica-ai/andrej-karpathy-skills

3.2.3 第二层记忆：Auto Memory（cc 自己的笔记本）

如果说 CLAUDE.md 是你主动立下的规矩，那 Auto Memory 就是 cc 在干活过程中默默记下的设计笔记。你没显式写进 CLAUDE.md 的习惯、反馈、项目踩坑，会被一个后台 agent 静静记录。

如何启用：

# 在 cc 会话中输入/memory​# 在弹出的菜单里选第一个选项 “启用 Auto Memory”# 启用后菜单里会多出“打开自动记忆文件夹”选项

Auto Memory 会记哪几类东西：

使用手感（重要）：

• 它只在当前项目生效（文件存在项目目录下），换项目需重新积累
• 启用后 cc 不会每次都把所有记忆全部加载进上下文，只会读一份 memory.md 索引——遇到具体问题才去读对应的子文件，占 token 很少
• 随时可以用快捷键 Ctrl+O 在会话中查看实际被调用过的记忆内容
• 记错了就跟它说：“忘掉刚刚说的不喜欢深色主题”，它会自己删掉

3.2.4 第三层记忆：自建参考文档（渐进式披露）

除了上面两层，你还可以仿照 Skill 的"渐进式披露"机制为 cc 手动打造一套专项参考文档。

应用场景：某些东西不适合全部塞进 CLAUDE.md（太长、太专门），但 cc 需要的时候必须能查到。比如做个产品，你希望：

• 品牌视觉规范：颜色、字体、间距 → docs/brand-visual.md
• 产品文本风格：语调、术语表 → docs/copywriting-style.md
• API 约定：请求响应格式、错误码 → docs/api-conventions.md

然后在 CLAUDE.md 里加上指引：

## 外部参考文档​- 修改前端视觉、调颜色、调间距时 → 必读 `docs/brand-visual.md`- 写产品文案、按钮文字、提示语时 → 必读 `docs/copywriting-style.md`- 写 API 、定义返回格式时 → 必读 `docs/api-conventions.md`

这样 cc 只在"需要的时候"才去读完整文档，既保证了准确性，又不占多余上下文。

3.2.5 三层记忆总览

Claude Code 的三层记忆体系：第一层 CLAUDE.md（你主动写，全量加载）→ 第二层 Auto Memory（cc 自己记，按需读取）→ 第三层自建参考文档（你写，cc 遇到对应任务才读）。

3.2.6 .claudeignore 文件

类似于 .gitignore，用来告诉 Claude Code 哪些文件/目录不需要关注：

# .claudeignore 示例node_modules/# 依赖包目录（太大了，AI不需要看）.next/ # Next.js 构建产物dist/ # 编译输出*.log # 日志文件.env # 环境变量（包含敏感信息）

3.3 核心命令与日常使用

掌握 Claude Code 的日常使用，就像学会开车的基本操作 —— 方向盘、油门、刹车、倒车镜。

3.3.1 启动与基本交互

# 最基本的启动方式（在当前目录启动）$ claude​# 指定项目目录启动$ claude --project-dir /path/to/your/project​# 使用指定模型启动$ claude --model sonnet​# 单次执行模式（执行完就退出，适合脚本调用）$ claude -p "请列出当前目录下所有的 JavaScript 文件"

3.3.2 对话交互基础

启动 Claude Code 后，你就进入了一个交互式对话界面。你输入需求，AI分析后执行。

典型的交互流程：

你：帮我创建一个简单的 HTML 页面，显示"Hello AI Coding"​AI：好的，我来创建这个页面。​[AI 分析需求][AI 请求确认：我将创建文件 index.html，是否允许？]​你：是（按 Enter 确认）​AI： 已创建 index.html，包含以下内容：- 基本 HTML5 结构- 一个标题显示"Hello AI Coding"- 简单的居中样式

权限确认机制：

Claude Code 在执行以下操作前会先询问你：

你可以：

• 按 Enter 或输入 y → 确认执行
• 输入 n → 拒绝执行
• 输入补充信息 → 修改AI的计划

3.3.3 核心斜杠命令详解

在 Claude Code 对话中，以 / 开头的命令是“斜杠命令”，用来控制Claude Code 的行为。在输入框里打一个 / 就会弹出完整命令清单；/help 列出所有可用指令。

基础高频命令：

扩展管理命令：

最常用的三个命令详解：

/compact —— 上下文压缩（必须掌握）

这是解决”用久了 AI 变笨”的核心武器。用 cc 一段时间会发现回答变慢、质量下降——这是因为你聊的每句话、它读的每个文件、它执行的每个操作的结果，都在挤占上下文空间。模型上下文虽然有 200K，但实际有效比例只有 60%-80%，且会随上下文增多能力下降。脑子里塞多了东西，它就容易把握不住重点。

/compact 命令会帮你”整理桌面” —— 把前面的对话压缩成摘要，腾出空间。

> /compact​AI: 上下文已压缩。当前对话摘要：- 我们正在开发一个书签管理器项目- 已完成：数据库设计、API端点- 当前正在：前端页面开发

配套命令：/context —— 监控上下文余量

在 /compact 之前，先用 /context 看看当前状况：它会详细展示上下文占比，包括各个 MCP、Skill 各占用了多少 token，让你知道是什么在”吃掉”上下文。

> /context​上下文使用情况：已使用: 142,000 / 200,000 tokens (71%)├── 对话历史: 89,000 tokens├── CLAUDE.md: 2,100 tokens├── Skills: 12,500 tokens└── MCP 工具: 4,800 tokens

/compact vs /clear —— 什么时候用哪个？

/rewind —— “后悔药”（双击 ESC 快捷启动）

当你让 cc 改了一些代码、过后发现不满意（或者项目被改坏了），cc 自带一个回滚机制：在对话里输入 /rewind，或者直接双击 ESC，就会进入回滚界面：

[Rewind] 选择回滚方式：1. 仅回滚对话 → 文件保留，只清除后面几轮对话2. 回滚对话 与 文件编辑 → 推荐！全部返回某个节点3. 仅回滚文件 → 保留对话，只还原文件

/memory —— 记忆管理

Claude Code 有一个跨会话的“长期记忆”系统。它会自动记住你的偏好和项目信息，下次启动时依然记得。/memory 进去后可以编辑全局 / 项目 CLAUDE.md、开启自动记忆。具体记忆体系见 4.2 节 记忆系统。

/review —— 代码审查

完成功能开发后，让 AI 审查你的代码质量：

> /review​AI: 正在审查项目代码...​审查结果： 代码结构清晰注意： api/bookmarks.ts 第15行：缺少输入验证注意： components/BookmarkList.tsx：建议添加 loading 状态 发现潜在安全问题：SQL 查询未使用参数化查询

3.3.4 快捷键速查

3.3.5 输入与交互高级技巧

除了打字对话，cc 还有几种交互方式能大幅提升效率。

1. ! 进入 Bash 模式（不用新开终端跑命令）

在 cc 对话窗口里输入文字默认是在跟 cc 对话，不是跑 shell 命令。要跑命令有两种常见做法：

推荐：在 cc 会话里以 ! 开头，进入 Bash 模式跑命令> !npm run dev> !node app.js​# 取代方案：另外开一个终端跑命令

2. @文件/目录 引用（给 cc 精准上下文）

cc 不会一直把所有项目文件加载到上下文里（项目一大也加不进去），需要时会现场 grep。你明确 @ 一个文件，就是在节省 cc 探路的 token 成本。

# 直接 @ 文件路径（输入时会自动弹出候选）> 参考 @src/auth/login.ts 的风格，在 @src/auth/ 下加个 register.ts​# 提示词太长、命令行里打不下？先写到 .md 文档里，再 @ 它> 按 @docs/feature-spec.md 的需求实现

3. 贴图片（多模态能力）

直接将图片拖拽到对话框、或者 Ctrl+V 粘贴。适合：

• 给设计参考图让 cc 实现一个类似的 UI
• 贴报错截图让 cc 判读
• 贴架架构图让 cc 按图实现

4. 三种启动参数（命令行启动时）

claude# 默认启动claude -c # = --continue，启动时直接接上次会话claude --permission-mode plan# 启动后直接进 Plan Mode（8 节）claude --dangerously-skip-permissions # "危险模式"：一路绿灯不问任何确认

3.4 Claude Code 实战工作流

了解了基本操作后，让我们来看一个完整的开发工作流。这就像学会了方向盘和油门后，实际上路开一圈。

3.4.1 官方推荐工作流：Explore → Plan → Implement → Commit

Claude Code 的常见推荐工作流可以概括为 四阶段：

0. Explore（探索） ：Plan Mode 下读代码、搜引用，搞清楚现状
1. Plan（规划） ：出方案、评估边界情况，你审核
2. Implement（实施） ：切出 Plan Mode，按方案执行
3. Commit（提交） ：生成 commit message，提交

一轮结束后，回到第 1 步开始下个任务。

各阶段详解：

3.4.2 项目设置（6个应该习惯性做的动作）

在开始一个新项目之前，完成以下 6 项设置能让后续开发顺利多倍：

Step 1: 项目初始化↓ 描述项目目标 → AI 生成项目骨架Step 2: 建立 CLAUDE.md（项目上下文）↓ 可运行 `/init` 让 AI 自动生成Step 3: 配置权限与默认模式↓ .claude/settings.json、复杂项目可默认 plan 模式Step 4: 功能开发↓ 一次一个功能，逐个 Explore→Plan→ImplementStep 5: 代码审查与测试↓ 用 /review 让 AI 生成测试并跑起来Step 6: 提交代码↓ git commit 保存进度

3.4.3 完整示例：用 Claude Code 创建一个 Express Hello World API

让我们用一个小例子走完整个流程，让你亲身体验 Claude Code 的威力。

Step 1：初始化项目

# 创建项目目录$ mkdir hello-api$ cd hello-api​# 启动 Claude Code$ claude

在 Claude Code 中输入：

> 请帮我初始化一个 Node.js Express 项目：> 1. 使用 npm init 创建 package.json> 2. 安装 express> 3. 创建一个 app.js 入口文件> 4. 实现一个 GET /hello 端点，返回 { message: "Hello AI Coding!" }> 5. 端口使用 3000

AI 会依次执行以下操作（每一步都会请求你确认）：

[Claude Code] 将运行命令: npm init -y→ 确认？(y/n) y​[Claude Code] 将运行命令: npm install express→ 确认？(y/n) y​[Claude Code] 将创建文件: app.js→ 确认？(y/n) y

预期生成的核心代码（app.js）：

// 引入 Express 框架const express = require('express');​// 创建应用实例const app = express();​// 定义端口号const PORT = 3000;​// 定义 GET /hello 路由app.get('/hello', (req, res) => { // 返回 JSON 格式的响应 res.json({ message: 'Hello AI Coding!' });});​// 启动服务器app.listen(PORT, () => { console.log(`服务器已启动，访问 http://localhost:${PORT}/hello`);});

Step 2：运行并验证

在 Claude Code 中输入：

> 请启动这个服务器，然后用 curl 测试 /hello 端点

AI 执行的操作：

[Claude Code] 将运行命令: node app.js→ 确认？(y/n) y​输出: 服务器已启动，访问 http://localhost:3000/hello

你也可以打开浏览器访问 http://localhost:3000/hello，应该看到：

{ "message": "Hello AI Coding!"}

Step 3：提交代码

> 请帮我初始化 Git 仓库并提交当前代码，commit message 为 "初始化 Express Hello World API"

AI 会执行：

git initgit add .git commit -m "初始化 Express Hello World API"

3.5 Claude Code 最佳实践

经过大量实践总结出的使用技巧，帮你事半功倍。

3.5.1 Prompt 编写技巧（针对 Claude Code 场景）

1. 任务描述要具体，不要模糊

差：帮我做一个登录功能 好：在 /api/auth/ 目录下创建登录 API：- POST /api/auth/login- 接受 { email, password }- 使用 bcrypt 验证密码- 成功返回 JWT token- 使用项目已有的 prisma client 查询 User 表

2. 引用已有代码作为参考

好：参考 /api/bookmarks/route.ts 的风格，为 /api/tags/ 创建类似的 CRUD 接口。数据模型参见 prisma/schema.prisma 中的 Tag 表。

3. 先让AI制定计划，确认后再执行

好：我想给书签管理器添加搜索功能。请先分析一下需要修改哪些文件，列出计划，等我确认后再开始实现。

4. 一次只做一件事

差：帮我同时添加搜索功能、标签管理、用户认证和导出功能 好：帮我先实现书签搜索功能。具体需求：- 在书签列表页面添加搜索框- 支持按标题和描述搜索- 搜索时实时过滤结果（前端过滤即可）

3.5.2 上下文管理策略（快速参考）

上面 /compact 详解已覆盖核心操作，这里给你一个快速决策表：

3.5.3 Git 集成最佳实践

在深入 Git 技巧之前，先给你一个直观理解：Git 就是你的"游戏存档系统" 。哪怕你不是程序员，只要在用 cc 做项目，Git 都是你的生命线。

想象你玩一个 RPG 游戏：打到 BOSS 前存个档 → 打输了就读档重来 → 打赢了就存新档继续。Git 在项目中就是完全一样的东西：打到一个满意的节点存一档，后面翻车就读档回来。

Mac 自带 Git，Windows 让 cc 帮你装。最好建个 GitHub 账号——远程仓库可以让你在其他电脑上拉下存档点继续工作，也方便协作。Git 的下载、安装、登录、提交、回滚，全都可以让 cc 用自然语言帮你完成，比如说：

> 帮我下载 Git 并跟我的 GitHub 账号绑定> 帮我把现在的代码提交到远程仓库> 回滚到上一个存档版本

黄金法则：在让AI做大修改之前，先 commit​开发流程：1. git commit → 保存当前状态（"存档"）2. 让 AI 实现新功能3. 测试功能是否正常├── 正常 → git commit → 继续下一个功能└── 有问题 → git checkout . → 回到步骤1，换个方式重试

# 实际命令示例​# 1. 开始新功能前，先保存$ git add . && git commit -m "开始添加搜索功能前的存档"​# 2. 在 Claude Code 中实现功能...# （如果功能做坏了）​# 3. 回退到存档点$ git checkout .​# （如果功能做好了）# 3. 保存新功能$ git add . && git commit -m "完成搜索功能"

3.5.4 费用控制策略

> /cost​AI: 当前会话费用统计：输入 Token: 15,234输出 Token: 8,721估算费用: $0.18

3.5.5 大型代码库最佳实践（Anthropic 官方推荐）

以上技巧偏通用。如果你接手的是一个多人协作、几十万行以上的大型代码库，Anthropic 官方在大型代码库实践中给出过多条专门建议。核心矛盾是：即使模型上下文已经很长，真实代码库仍然可能远超窗口上限。前 3 条是纪律，后 3 条是武器。

① 用 /init 自动生成 CLAUDE.md（项目初始化）

第一次在一个新项目里跑 Claude Code，第一件事就是 /init：

> /init

AI 会自动浏览项目目录、识别技术栈、读 README 和关键配置文件，生成一份初版 CLAUDE.md。然后你只要在它的基础上手工补充三类信息：

② 任务粒度要小且聚焦（避免“万能 prompt”）

大型代码库里最害人的就是“一句话扔给 AI 整个大需求” 。正确做法：

反例：帮我重构整个支付模块，加入新风控、新对账、新通知、新报表 正解：第一步——在 src/payment/risk/ 下抽出风控规则引擎，接口签名见 docs/risk-rules.md，先不动调用方代码

经验值：每个 Claude Code 任务 ≤ 涉及 5 个文件 / 200 行代码改动。超过这个量级就该拆。

③ 频繁重置上下文（/clear 是好朋友）

很多新手以为对话越长 AI 越懂自己，这恰恰是大型代码库里最大的坑：

• 上下文里塞的越多，无关代码片段越多，AI 越容易抓错重点
• 上一任务的失败尝试、错路径、错假设，会污染下一个任务

官方建议：

④ 复杂任务从 Plan Mode 起手（权限控制）

详见 4.9 节。一句话：陌生代码库或一动牵全身的修改，永远先 /plan 或 Shift+Tab×2，让 AI 在只读模式下先勘探出方案再动手，回退成本几乎为零。

⑤ 用 Skills 与 Subagents 卸载长任务

大型代码库里有些“调研型任务”天生很费 token：

• 找出所有调用了某废弃 API 的地方
• 梳理某个模块的依赖图
• 跨 50 个文件的批量重命名前的影响评估

这类任务不要让主会话亲自做，而是：

• 派 Subagent：让一个独立的子袋里去调研，最后只把结论带回主上下文（Plan Mode 下会自动调用）
• 写成 Skill：把高频调研流程封装成 Skill，每次一键触发（详见第四部分）

这样主会话的上下文窗口尽量留给“看结论、做决策、写代码”这些核心动作。

⑥ 接入 MCP / LSP（给 AI 装上团队协作工具）

一个真正的工程师不是只看代码，还会查 Jira、读 Confluence、连数据库、用 IDE 的“跳到定义”。Claude Code 通过 MCP（Model Context Protocol） 把这些能力接进来：

3.5.6 大型代码库最佳实践速查表

3.5.7 三个容易被忽视的官方进阶建议

这三点在官方博客里被反复强调，但实际使用中最容易被新手跳过。

1. 在子目录初始化 Claude，别从仓库根目录开始

这点在 monorepo 里反直觉但极重要：

反例：在 monorepo 根目录下启动user@monorepo $ claude# AI 看到三百个服务、上千个包，上下文污染严重​ 正解：进入你要改的子目录启动user@monorepo $ cd services/paymentuser@monorepo/services/payment $ claude# Claude 会自动向上遍历加载所有 CLAUDE.md（根目录的也会加）# 但工作范围被精准限定在了相关代码区域

配套做法：每个子目录都放一份小的 CLAUDE.md，写明该目录专用的测试与 lint 命令。不要让 AI 改了一个服务就去跑整个仓的测试套件——那就等着超时吧。

2. 配置要定期审查（每 3-6 个月）

为当前模型写的指令，在下一代模型上可能适得其反。官方举了两个真实例子：

3. 团队内应该有个“人”负责 Claude Code（DRI / Agent Manager）

这点是面向团队使用者的，个人开发者可以跳过。Anthropic 观察到：推广最快的组织，都是“先有一小队人把基础设施搭好”才大面积开放的。

3.5.8 企业级部署三阶段（面向团队负责人）

如果你是要在企业里推广 Claude Code 的人，Anthropic 推荐的路径是：阶段 1 先由小队搭好工具链和规范 → 阶段 2 小范围试点 → 阶段 3 大面积推广。核心原则是”开发者第一次接触就能跑通”，第一印象坏了后面很难翻盘。

3.6 新项目启动套件：5 分钟配好，以后每个项目都不用再教

3.6.1 为什么需要启动套件

每个新项目打开 Claude Code，它都像个刚入职的新人——不知道你的技术栈、不知道哪些文件不能碰、不知道你的规范。你得从零教起：

• 改一个 API，Claude 直接在组件文件里写 SQL——它不知道你的数据库操作全在 src/lib/services/ 里，没人告诉过它
• 每执行一个命令弹一次权限确认，一个下午点了 30 次 Allow
• commit message 格式每次都靠临时编

默认的 Claude Code 是什么都能做、什么都不知道的通用助手。通用不是好事。

这套配置把"通用"变成"你的项目的专属"。核心思路：把一次性的解释成本，变成可复用的配置文件。4 个文件 + 9 个命令，放到任何项目里就能用。

3.6.2 第一个文件：CLAUDE.md

CLAUDE.md 是 Claude Code 启动时第一个读的文件。写在里面的东西，Claude 在每一次对话里自动遵守。全局 CLAUDE.md 的精简模板：

## 沟通方式- 默认中文回复；代码、命令、变量名、文件路径保持英文- 结论先行，简洁直接，不先铺垫背景- 不谄媚，不夸"这是个很好的问题"，不以"当然可以"开头- 给真实判断——方案有问题直接指出，发现更好做法主动说明## Git- 不自动 `git commit` 或 `git push`，除非我明确要求- 提交前先展示将要提交的变更摘要- commit message 使用简洁英文## 红线操作以下操作即使在 auto-accept 模式下也必须先问我：- 删除文件、目录或 git 历史- 修改 `.env`、密钥、token、证书、CI/CD 配置- `git push`、`git rebase`、`git reset --hard`、强制推送- 公开发布（`npm publish`、生产部署等）

项目级的 CLAUDE.md 再加一层：技术栈、目录结构、commit 格式、禁区（如 不要碰 migrations/ 目录）。两个文件叠加，Claude 第一次打开项目就知道——跑测试是 pnpm vitest run 而不是 npm test，数据库操作全在 src/lib/services/ 里。

维护策略：每被 Claude 坑一次，立刻加一条到 CLAUDE.md。过时的规则删掉，内容保持精炼。三个月下来，这个文件就是"这个项目 Claude 犯过的所有错误的预防清单"。最有生产力的一句话是："更新 CLAUDE.md，让这件事不再发生"。

3.6.3 第二个文件：settings.json

用 Claude Code 最烦的就是弹窗。这个文件把"该放行的放行、该锁住的锁住"写死：

{ "permissions": {"allow": [ "Read", "Glob", "Grep", "Edit", "MultiEdit", "Write(src/**)", "Write(tests/**)", "Bash(npm *)", "Bash(pnpm *)", "Bash(git status)", "Bash(git diff *)", "Bash(git log *)", "Bash(git add *)", "Bash(git commit *)", "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(find *)" ],"deny": [ "Read(**/.env*)", "Read(**/*.pem)", "Read(**/*.key)", "Read(**/secrets/**)", "Read(**/credentials/**)", "Write(**/.env*)", "Write(**/secrets/**)", "Write(package-lock.json)", "Write(.github/workflows/*)", "Bash(rm -rf *)", "Bash(sudo *)", "Bash(git push *)", "Bash(git merge *)", "Bash(git rebase *)", "Bash(docker *)", "Bash(curl * | sh)", "Bash(chmod *)" ],"defaultMode": "acceptEdits"}}

allow 白名单：日常安全操作，不应该每次都问——读文件、写源码、跑测试、git 日常命令。

deny 黑名单：安全红线——读 .env、读密钥、rm -rf、sudo、git push。

配完之后：日常操作零弹窗，危险操作自动封堵。

3.6.4 第三个文件：.gitignore

除了常规忽略，多加几行保护 AI 工具配置和密钥不被提交到 git：

# AI 工具本地配置.claude/settings.local.json.cursor/.aider*.continue/.cody/​# 密钥和凭证*.pem*.keycredentials.json.npmrc.aws/.ssh/

3.6.5 第四个：9 个 Slash Command（Skills）

Skills 把你上线前的心理检查清单变成命令——不用再临时想"还有什么没查"，敲个 /，它按你的规矩跑完。每个 Skill 就是一个 Markdown 文件放在 .claude/skills/[名字]/SKILL.md。

9 个 Skill 的完整写法见第五部分。这里快速看三个最核心的：

/review — 审代码。不看风格，按严重程度排：

• CRITICAL：逻辑错误、空指针、竞态条件、安全漏洞
• WARNING：N+1 查询、缺少错误处理、性能隐患
• INFO：命名、垃圾代码、TODO
• 输出 checklist，结尾总结 "X critical, Y warnings, Z info"

/commit — 提交代码。自动跑 git status 和 git diff --stat，把改动按逻辑分组，格式遵循 type(scope): description。

/deploy-check — 上线前检查。按顺序跑：类型检查 → 测试 → lint → 构建 → 搜 console.log → 检查 .env 引用 → 确认没有未提交的改动。全绿才上线。

另外 6 个：/test、/pr、/debug、/refactor、/docs、/security。套路相同——frontmatter 声明 name、description、allowed-tools，后面写检查步骤。

3.6.6 三种安装方式

推荐做法：settings.json 和 skills 放全局，CLAUDE.md 每个项目单独写。权限和命令不用每个项目配一遍，但项目上下文是独立的。

3.6.7 这套配置是活的

模板最大的意义不是"直接用"，是"以此为起点，让它越长越像你的项目"：

• CLAUDE.md 是活的：Claude 每犯一次错就加一条。记住这句话："更新 CLAUDE.md，让这件事不再发生"
• settings.json 跟着项目长大：新工具来了加 allow，发现新的危险操作加 deny
• Skills 长出自己的版本：/review 里加你代码库特有的常见问题，/commit 里写团队的 scope 命名规范
• .gitignore 持续更新：每用一个新工具，看它会不会在本地生成配置文件

三个月后回头看，最初的模板已经被使用习惯磨成了不同的形状。这个变化本身就是价值——你的项目越来越像你，Claude 也越来越懂你。

3.7 Claude Code 常见问题与排查（FAQ）

3.7.1 安装类问题

Q1：安装时报 ENOENT: no such file or directory

• 原因：npm 缓存损坏
• 解决：运行 npm cache clean --force，然后重新安装

Q2：安装成功但 claude 命令找不到

• 原因：npm 全局安装路径未加入系统 PATH
• 解决：运行 npm config get prefix，将输出的路径加入系统 PATH 环境变量

Q3：Windows 上报"无法加载文件，因为在此系统上禁止运行脚本"

• 原因：PowerShell 执行策略限制
• 解决：以管理员身份打开 PowerShell，运行 Set-ExecutionPolicy RemoteSigned

3.7.2 连接/API 类问题

Q4：启动后提示 Invalid API Key

• 原因：API Key 配置错误或过期
• 解决：检查环境变量 ANTHROPIC_API_KEY 是否正确设置。用 echo $ANTHROPIC_API_KEY（macOS）或 echo $env:ANTHROPIC_API_KEY（PowerShell）验证

Q5：中转服务配置后连接超时

• 原因：中转服务地址错误或服务不可用
• 解决：1. 检查 ANTHROPIC_BASE_URL 是否正确 2. 用浏览器访问中转服务网站确认其正常运行 3. 尝试用 curl 直接测试API连通性

Q6：提示 Rate limit exceeded

• 原因：短时间内发送了太多请求
• 解决：等待 1 分钟后重试。如果频繁出现，考虑升级 API 套餐

3.7.3 使用类问题

Q7：AI 修改了不该改的文件

• 原因：需求描述不够明确，AI自行判断需要修改
• 解决：1. 用 git checkout . 撤销修改 2. 重新描述需求，明确指定"只修改 xxx 文件" 3. 在 CLAUDE.md 中注明"不要修改的文件"

Q8：AI 陷入"改A坏B、改B坏A"的循环

• 原因：AI缺乏全局视角，修复一个问题引入新问题
• 解决：1. 用 git checkout . 回退到稳定版本 2. 用 /clear 清空对话 3. 重新描述完整的需求，让 AI 一次性考虑所有约束

Q9：对话太长后 AI 开始"遗忘"早期内容

• 原因：上下文窗口接近满载
• 解决：使用 /compact 压缩上下文，或开新会话

Q10：AI 生成了一个不存在的npm包或API

• 原因：AI "幻觉"（编造不存在的东西）
• 解决：在使用 AI 推荐的包之前，先到 npmjs.com 搜索确认它是否存在

3.7.4 费用类问题

Q11：感觉费用消耗太快

• 原因：可能在使用 Opus 模型或对话过长
• 解决：1. 用 /cost 查看当前费用 2. 切换到更便宜的模型 3. 减少不必要的对话轮次 4. 在 Anthropic Console 设置月度预算限额

Q12：中转服务的费用如何计算

• 说明：中转服务通常按 Token 数量计费，价格 = 官方价格 × 倍率。不同中转服务倍率不同（1.0x-1.5x），请查看你使用的中转服务的价格页面

3.8 自定义斜杠命令（Custom Slash Commands）

你可以创建自己的斜杠命令，将常用操作封装成快捷方式。

在项目根目录创建 .claude/commands/ 目录，然后添加 Markdown 文件：

<!-- .claude/commands/deploy.md --># 部署检查清单​请执行以下部署前检查：1. 运行所有测试：npm test2. 检查是否有 lint 错误：npm run lint3. 确认 .env.example 已更新（如果添加了新的环境变量）4. 构建项目：npm run build5. 报告所有检查结果

使用方式：

> /deploy

Claude Code 就会按照你定义的步骤执行部署检查。

3.9 Claude Code 使用模式：Plan Mode 与三种权限模式

初学者常问：“用 Claude Code 是应该先让它规划整个项目再执行，还是自己分模块逐步让它做？”

答案：Claude Code 原生提供了 Plan Mode（规划模式） 。它不是“一种提示词技巧”，而是官方内置的一个只读运行模式，在该模式下 AI 只能分析不能修改，有专门的快捷键与命令可随时切入。

3.9.1 三种运行模式（官方）

Claude Code 内置 三种互斥的运行模式：

3.9.2 Plan Mode 能做什么、不能做什么

在 Plan Mode 下，AI 只能调用这些只读工具：

严格禁止：写入文件、修改文件、运行 shell 命令、运行测试、任何改动项目的动作。这保证你在看到 AI 计划之前，它不会动你项目中的任何一行代码。

3.9.3 四种进入 Plan Mode 的方式（重点！）

图：进入 Plan Mode 的四种方式，从临时到永久

方式一：键盘快捷键 Shift+Tab（最常用）

在 Claude Code 会话中连按两次 Shift + Tab：

第一次 Shift+Tab → 切到 Auto-Accept Mode（状态栏： accept edits on）第二次 Shift+Tab → 切到 Plan Mode （状态栏： plan mode on）第三次 Shift+Tab → 切回 Normal Mode

方式二：会话中输入 /plan 命令（v2.1.0+）

Claude Code v2.1.0 之后支持直接在提示符中输入斜杠命令：

> /plan

会话会立即切入 Plan Mode。特别适合“继续聊到一半发现需要规划”的场景。

方式三：启动时直接进 Plan Mode

如果你明确知道本次是复杂任务，可以从启动就进入 Plan Mode：

# 交互式claude --permission-mode plan# 无头模式（可用于 CI / 脚本）claude --permission-mode plan -p "分析认证模块并提出优化建议"

方式四：设为项目默认模式

如果某个项目你一直希望默认“先规划后执行”，可以在项目根的 .claude/settings.json 中配置：

{"permissions": { "defaultMode": "plan"}}

以后只要在该项目目录下运行 claude，就会默认进 Plan Mode。

3.9.4 推荐的完整工作流

推荐的使用顺序：

claude --permission-mode plan← 进 Plan Mode↓ Phase 1：Explore—— “读一下 src/auth 目录，了解现有认证逻辑”↓ Phase 2：Plan—— “请出详细计划：需改哪些文件、按什么顺序、边界情况是什么”↓ 你审核计划，反复打磨满意为止Shift+Tab → Auto-Accept Mode← 切出 Plan Mode↓ Phase 3：Implement —— “按上述计划实施”↓ Phase 4：Commit —— “生成提交信息并 commit”

3.9.5 何时用 Plan Mode、何时不用

作者推荐的一句话准则：

3.9.6 另一种变体：Opus Plan + Sonnet Implement

Claude Code 还提供了 --model opusplan 别名，它会：

• 用 Opus（推理能力更强、成本较高）作为规划阶段的模型
• 用 Sonnet（代码快、成本低）作为执行阶段的模型

claude --model opusplan

这是一种 “用贵模型思考、用便宜模型动手”的成本优化策略，适合复杂任务。

3.9.7 快捷决策树

图：决策树——复杂任务走 Plan Mode，简单任务走 Normal Mode

3.10 案例实操：Web 记账工具（finance-cli）—— 热身练习

3.10.1 项目简介

我们要做一个带 Web 界面的记账工具，在浏览器里记录和查看日常开销。核心功能：

• 添加账目：金额、分类、日期、备注——在网页表单里填写
• 查看列表：按月份和分类筛选，表格展示所有记录
• 分类统计：柱状图 + 统计表，一目了然
• 删除记录：输入 ID 即可删除

技术栈：Python + Streamlit（Web 界面框架）+ sqlite3（数据库，Python 自带，零配置）

选择 Streamlit 的原因是它只用 Python 代码就能做出漂亮的 Web 界面，不需要学 HTML/CSS/JavaScript。你写的每一行都是 Python，Streamlit 自动把它变成网页。

项目结构（4 个文件，不到 350 行代码）：

finance-cli/├── pyproject.toml # 项目配置和依赖声明└── finance/ # Python 包├── __init__.py # 空文件，标记为 Python 包├── models.py # 数据结构定义（dataclass）├── database.py # SQLite 建表 + 增删查 + 统计└── web.py # Streamlit Web 界面入口

3.10.2 第 1 步：用 /plan 做架构设计

在终端中创建项目目录，启动 Claude Code：

cd ~/ai-coding-projectsmkdir finance-cli && cd finance-cliclaude

告诉 AI 你的需求（注意：直接输入自然语言即可，不需要特殊格式）：

我要做一个 Python Web 记账工具，功能包括：- 添加账目（金额、分类、日期、备注）——在网页表单里填写- 查看列表（按月份和分类筛选）——表格展示- 删除账目——输入 ID 删除- 分类统计——柱状图 + 统计表​技术栈用 Python + streamlit + sqlite3。预设 6 个分类：餐饮、交通、购物、娱乐、居住、其他。我是编程新手，请先出方案再动手。

Claude Code 会进入 Plan Mode（Shift+Tab 两次或输入 /plan），提出几个问题确认你的需求（比如"你是新手还是老手？"、确认技术选型），然后生成一份包含以下内容的架构方案：

• 数据库表设计（categories 表 + records 表）
• 项目文件结构
• 每个文件的职责说明
• 实现步骤顺序

审核方案确认无误后，告诉 AI "可以开始执行"。

3.10.3 第 2 步：环境准备

在 Claude Code 中输入：

请帮我创建 pyproject.toml，声明项目信息和依赖：- 项目名：finance-cli- Python 版本要求：>=3.10- 依赖：streamlit

AI 会生成 pyproject.toml，内容如下：

[project]name = "finance-cli"version = "0.1.0"description = "个人记账 Web 应用"requires-python = ">=3.10"dependencies = ["streamlit>=1.42",]

然后创建虚拟环境并安装依赖：

# 创建虚拟环境（隔离本项目依赖，不影响系统 Python）python -m venv venv​# 激活虚拟环境# Windows：venvScriptsactivate# macOS / Linux：source venv/bin/activate​# 安装依赖pip install -e .

3.10.4 第 3 步：数据模型（models.py）

在 Claude Code 中继续输入：

请创建 finance/models.py，定义数据模型：1. DEFAULT_CATEGORIES 列表：餐饮、交通、购物、娱乐、居住、其他2. Category 类（用 @dataclass），字段：id、name3. Record 类（用 @dataclass），字段：id、amount、category_id、record_date、note、created_at、category_name（运行时填充，非数据库字段）

AI 生成的 finance/models.py：

from dataclasses import dataclass​# 预设的 6 个默认分类，用户首次使用时自动创建DEFAULT_CATEGORIES = ["餐饮", "交通", "购物", "娱乐", "居住", "其他"]​​@dataclassclass Category:"""分类模型"""id: intname: str​​@dataclassclass Record:"""一笔账目的模型"""id: intamount: floatcategory_id: intrecord_date: str # 格式: YYYY-MM-DDnote: str = ""created_at: str = ""​# 展示时可以带上分类名称（不从数据库来，运行时填充）category_name: str = ""

3.10.5 第 4 步：数据库层（database.py）

在 Claude Code 中输入：

请创建 finance/database.py，实现数据库操作层：1. 数据库文件放在 ~/.finance-cli/data.db（用户主目录下）2. init_db() — 创建 categories 表和 records 表 + 写入 6 个默认分类3. add_record(amount, category_name, date, note) — 插入一笔账目，分类不存在时报错4. list_records(month, category_name) — 查询账目，支持按月份和分类筛选5. delete_record(record_id) — 删除一笔账6. get_stats(month) — 按分类统计支出（总金额、笔数）​要求：使用 sqlite3（Python 标准库），查询结果用 JOIN 关联分类名。

AI 生成的 finance/database.py 核心函数：

import sqlite3import osfrom finance.models import DEFAULT_CATEGORIES, Record​DB_DIR = os.path.join(os.path.expanduser("~"), ".finance-cli")DB_PATH = os.path.join(DB_DIR, "data.db")​​def _get_conn():"""获取数据库连接"""os.makedirs(DB_DIR, exist_ok=True)conn = sqlite3.connect(DB_PATH)conn.row_factory = sqlite3.Row # 让查询结果可以像字典一样取值return conn​​def init_db():"""初始化数据库：建表 + 写入默认分类"""conn = _get_conn()cursor = conn.cursor()​cursor.execute("""CREATE TABLE IF NOT EXISTS categories ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE)""")​cursor.execute("""CREATE TABLE IF NOT EXISTS records ( id INTEGER PRIMARY KEY AUTOINCREMENT, amount REAL NOT NULL, category_id INTEGER NOT NULL, record_date TEXT NOT NULL, note TEXT DEFAULT '', created_at TEXT DEFAULT (datetime('now', 'localtime')), FOREIGN KEY (category_id) REFERENCES categories(id))""")​for cat_name in DEFAULT_CATEGORIES: cursor.execute( "INSERT OR IGNORE INTO categories (name) VALUES (?)", (cat_name,))​conn.commit()conn.close()​​def add_record(amount: float, category_name: str, date: str, note: str = "") -> int:"""添加一笔账目，返回新记录的 ID"""conn = _get_conn()cursor = conn.cursor()​# 先查分类 IDcursor.execute("SELECT id FROM categories WHERE name = ?", (category_name,))row = cursor.fetchone()if row is None: conn.close() raise ValueError(f"未知分类：{category_name}。可用分类：{', '.join(DEFAULT_CATEGORIES)}")​category_id = row["id"]cursor.execute( "INSERT INTO records (amount, category_id, record_date, note) VALUES (?, ?, ?, ?)",(amount, category_id, date, note))new_id = cursor.lastrowidconn.commit()conn.close()return new_id

其余三个函数（list_records、delete_record、get_stats）的结构类似，完整代码约 150 行（见项目源码 finance/database.py）。

3.10.6 第 5 步：Web 界面（web.py）

在 Claude Code 中输入：

请创建 finance/web.py，实现 Streamlit Web 界面：1. 页面配置：标题"个人记账助手"，宽屏布局2. 侧边栏导航：三个选项——添加记录、账目列表、分类统计3. "添加记录"页：金额输入框、分类下拉框、日期选择器、备注输入框、提交按钮4. "账目列表"页：月份和分类筛选、表格展示所有记录、底部显示合计5. "分类统计"页：统计表（分类、笔数、合计、占比）+ 柱状图6. 启动时自动调用 init_db() 确保数据库存在

AI 生成的 finance/web.py 关键部分：

import streamlit as stimport pandas as pdfrom datetime import date​from finance.database import init_db, add_record, list_records, delete_record, get_statsfrom finance.models import DEFAULT_CATEGORIES​# 页面配置st.set_page_config(page_title="个人记账助手", layout="wide")init_db()​# 侧边栏导航menu = st.sidebar.radio("导航", ["添加记录", "账目列表", "分类统计"])​# "添加记录" 页面if menu == "添加记录":st.header("添加一笔账目")amount = st.number_input("金额（元）", min_value=0.01, value=35.0, step=0.5)category = st.selectbox("分类", DEFAULT_CATEGORIES)record_date = st.date_input("日期", value=date.today())note = st.text_input("备注（可选）", placeholder="例如：外卖")​if st.button("记录这笔账", type="primary"):record_id = add_record(amount, category, record_date.isoformat(), note)st.success(f"已记录 #{record_id}：{category} {amount:.2f} 元")​# "账目列表" 页面elif menu == "账目列表":st.header("账目列表")records = list_records()if not records:st.info("暂无记录")else:# 构建表格并展示df = pd.DataFrame([{"ID": r.id, "日期": r.record_date,"分类": r.category_name, "金额": f"{r.amount:.2f}","备注": r.note } for r in records])st.dataframe(df, use_container_width=True, hide_index=True)

完整代码见项目源码 finance/web.py，约 130 行。

3.10.7 第 6 步：启动并验证

激活虚拟环境后，启动 Streamlit：

# 激活虚拟环境# Windows：venvScriptsactivate# macOS/Linux：source venv/bin/activate​# 启动 Web 服务streamlit run finance/web.py

浏览器会自动打开 http://localhost:8501。如果没自动打开，手动访问这个地址即可。

你会看到一个完整的 Web 界面：

• 左侧侧边栏有三个导航选项
• 点击「添加记录」→ 填写金额、选择分类、选择日期、输入备注 → 点击按钮，记录成功
• 点击「账目列表」→ 看到所有记录以表格展示，可按月份和分类筛选
• 点击「分类统计」→ 看到柱状图和统计表

验证清单：

• 添加一条「餐饮 35.5 元」的记录
• 添加一条「交通 120 元」的记录
• 在账目列表中看到这两条记录
• 分类统计中有对应的柱状图
• 删除一条记录，列表刷新后该记录消失

3.10.8 项目总结

总共 不到 350 行代码，你就拥有了一个带 Web 界面的记账工具。数据库文件自动创建在 C:Users你的用户名.finance-clidata.db（Windows）或 ~/.finance-cli/data.db（macOS/Linux），不会丢失。

3.10.9 你学到了什么

第四部分：AI技能系统（Skills）深度实践

如果说前面几部分教你的是"怎么和AI对话"，这一部分教你的是"怎么给AI写操作手册" —— 让AI不仅能听懂你的临时指令，还能按照标准化的流程高效执行重复性任务。

还记得 Part 4 开头的 Harness 七层框架吗？Skill 是其中的第三层，也是最重要的一层：它把专业知识变成 cc 在需要时按需调用的"外接大脑"。大模型再聪明，也不可能把所有领域的最佳实践都塞进训练数据。但有了 Skill，你可以——这正是它如此重要的原因。

4.1 什么是AI技能（Skill）

4.1.1 Skill 的定义

Skill（技能） 是一个封装了特定能力的可复用指令集。

打个比方：你每次做一道菜，都要从头回忆配料和步骤，很容易忘这忘那。但如果你把菜谱写下来，下次照着做就行了，还能分享给别人。Skill 就是给AI写的"菜谱" —— 把一个复杂的任务标准化、流程化，让AI每次都能按照固定的高质量标准执行。

Skill vs 单次 Prompt：

4.1.2 Skill 的核心价值

0. 一致性：确保AI每次执行都遵循相同标准（不会这次用Tab缩进，下次用空格）
1. 效率：复杂流程一键触发，无需每次重写Prompt
2. 可复用：跨项目、跨团队共享最佳实践
3. 可迭代：持续优化和升级，越用越好

4.1.3 Skill 的组成结构

很多人以为 Skill 就是一个 Markdown 文件，其实不是。一个完整的 Skill 是一个目录，可以包含多种类型的文件，就像一个"能力包"。

打个比方：如果把 Skill 比作一本食谱，那么：

• SKILL.md 就是食谱本身（菜名、步骤、注意事项）
• scripts/ 就是配套的厨房小工具（削皮刀、量杯 —— 封装好的辅助脚本）
• resources/ 就是附赠的食材包和调料配比表（模板、示例数据、配置）
• references/ 就是食谱末尾的"参考书目"（营养学标准、食品安全规范 —— AI 可随时查阅的参考资料）

标准 Skill 目录结构：

skill-xxx/# Skill 根目录（命名规范：小写+短横线）├── SKILL.md# 核心：技能描述文件（必选）├── scripts/# 辅助脚本目录（可选）│├── helper.py# Python 辅助脚本│└── utils.js# JavaScript 工具函数├── resources/ # 配套资源目录（可选）│├── template/# 模板文件（如代码模板、报告模板）│├── examples/# 示例文件（如输入/输出示例数据）│└── config/ # 配置文件（如规则定义、默认参数）├── references/ # 参考文档目录（可选）│├── best-practices.md # 最佳实践文档│├── api-docs.md # API 参考文档│└── standards.md # 行业/团队编码规范└── requirements.txt # 依赖声明（可选，列出脚本需要的第三方包）

各组成部分详解：

1. SKILL.md（必选）—— 技能的"说明书"

这是 Skill 的核心载体。它包含两部分：头部的元数据（Frontmatter） 和正文的具体指令。

---# 元数据（Frontmatter，YAML 格式）name: react-component-generator# 技能名称（唯一标识）version: 1.0# 技能版本description: 根据需求生成符合项目规范的 React 组件文件集# 技能简介trigger: ["创建组件", "新建React组件", "生成组件"]# 触发关键词tools: ["typescript", "react"] # 依赖工具author: your-name# 技能作者---​# React 组件生成器​## 执行步骤1. 确认组件名称和功能需求2. 在 src/components/{componentName}/ 目录下创建文件3. 按照 resources/template/ 中的模板生成代码4. 运行 scripts/validate.js 验证组件结构​## 输出规范- 所有文件创建完成后，报告创建的文件列表- 给出组件的使用示例代码​## 错误处理- 如果目录已存在，提示用户确认是否覆盖- 如果缺少依赖包，提示安装命令​## 示例给一个完整的输入→输出示例。

2. scripts/（可选）—— 辅助脚本

当 Skill 需要执行复杂逻辑时（如数据预处理、文件批量操作、格式验证），把这些逻辑封装到脚本中比写在 SKILL.md 里更清晰：

# scripts/helper.py —— 辅助脚本示例def fill_missing_value(df, column, strategy="mean"):"""缺失值填充：把复杂逻辑封装成函数，SKILL.md 中只需调用即可"""if strategy == "mean": df[column].fillna(df[column].mean(), inplace=True)elif strategy == "empty": df[column].fillna("", inplace=True)return df

3. resources/（可选）—— 配套资源

• template/：存放代码模板、文档模板。例如 React 组件的标准结构模板，AI 可以基于模板快速生成代码
• examples/：存放输入/输出示例。帮助 AI 理解"好的输出长什么样"
• config/：存放配置文件（JSON/YAML），定义规则和参数，避免在 SKILL.md 中硬编码

4. references/（可选）—— 参考文档

与 resources/ 不同，references/ 存放的不是"模板和配置"，而是 AI 执行任务时可以查阅的知识性文档。比如：

• 编码规范文档（团队的代码风格指南）
• 安全审计标准（如 OWASP Top 10 清单）
• API 文档（第三方服务的接口说明）
• 技术选型文档（为什么用 A 不用 B 的决策记录）

5. requirements.txt（可选）—— 依赖声明

如果 scripts/ 中的脚本依赖第三方库，在这里声明，方便部署时一键安装：

pandas>=2.0.0openpyxl>=3.1.0

简单 vs 完整 Skill 的选择：

4.1.4 Skill 的类型分类

4.2 官方与社区 Skill 资源

你不必从零开始造轮子。Skill 生态已经非常成熟，从 Anthropic 官方到头部大厂、再到社区开发者，已经沉淀了大量可直接使用的高质量 Skill。学会"找到好 Skill → 评估 → 安装 → 在此基础上定制"，是比从头写更高效的路径。

4.2.1 Anthropic 官方 Skill 库

仓库地址：github.com/anthropics/…

这是 Anthropic 官方维护的 Skill 库，质量最高、最值得优先使用。官方对 Skill 的定义是：

官方 Skill 分类总览：

安装方式（使用 Vercel Skills CLI）：

# 安装 Anthropic 官方全部 Skill（全局安装）$ npx skills add anthropics/skills -g# 只安装指定 Skill（推荐按需安装）$ npx skills add anthropics/skills@frontend-design -g$ npx skills add anthropics/skills@mcp-builder -g$ npx skills add anthropics/skills@skill-creator -g

手动安装（不使用 CLI）：

如果你不想用 npx skills 命令，也可以手动操作：

# 克隆官方仓库到本地$ git clone https://github.com/anthropics/skills.git# 将需要的 Skill 目录复制到你的项目中$ cp -r skills/skills/frontend-design .claude/skills/

4.2.2 Vercel 官方 Skill 库

仓库地址：github.com/vercel-labs…

Vercel（Next.js 的母公司）维护的 Skill 库，专注于 React、Next.js、AI SDK、部署 等前端生态。如果你用 Next.js 技术栈开发，这个库非常有价值。

Vercel Skill 分类：

安装方式：

# 安装 Vercel 全部 Skill$ npx skills add vercel-labs/skills -g# 安装 find-skills（推荐首先安装，用于搜索发现其他 Skill）$ npx skills add vercel-labs/skills@find-skills -g -y

4.2.3 Vercel Skills CLI：Skill 的"包管理器"

Vercel 还提供了一个命令行工具 npx skills，可以把它理解为 Skill 世界的 npm —— 用来搜索、安装、管理各种 Skill。

基本用法：

# 搜索 Skill（按关键词）$ npx skills find "react testing"# 安装 Skill（从 GitHub 仓库）$ npx skills add <owner/repo># 安装仓库中的全部 Skill$ npx skills add <owner/repo>@<name> # 安装指定 Skill$ npx skills add <owner/repo> -g# 全局安装（所有项目可用）# 列出已安装的 Skill$ npx skills list# 初始化（在当前项目创建 Skill 目录）$ npx skills init

支持的 AI 工具：Claude Code、GitHub Copilot、Cursor、Qoder、OpenAI Codex、Cline、Windsurf 等多种 AI 编程工具。具体支持范围会随 CLI 版本变化，安装前以项目 README 为准。

4.2.4 社区 Skill 库

除了官方库，社区贡献了大量 Skill 资源：

精选 GitHub 仓库：

alirezarezvani/claude-skills 领域覆盖（235+ Skill）：

工程核心（37）：架构、前端、后端、QA、DevOps、安全、AI/ML高级工程（45）：Agent设计器、RAG架构师、数据库设计、CI/CD构建器、MCP构建器产品（16）：产品经理、UX研究员、UI设计、落地页、SaaS脚手架营销（44）：内容、SEO、CRO、渠道、增长、情报、销售项目管理（9）：Scrum Master、Jira集成、Confluence集成C-Level顾问（34）：全套C-Suite角色（CTO、CFO等）合规与质量（14）：ISO 13485、GDPR、FDA合规商业与增长（5）：客户成功、销售工程师、收入运营财务（4）：财务分析、SaaS指标教练

安装社区 Skill：

# 从社区仓库安装$ npx skills add alirezarezvani/claude-skills -g$ npx skills add ComposioHQ/awesome-claude-skills -g# 手动安装（克隆后复制需要的目录）$ git clone https://github.com/alirezarezvani/claude-skills.git$ cp -r claude-skills/engineering-team/frontend .claude/skills/

国内大厂 Skill 库（ 国内用户推荐）：

国内头部科技公司也在积极拥抱 Skill 生态，维护了多个高质量的 Skill 库：

安装国内大厂 Skill 示例：

# 科大讯飞 iFly-Skills（语音、OCR、翻译等 AI 能力）$ git clone https://github.com/iflytek/iFly-Skills.git$ cp -r iFly-Skills/ifly-pdf-image-ocr .claude/skills/# 注意：需要在讯飞开放平台申请 API Key，配置 XFEI_APP_ID 等环境变量# 字节跳动 AgentKit Samples$ git clone https://github.com/bytedance/agentkit-samples.git$ cp -r agentkit-samples/skills/byted-web-search .claude/skills/# 注意：需要火山引擎 API Key

4.2.5 Skill 聚合平台

如果觉得逐个找仓库太麻烦，还有专门的 Skill 聚合搜索平台：

在这些平台上，你可以按分类浏览、按关键词搜索，找到需要的 Skill 后一键安装。

4.2.6 Cursor 规则库

Cursor 使用 Rules 作为项目级 AI 行为规范。旧版常见 .cursorrules，新版更推荐 .cursor/rules/*.mdc。它和 Skill 不完全相同，但都属于“把经验写成可复用上下文”的做法。社区贡献了大量现成模板：

4.2.7 使用第三方 Skill 的安全评估

Skill 本质上是给 AI 的"操作指令"，某些恶意 Skill 可能包含危险操作。在使用任何第三方 Skill 之前，必须进行安全评估：

安全检查的最佳实践：

# 1. 安装前先浏览 Skill 内容（不要盲目安装）# 在 GitHub 上直接阅读 SKILL.md# 2. 检查 scripts/ 目录中的脚本（如果有的话）# 确保没有网络请求、文件删除等危险操作# 3. 在测试项目中先试用，确认安全后再用于正式项目

4.2.8 经典 Skill 实操体验

在学习"如何创建 Skill"之前，先来体验几个经典的现有 Skill，建立直观感受。

案例一：用 skill-creator 让 AI 帮你创建 Skill

skill-creator 是 Anthropic 官方提供的一个"元技能" —— 它的功能就是帮你创建新的 Skill。这相当于请了一位 Skill 专家替你写"操作手册"。

# Step 1：安装 skill-creator$ npx skills add anthropics/skills@skill-creator -g

安装后，在 Claude Code 中输入：

> 用 skill-creator 帮我创建一个名为 weekly-report-generator 的技能。> 功能：每周自动扫描本周的 Git 提交记录和 TODO 变更，> 生成一份结构化的周报 Markdown 文件。> 需要的工具：Read、Glob、Bash（用于 git log）。

Claude 会按照 skill-creator 的规范，自动帮你生成完整的 Skill 目录：

预期输出：~/.claude/skills/weekly-report-generator/├── SKILL.md# 包含 Frontmatter 和详细执行步骤├── scripts/│ └── collect-commits.sh # 收集本周提交的脚本└── resources/ └── template/└── weekly-report.md# 周报模板

案例二：使用官方 PDF 文档处理 Skill

Anthropic 官方的 pdf Skill 可以让 Claude 处理 PDF 文件 —— 解析内容、提取信息、生成摘要等。

# 安装 PDF 技能$ npx skills add anthropics/skills@pdf -g

安装后即可直接使用：

> 请读取 docs/产品需求文档.pdf，提取其中的核心功能列表和技术要求，> 整理成一份 Markdown 格式的摘要。

Claude 会调用 pdf Skill 中的脚本解析 PDF 文件结构，提取文本内容并按你的要求整理输出。

案例三：使用官方 frontend-design Skill

frontend-design Skill 让 Claude 具备专业的前端设计能力 —— 生成像素级精确的 UI 组件。

# 安装前端设计技能$ npx skills add anthropics/skills@frontend-design -g

使用示例：

> 请使用 frontend-design 技能，为书签管理器设计一个响应式的卡片列表页面。> 要求：支持暗色模式，卡片包含标题、URL、标签和收藏时间。> 技术栈：React + Tailwind CSS。

4.3 构建自己的 Skill

这是本部分最核心的内容。我们通过三个实战案例，手把手教你创建自己的Skill。

4.3.1 识别 Skill 化的机会

观察你日常使用AI时的重复行为：

• 你是否经常给AI写类似的Prompt？→ 把它变成Skill
• 你的项目是否有固定的开发模式？→ 把它变成Skill
• 你是否有标准化的审查流程？→ 把它变成Skill

4.3.2 实战：创建一个 React 组件生成 Skill

需求：每次创建新的React组件时，需要遵循统一的文件结构和编码规范。我们来创建一个包含模板和验证脚本的完整 Skill 包。

Step 1：创建 Skill 目录结构

在项目根目录下创建如下结构：

# 一次性创建完整的 Skill 目录$ mkdir -p .claude/skills/react-component/scripts$ mkdir -p .claude/skills/react-component/resources/template$ mkdir -p .claude/skills/react-component/resources/examples

创建后的目录结构：

.claude/skills/react-component/# Skill 根目录├── SKILL.md# 核心指令文件├── scripts/# 辅助脚本│ └── validate.js # 组件结构验证脚本└── resources/ # 配套资源 ├── template/ # 代码模板 │ ├── component.tsx.tpl# 组件主文件模板 │ └── test.tsx.tpl # 测试文件模板 └── examples/ # 示例└── BookmarkCard-example/ # 一个完整的示例组件供参考

Step 2：编写 SKILL.md（核心指令）

创建 .claude/skills/react-component/SKILL.md：

---name: react-component-generatorversion: 1.0description: 根据组件名称和功能描述，生成符合项目规范的 React 组件文件集trigger: ["创建组件", "新建React组件", "生成组件"]tools: ["typescript", "react", "tailwindcss"]author: your-name---​# React 组件生成器​## 触发条件当用户要求创建新的 React 组件时使用此 Skill。​## 输入参数- componentName（必填）：组件名称，使用 PascalCase 格式- description（必填）：组件功能描述- hasProps（可选，默认true）：是否需要 Props 类型定义- hasState（可选，默认false）：是否需要状态管理​## 执行步骤​1. 在 `src/components/` 目录下创建组件文件夹：`src/components/{componentName}/`​2. 参考 `resources/template/` 中的模板文件创建以下文件：- `index.tsx` - 组件主文件（参考 component.tsx.tpl）- `types.ts` - TypeScript 类型定义（如果 hasProps=true）- `{componentName}.test.tsx` - 测试文件（参考 test.tsx.tpl）​3. 组件代码规范：- 使用函数式组件 + TypeScript- Props 使用 interface 定义，命名为 {componentName}Props- 使用 Tailwind CSS 处理样式- 导出使用 named export- 添加 JSDoc 注释说明组件功能​4. 测试代码规范：- 使用 @testing-library/react- 至少包含：渲染测试、Props 传递测试​5. 创建完成后，可运行 `scripts/validate.js` 验证组件结构完整性。​## 输出规范- 所有文件创建完成后，报告创建的文件列表- 给出组件的使用示例代码​## 参考示例参见 `resources/examples/BookmarkCard-example/` 中的完整示例。​## 示例​输入：- componentName: "BookmarkCard"- description: "展示单个书签的卡片组件，显示标题、URL和标签"- hasProps: true- hasState: false​预期输出文件：- src/components/BookmarkCard/index.tsx- src/components/BookmarkCard/types.ts- src/components/BookmarkCard/BookmarkCard.test.tsx

Step 3：创建辅助脚本（scripts/）

创建 .claude/skills/react-component/scripts/validate.js：

// scripts/validate.js —— 验证组件目录结构是否完整// AI 在执行 Skill 后可以运行此脚本进行自检​const fs = require('fs');const path = require('path');​function validateComponent(componentName) { const dir = path.join('src/components', componentName); const requiredFiles = ['index.tsx', 'types.ts']; const missing = [];​ requiredFiles.forEach(file => {if (!fs.existsSync(path.join(dir, file))) { missing.push(file);}});​ if (missing.length > 0) {console.error(` 组件 ${componentName} 缺少文件: ${missing.join(', ')}`);return false;} console.log(` 组件 ${componentName} 结构验证通过`); return true;}​// 从命令行参数获取组件名const componentName = process.argv[2];if (!componentName) { console.error('用法: node validate.js <ComponentName>'); process.exit(1);}validateComponent(componentName);

Step 4：创建代码模板（resources/template/）

创建 .claude/skills/react-component/resources/template/component.tsx.tpl：

// resources/template/component.tsx.tpl —— 组件代码模板// AI 生成代码时参考此模板结构​/** * {componentName} 组件 * {description} */​import { {componentName}Props } from './types';​export function {componentName}({ ...props }: {componentName}Props) { return (<div className="..."> {/* 组件内容 */}</div>);}

Step 5：在 CLAUDE.md 中引用此 Skill

在你的 CLAUDE.md 文件中添加：

## 可用 Skills- 创建 React 组件时，请读取 `.claude/skills/react-component/SKILL.md` 并严格遵循其中的规范

Step 6：使用 Skill

在 Claude Code 中输入：

> 请按照 React 组件生成器 Skill 的规范，创建一个 BookmarkCard 组件。> 组件功能：展示单个书签的卡片，显示标题、URL、描述和标签列表。> 需要 Props，不需要状态管理。

Claude Code 会按照 Skill 定义的规范，参考模板文件，自动创建所有文件。完成后你还可以运行验证脚本确认结构：

$ node .claude/skills/react-component/scripts/validate.js BookmarkCard 组件 BookmarkCard 结构验证通过

4.3.3 实战：创建一个 API 端点生成 Skill

这个 Skill 相对简单，不需要辅助脚本，只需一个 SKILL.md 加一份配置文件：

.claude/skills/api-endpoint/├── SKILL.md# 核心指令└── resources/ └── config/└── response-format.json # API 统一返回格式定义

创建 .claude/skills/api-endpoint/SKILL.md：

---name: api-endpoint-generatorversion: 1.0description: 为指定的数据模型生成标准的 CRUD API 端点trigger: ["创建API", "生成端点", "新建接口"]---# RESTful API 端点生成器## 输入参数- modelName（必填）：数据模型名称（如 "bookmark"、"tag"）- fields（必填）：模型字段列表- operations（可选，默认全部）：需要的操作（create/read/update/delete/list）## 执行步骤1. 在 `src/app/api/{modelName}s/` 目录下创建 `route.ts`2. 实现以下端点： - GET /api/{modelName}s → 获取列表（支持分页、搜索） - POST /api/{modelName}s → 创建 - GET /api/{modelName}s/[id] → 获取单个 - PUT /api/{modelName}s/[id] → 更新 - DELETE /api/{modelName}s/[id] → 删除3. 代码规范： - 使用 Prisma Client 操作数据库 - 统一返回格式参考 `resources/config/response-format.json` - 包含输入验证 - 包含错误处理（try-catch）4. 创建完成后，列出所有 API 端点的 URL 和用法

同时创建 .claude/skills/api-endpoint/resources/config/response-format.json：

{"success_response": { "success": true, "data": "<返回数据>"},"error_response": { "success": false, "error": "<错误信息>"},"list_response": { "success": true, "data": "<数据数组>", "pagination": { "page": 1, "pageSize": 20, "total": 100 }}}

4.3.4 实战：创建一个 Git 规范化 Skill

Git 规范化 Skill 非常简单，不需要脚本和资源文件，只需一个 SKILL.md 即可。这说明并非所有 Skill 都要用上全套目录 —— 够用就好。

创建 .claude/skills/git-commit/SKILL.md：

---name: git-commit-standardversion: 1.0description: 在提交代码时，自动生成符合 Conventional Commits 规范的 commit messagetrigger: ["提交代码", "git commit", "生成commit"]---# Git 提交规范化## 执行步骤1. 运行 `git diff --staged` 查看暂存区的修改2. 分析修改内容，判断变更类型： - feat: 新功能 - fix: 修复Bug - refactor: 重构（不改变功能） - style: 样式修改 - docs: 文档更新 - test: 测试相关 - chore: 构建/工具变更3. 生成 commit message，格式： ``` <type>(<scope>): <description> <body> ```4. 显示给用户确认后执行 `git commit`## 示例修改了 src/components/BookmarkCard.tsx 中的样式生成的 message：​```style(BookmarkCard): 优化书签卡片的响应式布局- 调整了移动端下的卡片宽度- 修复了标签溢出问题​```

4.3.5 实战：创建一个代码安全审计 Skill（references 实践）

前面三个案例分别展示了 scripts/、resources/、纯 SKILL.md 的用法，这个案例重点展示 references/ 目录 —— 当 Skill 需要 AI 依据特定的标准和规范来执行任务时，把参考文档放入 references/ 是最佳实践。

需求：在提交代码前，让 AI 按照 OWASP 安全清单和团队编码安全规范，对代码进行安全审计。

Step 1：创建 Skill 目录结构

$ mkdir -p .claude/skills/security-audit/references$ mkdir -p .claude/skills/security-audit/resources/examples

完成后的结构：

.claude/skills/security-audit/├── SKILL.md# 审计流程指令├── references/#参考文档（AI 审计时依据的"法规"）│ ├── owasp-top10-checklist.md # OWASP Top 10 安全检查清单│ └── team-security-standards.md # 团队安全编码规范└── resources/ └── examples/└── audit-report-sample.md # 审计报告示例（让 AI 知道输出长什么样）

Step 2：编写 SKILL.md

创建 .claude/skills/security-audit/SKILL.md：

---name: security-auditversion: 1.0description: 对指定代码进行安全审计，依据 OWASP Top 10 和团队安全规范输出审计报告trigger: ["安全审计", "security audit", "安全检查", "代码安全"]---# 代码安全审计## 执行步骤1. 读取用户指定的代码文件或目录2. 阅读 `references/owasp-top10-checklist.md`，逐项检查代码是否存在对应漏洞3. 阅读 `references/team-security-standards.md`，检查代码是否符合团队安全规范4. 按照 `resources/examples/audit-report-sample.md` 的格式，生成安全审计报告5. 对每个发现的问题：标注严重等级（高危/中危/低危）、给出修复建议和修复代码## 输出规范- 使用 Markdown 表格列出所有问题- 每个问题包含：文件路径、行号、问题描述、严重等级、修复建议- 最后给出安全评分（0-100）和总结## 错误处理- 如果代码量过大，优先审计 API 路由和数据库操作相关的文件- 如果无法判断是否存在风险，标记为"待人工确认"

Step 3：编写参考文档（references/）

这是本案例的重点。references/ 中的文件不会直接变成输出，而是作为 AI 做判断时的"知识库"。

创建 .claude/skills/security-audit/references/owasp-top10-checklist.md：

# OWASP Top 10 安全检查清单## 1. 注入攻击（Injection）- [ ] SQL 查询是否使用参数化查询或 ORM？- [ ] 是否存在字符串拼接 SQL 的情况？- [ ] 用户输入是否经过转义和过滤？## 2. 身份认证失效（Broken Authentication）- [ ] 密码是否明文存储？（应使用 bcrypt 等加密）- [ ] 会话令牌是否使用安全的随机数生成？- [ ] 是否有登录失败次数限制？## 3. 敏感数据泄露（Sensitive Data Exposure）- [ ] API 密钥、数据库密码是否硬编码在代码中？- [ ] 敏感数据是否通过 HTTPS 传输？- [ ] 日志中是否记录了敏感信息？## 4. XSS 跨站脚本攻击- [ ] 用户输入是否在渲染前经过转义？- [ ] 是否使用 dangerouslySetInnerHTML 等危险 API？- [ ] CSP（Content Security Policy）头是否设置？## 5. 安全配置错误- [ ] 是否关闭了调试模式？- [ ] 错误页面是否暴露了堆栈信息？- [ ] 默认账户密码是否已修改？（后续 6-10 条按同样格式补充）

创建 .claude/skills/security-audit/references/team-security-standards.md：

# 团队安全编码规范## 强制规则（违反即为高危）1. 禁止在代码中硬编码任何密钥、密码、令牌，必须使用环境变量2. 所有数据库操作必须通过 ORM（Prisma），禁止直接写 SQL3. 所有用户输入必须在服务端验证，不能只依赖前端验证4. API 路由必须有权限校验，不允许裸接口## 建议规则（违反为中危）1. 文件上传功能必须限制文件类型和大小2. 敏感操作（删除、修改密码等）需要二次确认3. 分页查询必须限制 pageSize 最大值，防止数据库压力攻击4. 错误响应不应包含内部实现细节

Step 4：编写输出示例（resources/examples/）

创建 .claude/skills/security-audit/resources/examples/audit-report-sample.md：

# 安全审计报告**审计范围**：src/app/api/**审计时间**：2026-04-30**审计依据**：OWASP Top 10 + 团队安全规范## 发现问题| # | 文件 | 行号 | 问题描述 | 等级 | 修复建议 ||---|------|------|---------|------|---------|| 1 | src/app/api/users/route.ts | 23 | SQL 字符串拼接，存在注入风险 |高危 | 改用 Prisma 参数化查询 || 2 | src/lib/auth.ts | 45 | API 密钥硬编码 |高危 | 移至 .env 环境变量 || 3 | src/app/api/upload/route.ts | 12 | 文件上传未限制类型 |中危 | 添加 MIME 类型白名单 |## 安全评分：65/100## 总结发现 2 个高危、1 个中危问题。建议优先修复高危问题后再上线。

Step 5：使用 Skill

> 请使用安全审计 Skill，对 src/app/api/ 目录下的所有文件进行安全检查。

AI 会先读取 references/ 中的两份参考文档作为审计标准，然后逐一检查代码，最后按照 resources/examples/ 中的示例格式输出审计报告。

现在回顾四个案例，每个都突出了不同的 Skill 目录组件：

4.4 Skill 与 AI 工具的集成

4.4.1 在 Claude Code 中集成

方法一：通过 CLAUDE.md 引用（推荐）

在 CLAUDE.md 中添加 Skill 引用：

## 项目 Skills以下 Skill 定义了标准化的开发流程（每个 Skill 是一个目录，核心指令在 SKILL.md 中）：- `.claude/skills/react-component/` - React 组件生成规范- `.claude/skills/api-endpoint/` - API 端点生成规范- `.claude/skills/git-commit/` - Git 提交规范- `.claude/skills/security-audit/` - 代码安全审计执行相关任务时，请先阅读对应 Skill 目录下的 SKILL.md 并严格遵循。如 Skill 中包含 scripts/、resources/ 或 references/，请一并参考。

方法二：通过自定义 slash commands

将 Skill 的触发文件放在 .claude/commands/ 目录下，即可通过 /skill名称 直接触发：

# 文件结构.claude/├── commands/│ ├── new-component.md # 触发方式：/new-component（引用 skills 中的规范）│ └── security-check.md # 触发方式：/security-check└── skills/ ├── react-component/ # 完整 Skill 包（SKILL.md + scripts + resources） │ ├── SKILL.md │ ├── scripts/ │ └── resources/ ├── api-endpoint/# 中等 Skill 包（SKILL.md + resources/config） │ ├── SKILL.md │ └── resources/ ├── security-audit/# 参考文档型（SKILL.md + references + resources/examples） │ ├── SKILL.md │ ├── references/ │ └── resources/ └── git-commit/ # 简单 Skill（仅 SKILL.md）└── SKILL.md

4.4.2 在 Cursor 中集成

将 Skill 的核心规则写入 Cursor Rules（推荐 .cursor/rules/*.mdc，旧项目可用 .cursorrules）：

When creating new React components:- Follow the structure defined in .claude/skills/react-component/SKILL.md- Reference templates in .claude/skills/react-component/resources/template/- Always create types.ts for Props definitions- Always include basic test file

4.5 Skill 的迭代与版本管理

4.5.1 持续优化

Skill 不是写完就不管了。每次使用后，记录：

• AI 哪些地方做得好？→ 保持
• AI 哪些地方做得不好？→ 在 Skill 中加入更明确的指令
• 有没有遗漏的边界情况？→ 补充到错误处理部分

4.5.2 版本管理

用 Git 管理你的 Skill 目录，就像管理代码一样：

# 提交整个 Skill 包（包括 SKILL.md、scripts、resources 等）$ git add .claude/skills/react-component/$ git commit -m "feat(skills): 新增 React 组件生成 Skill v1.0"# 更新 Skill 后，修改 SKILL.md 中的版本号并提交$ git add .claude/skills/react-component/SKILL.md$ git commit -m "chore(skills): 升级 React 组件 Skill 至 v1.1，优化模板"

4.6 Superpowers 插件

Superpowers 是 Claude Code 生态中的一类社区增强插件 / Skills 集合。它不是“必装”的，但思路值得学习：把成熟工作流封装成可复用能力，让 AI 不只是会写代码，还会按固定方法做事。

4.6.1 什么是 Superpowers？

Superpowers 本质是一套工作方法论集合，通常会封装成多个可复用 Skill。安装后，AI 可以在合适的任务中调用这些方法论。

安装前后对比：

4.6.2 核心 Skills 一览

4.6.3 安装方法

方式一：npx 一键安装（推荐）

# 进入你的项目目录（重要！不要在主目录 ~ 下运行）$ cd /your/project# 英文版（原版）$ npx superpowers# 中文增强版（推荐国内用户，包含 6 个中国特色 Skill）$ npx superpowers-zh

安装后会在项目下生成 .claude/skills/ 目录，包含所有 Skill 文件。

方式二：手动安装（备选）

# 克隆仓库git clone https://github.com/jnMetaCode/superpowers-zh.git# 复制 skills 到项目cp -r superpowers-zh/skills /your/project/.claude/skills

4.6.4 是否必须安装？

不是必须的。 Superpowers 是一个“锦上添花”的增强插件：

• 初学者：建议先不装，熟悉 Claude Code 基本操作后再考虑
• 日常开发：强烈推荐安装，能显著提升代码质量和开发流程规范性
• 团队项目：强烈推荐安装，统一团队的 AI 工作方法论

~/.claude/└── commands/ ← 你的全局 Skills ├── review.md← 代码审查 Skill ├── refactor.md← 重构优化 Skill └── test.md ← 测试生成 Skill项目根目录/└── .claude/ ├── commands/← 项目级 Skills │ ├── deploy.md ← 部署流程 Skill │ └── migrate.md← 数据库迁移 Skill ├── settings.json ← 项目配置 └── CLAUDE.md← 项目规则文件

图：Superpowers Skills 目录结构 —— 全局Skills对所有项目生效，项目级Skills仅对当前项目生效

4.7 MCP（Model Context Protocol）简介

MCP 是 Anthropic 推出的一个标准化协议，让 AI 工具可以连接外部服务和数据源。你可以把 MCP 理解为给 AI 装"插件"或"扩展能力"。

MCP 的概念：

AI 工具（Claude Code） │ ├── 内置能力：读写文件、运行命令 │ └── MCP 扩展能力：├── GitHub MCP Server → 操作 GitHub（创建PR、管理Issue）├── Database MCP Server → 直接查询数据库├── Browser MCP Server → 浏览器自动化测试└── 更多第三方 MCP Server...

MCP 与 Skill 的关系：

• Skill 定义了"做什么、怎么做"（流程和规范）
• MCP 提供了"能力扩展"（让AI能做更多事情）

两者互补：你可以在 Skill 中调用 MCP 提供的能力。例如，一个"部署检查 Skill"可以调用 GitHub MCP 来创建 PR。

4.8 本部分小结与实践练习

实践练习：

• 使用 npx skills add anthropics/skills@skill-creator -g 安装官方 skill-creator，体验用 AI 创建 Skill
• 浏览 SkillsMP（skillsmp.com/zh）或 skills.sh，找到3个感兴趣的社区 Skill 并阅读其 SKILL.md
• 创建一个项目初始化 Skill（包含 SKILL.md + resources/template/ 技术栈配置模板）
• 创建一个代码审查 Skill（包含 SKILL.md + references/ 审查标准文档）
• 将自定义 Skill 集成到 Claude Code 中并实际使用一次
• 用 Git 提交你的 Skill 目录

4.8.1 动手实践：创建一个「Git 提交规范化」Skill

前面看了 4 个案例，现在轮到你自己动手了。下面会带你从零创建一个 Git 提交规范化 Skill，整个流程大约 10 分钟。

第 1 步：创建 Skill 目录

mkdir -p .claude/skills/git-commit

第 2 步：编写 SKILL.md

创建 .claude/skills/git-commit/SKILL.md，写入以下内容：

---name: git-commit-standardversion: 1.0description: 在提交代码时，自动生成符合 Conventional Commits 规范的 commit messagetrigger: ["提交代码", "git commit", "生成commit"]---# Git 提交规范化## 执行步骤1. 运行 `git diff --staged` 查看暂存区的修改2. 分析修改内容，判断变更类型： - feat: 新功能 - fix: 修复Bug - refactor: 重构（不改变功能） - style: 样式修改 - docs: 文档更新 - test: 测试相关 - chore: 构建/工具变更3. 生成 commit message，格式：`<type>(<scope>): <description>`4. 显示给用户确认后执行 `git commit`## 示例修改了 `src/components/Header.tsx` 中的导航样式生成的 message：​```style(Header): 优化导航栏的响应式布局​```

第 3 步：在 CLAUDE.md 中注册 Skill

在项目根目录的 CLAUDE.md 文件中添加以下内容，让 Claude Code 知道这个 Skill 的存在：

## 项目 Skills- `.claude/skills/git-commit/` — Git 提交规范化执行相关任务时请先阅读对应 SKILL.md。

第 4 步：实际使用

0. 随便修改项目中的某个文件（加几行注释或改个变量名即可）
1. 运行 git add . 暂存修改
2. 在 Claude Code 中输入：

请用 git-commit Skill 帮我生成 commit message 并提交

4.Claude Code 会自动读取你的 SKILL.md，分析 git diff --staged 的内容，生成类似 style(Header): 优化导航栏的响应式布局 这样的规范化提交信息

第 5 步：用 Git 提交你的 Skill

git add .claude/skills/git-commit/git commit -m "feat(skills): 新增 Git 提交规范化 Skill"

4.8.2 进阶挑战（选做）

完成基础练习后，试试这些挑战来巩固你的 Skill 创建能力：

• 修改 Git 提交 Skill，加入对中文 commit message 的支持
• 参考 5.3.2 节，为你当前的技术栈创建一个组件生成 Skill（React/Vue/任意框架）
• 参考 5.3.5 节，创建一个包含 references/ 的代码审查 Skill，加入你团队的编码规范