Claude Code 完整指南

Codex安装教程

第一步注册账号

官网地址： https://api.chongplus.plus/

第二部安装 cc-switch

gitHub自行安装：https://github.com/farion1231/cc-switch/releases/

第三步 安装codex

npm i -g @openai/codex

第四步 创建api密钥，导入cc-switch

第五步 成功

目目录下打开终端，执行以下命令，等待 5～10 秒初始化，开始使用

codex

claude code

claude code安装

以下命令安装即可

node版本检查：node -v
npm版本检查：npm -v
npm国内镜像：npm config set registry https://registry.npmmirror.com/
git版本检查：git -v
ClaudeCode安装命令：npm install -g @anthropic-ai/claude-code
ClaudeCode版本检查：claude --version
启动ClaudeCode：claude


修改配置文件跳过登录步骤

1.输入用户名回车

2.选择Claunde.js文件

3.新增内容

"hasCompletedOnboarding": true

4.回到cmd输入claude选择第一个相信文件夹跳过登录步骤

5.打开 CC SWitch配置deeekseek

6.重新打cmd启动Claude 输入/model查看deekseek模型 选择刚刚配置得模型deekseek-v4-pro模型即可

7.输入你是上面模型即可确认模型是否安装成功

8.测试Claude Code叫他做项目，在桌面新建一个文件，进入这个文件，打开CMD 启动Claude，选择信任该文件夹，就可以开始使用Claude code

claudecode进阶使用

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

配置层级：

全局配置（影响所有项目）
  └── ~/.claude/settings.json

项目级配置（只影响当前项目）
  └── 项目根目录/.claude/settings.json

项目上下文文件（告诉AI项目背景信息）
  └── 项目根目录/CLAUDE.md ← 最重要！

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
}

注意：权限设置要谨慎。过于宽松的权限可能导致AI执行你不期望的操作。建议初学者保持默认设置，让 Claude Code 在执行每个操作前都询问你确认。

文件一般在整个项目目录下面

测试 重启Claude 看到配置的已经生效 输入根据配置文件 你现在执行的操作有哪些

CLAUDE.md全局配置

这个文件一般在用户.claude文件夹下面配置这个一般是全局的每个项目都是识别到一般是通用的

CLAUDE.md项目说明书

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

为什么 CLAUDE.md 如此重要？

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

CLAUDE.md 模板（可直接复制修改）：文档可以要Claude Code帮你生成

## 项目概述
一句话描述这个项目做什么。

## 技术栈
- 前端：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 类型定义
​```cpp

## 编码规范
- 使用函数式组件 + React Hooks
- 组件文件使用 PascalCase 命名（如 BookmarkCard.tsx）
- 工具函数使用 camelCase 命名
- API 路由返回统一格式：{ success: boolean, data?: any, error?: string }
- 所有数据库操作通过 Prisma Client 执行

## 当前开发状态
-  项目初始化完成
-  数据库 Schema 设计完成
-  书签 CRUD API 开发中
-  前端页面待开发
-  搜索功能待开发

## 注意事项
- mysql 数据库名称 claude.db，不要提交到 Git
- 环境变量在 .env 文件中，不要提交到 Git
- 所有新功能先创建 Git 分支再开发

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

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

层级	路径	作用范围	适合写什么
全局级	~/.claude/CLAUDE.md	所有项目都会读	个人习惯、身份、翻译偏好（如"永远用中文回答"、"我是 xx、从事 xx"）
项目级	项目根目录/CLAUDE.md	仅本项目	项目技术栈、架构、规范、进度（可提交 Git，团队共享）
文件夹级	子目录/CLAUDE.md	仅该子目录	模块专属约定（如 src/payment/CLAUDE.md 写支付模块踩过的坑）

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

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

• /init 创建项目级：在项目根目录下运行 claude 后输入 /init，cc 会自动扫描项目并生成一份 CLAUDE.md 初稿，你再调整。官方建议：项目有一定规模再 /init 效果更好（太空它扫不出什么东西）。

• /memory 编辑全局级：在 cc 会话里输入 /memory 选择“全局 CLAUDE.md”，会用默认编辑器打开该文件供你修改。修改全局后需重启 cc 才生效。

最佳实践：

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

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

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

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

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

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

**在.claude文件家下面新建一个claude.md 文件放项目的基本需求 ，如果已经有项目的，可以叫Claude Code 生成 使用init来生成 **

二层记忆自己的笔记本

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

如何启用：

/memory

Auto Memory 会记哪几类东西：

类型	含义	举例
user	关于你	你的角色、偏好（如“不喜欢深色 UI”）
feedback	你给过的反馈	“不要这样做"、“对，就这样"
project	项目相关	进度、决策、技术选型
reference	外部资源索引	“某份设计文档在 docs/design.md”

使用手感（重要）：

• 它只在当前项目生效（文件存在项目目录下），换项目需重新积累

• 启用后 cc 不会每次都把所有记忆全部加载进上下文，只会读一份 memory.md 索引——遇到具体问题才去读对应的子文件，占 token 很少

• 随时可以用快捷键 Ctrl+O 在会话中查看实际被调用过的记忆内容

• 记错了就跟它说：“忘掉刚刚说的不喜欢深色主题”，它会自己删掉

提示： 一句话区分 CLAUDE.md vs Auto Memory：CLAUDE.md 是第一优先级、全量注入的明规则；Auto Memory 是第二优先级、按需注入的隐规则。两者配合，cc 越用越懂你。

三层记忆自建参考文档

除了上面两层，你还可以仿照 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 只在"需要的时候"才去读完整文档，既保证了准确性，又不占多余上下文。

三层记忆总览

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

层	位置	优先级	加载方式	谁在维护
1	CLAUDE.md（三级）	高	会话启动全量加载	你手动维护
2	Auto Memory	中	先读索引、按需读子文件	cc 自己写、你校对修改
3	参考文档	按需	cc 遇到对应任务才读	你手动维护

本质认知：agent 的所有"记忆"，本质上都是在合适的时候向大模型注入压缩过的上下文。粗暴点说 —— 这些记忆机制本质上还是提示词工程，只不过由 cc 帮你组织了层次。

claudeignore 文件

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

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

核心命令与日常使用

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

启动与基本交互

$ claude


$ claude --project-dir /path/to/your/project


$ claude --model sonnet


$ claude -p "请列出当前目录下所有的 JavaScript 文件"

对话交互基础

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

典型的交互流程：

你：帮我创建一个简单的 HTML 页面，显示"Hello AI Coding"

AI：好的，我来创建这个页面。

[AI 分析需求]
[AI 请求确认：我将创建文件 index.html，是否允许？]

你：是（按 Enter 确认）

AI： 已创建 index.html，包含以下内容：
   - 基本 HTML5 结构
   - 一个标题显示"Hello AI Coding"
   - 简单的居中样式

权限确认机制：

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

操作类型	示例	提示信息
创建文件	创建 index.html	"Will create file: index.html"
修改文件	修改 app.js 的第10行	"Will edit file: app.js"
执行命令	运行 npm install express	"Will run: npm install express"
删除文件	删除 temp.txt	"Will delete file: temp.txt"

你可以：

• 按 Enter 或输入 y → 确认执行

• 输入 n → 拒绝执行

• 输入补充信息 → 修改AI的计划

提示：如果你发现每次确认很烦，可以在 settings.json 中配置自动允许的操作（见 4.2 节）。但初学者建议保持默认，让自己有机会审查AI的每一步操作。

核心斜杠命令详解

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

基础高频命令：

命令	作用	使用场景
/help	显示帮助信息	忘记命令时查看
/model	查看/切换当前模型（高/中/低档）	需要换用更强/更快的模型时
/compact	压缩当前对话的上下文	对话太长，AI开始“遗忘”早期内容时
/clear	完全清空当前对话	开始全新的任务时
/context	详细查看上下文占比（各 MCP/Skill 各占多少）	优化 token、诊断哪里挨上下文
/memory	查看/编辑 CLAUDE.md 与自动记忆	管理项目/全局记忆、开启 Auto Memory
/status	查看会话状态	确认模型、Token 消耗
/cost	查看当前会话费用	监控花了多少钱
/review	对当前项目进行代码审查	完成功能后检查质量
/init	自动生成项目的 CLAUDE.md	进入新项目后的第一件事
/plan	切入 Plan Mode（只读规划模式）	复杂任务起手（详见 4.9 节）
/rewind	回滚 cc 之前的修改	“后悔药”，下面重点讲
/resume	选择历史会话恢复	上次话题还没聊完
/btw	“顺便问一句”，不污染主上下文	主任务进行中想问个无关问题

扩展管理命令：

命令	作用	使用场景
/skill <名称>	直接调用某个 Skill	手动触发，不要等 AI 自己决定
/agent	创建、查看、调用子代理（SubAgent）	手工创建专项 SubAgent
/plugin	插件管理界面（discover / installed）	发现、安装、卸载插件
/login	使用 Claude 官方订阅会员登录	有 Claude Pro/Max 会员时首选
/simplify	派 3 个子 Agent 从代码质量/性能/复用性三个角度优化	快速全面优化已有代码

最常用的三个命令详解：

/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

提示： 我的习惯：看到上下文高于 60% 了，就 /compact 一下。别等到接近满载、cc 自动压缩才动手——那时候它已经开始”遗忘”了。也可以让 cc 帮你打开常驻显示，重启终端后底部就会一直显示上下文余量。

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

命令	效果	适用时机
/compact	压缩历史为摘要，保留关键决策	同一任务对话过长、但还要继续做
/clear	彻底清空，等于重开	一个独立任务彻底结束，要开始全新任务

心法：宁可”多 /clear 几次重新介绍背景”，也不要”一直聊一直聊”。每个 /clear 都是给 AI 一次重新聚焦的机会。

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

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

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

注意： 底线提醒：/rewind 只能撤销 cc 自己编辑过的文件。它跑过的终端命令（安装依赖、下载文件、修改数据库）撤不了。真正靠谱的“后悔药”还是 Git（参见 4.5 节“Git 集成最佳实践”）。

/memory —— 记忆管理

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

/review —— 代码审查

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

> /review

AI: 正在审查项目代码...

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

快捷键速查

快捷键	作用
Enter	发送消息 / 确认操作
Shift + Enter	也是发送（不是换行！超多新手在这里发出了半截提示词）
Option + Enter（Mac）	换行输入（在提示词里换行不发送）
Ctrl + Enter（Windows）	换行输入（同上）
Ctrl + C	中断当前操作
Esc	取消正在生成的内容
Esc × 2（双击）	启动 /rewind 回滚界面
Shift + Tab	三种运行模式循环切换（Normal/Auto-Accept/Plan，详见 4.9）
↑ / ↓	浏览历史消息
Ctrl + B	让当前运行的命令到后台跑（不阻塞对话）
Ctrl + O	查看 Auto Memory 记录的具体内容

输入与交互高级技巧

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

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

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

 推荐：在 cc 会话里以 ! 开头，进入 Bash 模式跑命令
> !npm run dev
> !node app.js

提示： 后台运行：运行中的命令会阻塞跟 cc 的对话（比如 dev 服务起来后不会退出）。这时按 Ctrl+B，cc 会把它交到后台跑，你可以继续与 cc 对话。

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

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

> 参考 @src/auth/login.ts 的风格，在 @src/auth/ 下加个 register.ts


> 按 @docs/feature-spec.md 的需求实现

提示： 反直觉小冗识：你给 cc 的指令越短，它反而可能花越多 token——因为它要多费力探索项目才能猜到你想要什么。描述越具体 + 明确 @ 文件，成本反而低，效果反而准。

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

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

• 给设计参考图让 cc 实现一个类似的 UI

• 贴报错截图让 cc 判读

• 贴架架构图让 cc 按图实现

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

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

注意： 危险模式使用须谨慎：--dangerously-skip-permissions（绿灯模式）适合在沙箱环境 / 有 Git 存档 / 不重要的练手项目中使用。生产项目里不推荐，新手也请从默认模式起手。

Claude Code 实战工作流

官方推荐工作流

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

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

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

各阶段详解：

阶段	你该做什么	AI 在做什么	推荐模式
① Explore（探索）	告诉 AI 要改动的区域	读相关文件、grep、跟引用	Plan Mode
② Plan（规划）	让 AI 出详细方案并由你审核	生成计划、评估边界情况	Plan Mode
③ Implement（实施）	切出 Plan Mode 按计划执行	按顺序修改文件、运行构建	Normal / Auto-Accept
④ Commit（提交）	让 AI 生成提交消息并 commit	生成 commit message、可选开 PR	Normal

提示： 为什么要分阶段？ 试想一下这种体验：你说”加个软删除功能”，15 分钟后 AI 改了 14 个文件、动了全局查询过滤器、破坏了 3 个现有接口——你只能一个一个手工回退。这就是不规划直接干的代价。 在 Plan Mode 里多花 5 分钟讨论方案，换来执行阶段节省 30 分钟返工。Plan Mode 的详细用法在 4.9 节 详讲。

项目设置

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

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

完整示例

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

Step 1：初始化项目

$ mkdir hello-api
$ cd hello-api


$ 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!"
}

验证：如果浏览器能看到上面的 JSON 响应，恭喜！你用 Claude Code 成功创建了第一个 API！

Step 3：提交代码

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

AI 会执行：

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

Claude Code实战

Prompt 编写技巧

任务描述要具体，不要模糊**

 差：帮我做一个登录功能
 好：在 /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. 一次只做一件事

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

上下文管理策略

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

你观察到的情况	是什么问题	该怎么做
响应变慢、质量下降	上下文快满了	/context 看占比 → 高于 60% 就 /compact
AI 开始"遗忘"早期约定	早期信息被挤出窗口	立即 /compact
AI 重复问已回答过的问题	上下文混乱	/clear 开新会话
要切换到完全不同的任务	避免上一个任务的思路污染	/clear 开新会话
想永久记住某条规则	跨会话记忆	/memory 开启 Auto Memory 或写入 CLAUDE.md

费用控制策略

策略	方法	节省比例
分级使用	简单任务用 Haiku/DeepSeek，复杂任务用 Sonnet	30-50%
精准描述	减少来回修改次数	20-30%
及时 /compact	避免重复发送长上下文	10-20%
使用 /cost 监控	实时了解消耗	-
设置预算上限	Anthropic Console 中设置月度限额	防止超支

> /cost

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

大型代码库最佳实践

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

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

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

> /init

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

必补内容	为什么	示例
项目目录地图	让 AI 知道“去哪儿找代码”	认证逻辑在 src/auth/，UI 组件在 src/components/
不要碰的禁区	防止 AI 改坏	不要修改 prisma/migrations/，不要动 vendor/
团队约定	风格统一	所有 API 必须返回 { success, data, error }

提示： CLAUDE.md 是“起点上下文”，不是“全部上下文”。它就像一份给新人的入职手册，AI 看完后再现场探索代码——这正是 Agentic Search 的工作方式（参见 2.2.1 节）。

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

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

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

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

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

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

• 上下文里塞的越多，无关代码片段越多，AI 越容易抓错重点

• 上一任务的失败尝试、错路径、错假设，会污染下一个任务

官方建议：

时机	操作	区别
一个独立任务结束（PR 提交后）	/clear	完全清空对话，从零开始
同一任务内对话过长	/compact	压缩历史摘要，保留关键决策
想换条思路重做	退出 claude 重新启动	连状态栏模式都重置

核心心法：宁可“多 clear 几次重新介绍背景”，也不要“一直聊一直聊”。每个 /clear 都是给 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） 把这些能力接进来：

接入对象	解决什么	典型场景
GitHub MCP	读 PR、Issue、CI 日志	“这个 bug 在 PR #1234 里讨论过，看一下”
数据库 MCP（Postgres / MySQL）	直接查数据	“线上 user 表里有多少条 deleted_at 不为空的”
Jira / Linear MCP	读任务卡	“按 PROJ-123 的需求实现”
LSP（语言服务器）集成	精确跳转、查类型、找引用	等同于 IDE 的“查找所有引用”
Sentry / Datadog MCP	读告警、堆栈	“上一小时的 5xx 错误调一下”

提示： 配置入口：.claude/settings.json 中的 mcpServers 字段，或运行 claude mcp add ...。MCP 详细配置在第四部分 3.6 节讲解。

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

实践	命令/入口	何时做	收益
项目初始化	/init + 手工补充	第一次进入项目	让 AI 知道地图与禁区
任务拆分	心法（无命令）	每次提需求前	避免 AI 改坏一大片
上下文重置	/clear / /compact	任务结束 / 上下文过长	避免污染、节省 token
规划优先	/plan 或 Shift+Tab×2	复杂任务起手	先勘探后动手
任务卸载	Subagent / Skill	高频调研类任务	保护主上下文
工具接入	claude mcp add ...

自定义斜杠命令

<!-- .claude/commands/deploy.md -->


请执行以下部署前检查：
1. 运行所有测试：npm test
2. 检查是否有 lint 错误：npm run lint
3. 确认 .env.example 已更新（如果添加了新的环境变量）
4. 构建项目：npm run build
5. 报告所有检查结果

使用方式：

> /deploy

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

这里就建了一个.md的文件里面就给Claude输入了一个指令，启动claude就可以调用这个指令执行

新项目启动套件

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，让这件事不再发生"。

settings.local.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"
  },
     "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"文件已修改，建议检查一下改了什么\""
          }
        ]
      }
    ]
  }
}

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

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

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

注意：allow 按你的工具链改——用 yarn 就加 Bash(yarn *)，用 bun 就加 Bash(bun *)。deny 那几行建议原样留着，它们是安全底线。

.gitignore

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

.claude/settings.local.json
.cursor/
.aider*
.continue/
.cody/


*.pem
*.key
credentials.json
.npmrc
.aws/
.ssh/

注意一个细节：.claude/settings.local.json 被 gitignore 了，但 .claude/settings.json 和 .claude/skills/ 没有。意思是——项目配置团队共享，个人偏好（含 API key）自己留着。

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，后面写检查步骤。

核心价值：写一次，以后每次都是它替你查。详见第四部分完整教程。

三种安装方式

场景	做法
从零开始的新项目	模板复制进去，填入技术栈，第一次 commit 就带着完整配置
已有项目	CLAUDE.md 和 .gitignore 加到根目录，settings.json 合并到现有配置，skills 文件夹拖进去
所有项目通用	settings.json 和 skills 放 ~/.claude/ 全局生效；CLAUDE.md 每个项目单独写

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

配置 Claude Code：Hook + 权限模式 + Memory

本节目标：配置 Claude Code 的进阶设置，让开发更安全、更高效

演示的 Claude Code 功能：Hook 配置、权限模式、Memory 系统

Hook 配置：让 AI 自动执行命令

Hook（钩子）是 Claude Code 的一个强大功能——你可以在特定事件发生时（比如 AI 修改了文件），自动触发一条命令。

在我们的项目中，创建一个 .claude/settings.local.json 文件：

{
  "permissions": {
   "allow": [
     "Bash(npm run dev)",
     "Bash(npm run build)",
     "Bash(npx prisma *)",
     "Bash(npm install *)"
   ]
  },
  "hooks": {
   "PostToolUse": [
     {
      "matcher": "Write|Edit",
      "hooks": [
        {
         "type": "command",
         "command": "echo \"文件已修改，建议检查一下改了什么\""
        }
      ]
     }
   ]
  }
}

解释一下这段配置：

• permissions.allow：这些命令 AI 可以直接执行，不需要每次弹出确认框

• hooks.PostToolUse：当 AI 使用 Write 或 Edit 工具修改文件后，自动执行提醒命令

提示：Hook 可以做很多事——自动运行 Prettier 格式化代码、自动运行 ESLint 检查、甚至自动提交 Git。但初期不建议配置太多，够用就好。

权限模式：控制 AI 的"自由度"

Claude Code 有三种权限模式，针对不同的场景：

模式	行为	适用场景
Safe（安全）	所有危险操作都需要确认	新手阶段，不想让 AI 乱动文件
Approve（审批）	大部分操作要确认	日常开发，看到关键操作再放行
Edit（编辑）	AI 自主操作	信任 AI，不想频繁点确认

注意：建议初期使用 Approve 模式。当 AI 要执行 rm -rf、git push --force 等危险操作时，它会强制要求确认——这是保护你的最后一道防线。


Memory 系统：让 AI 记住你的偏好

Memory 是 Claude Code 的持久化记忆系统。你可以让 AI 记住：

• 你的技术偏好："我喜欢用 TypeScript 严格模式"

• 项目约定："这个项目用 TailwindCSS，不要写 CSS 文件"

• 你踩过的坑："上次用 Prisma 7 有兼容问题，这次用 Prisma 5"

在任何对话中，直接告诉 AI：

请记住：我所有的项目都用 TypeScript 严格模式，UI 文案用中文，代码注释用中文。

AI 会把这条信息存到持久化记忆中，以后的对话都会自动读取。

验证：后续对话中问 AI "我们之前约定过编码规范吗？"——AI 会从 Memory 中检索并回答你。

这套配置是活的

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

• CLAUDE.md 是活的：Claude 每犯一次错就加一条。记住这句话："更新 CLAUDE.md，让这件事不再发生"

• settings.json 跟着项目长大：新工具来了加 allow，发现新的危险操作加 deny

• Skills 长出自己的版本：/review 里加你代码库特有的常见问题，/commit 里写团队的 scope 命名规范

• .gitignore 持续更新：每用一个新工具，看它会不会在本地生成配置文件

Claude使用模式

三种运行模式

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

模式	行为	适合场景	状态栏提示
Normal（默认）	每次文件修改、命令执行都要你确认	默认、小任务、需要逐步审查	无特殊标记
Auto-Accept（自动接受）	不再询问，直接执行	已计划好的批量任务、可信操作	accept edits on
Plan Mode（规划模式）	全面只读，只能分析、提问、出方案	复杂任务、不熟悉的代码库、架构决策	plan mode on

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

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

工具	作用
Read	查看文件内容
Glob	按 pattern 查找文件
Grep	用正则在文件内容中搜索
LS	列出目录内容
WebSearch / WebFetch	联网查资料
Task	启动只读子代理去调研
AskUserQuestion	向你提交选项题以澄清需求

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

提示：Plan Mode 的重点是先探索和规划，暂不修改文件。不同版本可能会用不同的内部检索或子任务机制来辅助调研，不建议把某个内部实现细节当成稳定接口来记。

四种进入 Plan Mode 的方式

graph TB
   subgraph Methods["进入 Plan Mode 的 4 种方式"]
      direction TB
      M1["① 快捷键：Shift+Tab ×2<br/>（Windows 某些终端用 Alt+M）"]
      M2["② 斜杠命令：/plan<br/>（Claude Code v2.1.0+）"]
      M3["③ 启动参数：claude --permission-mode plan"]
      M4["④ 默认配置：.claude/settings.json<br/>permissions.defaultMode = 'plan'"]
   end

图：进入 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

注意： Windows 用户注意：某些 Windows 终端（如部分 PowerShell 配置）上 Shift+Tab 只能在 Normal/Auto-Accept 间切换，跳过了 Plan Mode。请改用 Alt + M 切入 Plan Mode；该问题在官方 Issue 中已标记为已知问题。

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

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

> /plan

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

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

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

claude --permission-mode plan


claude --permission-mode plan -p "分析认证模块并提出优化建议"

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

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

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

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

Skills 介绍

Skill的定义

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

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

Skill vs 单次 Prompt：

维度	单次 Prompt	Skill
性质	一次性指令	可复用的标准流程
一致性	每次输出可能不同	每次按照同样的标准执行
效率	每次重新写一遍	一键触发
维护	用完即弃	可版本管理、持续优化
比喻	口头交代任务	书面的标准操作手册（SOP）

Skill的核心价值

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

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        # 依赖声明（可选，列出脚本需要的第三方包）

提示：Skill 的核心是 SKILL.md，其余文件均为辅助。如果你的 Skill 只需要一份指令说明，只放一个 SKILL.md 就够了。但当 Skill 涉及复杂逻辑（如数据处理、格式转换）时，配上 scripts/、resources/ 和 references/ 会大幅提升 Skill 的能力和可维护性。

各组成部分详解：

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

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

---

name: react-component-generator   # 技能名称（唯一标识）
version: 1.0                  # 技能版本
description: 根据需求生成符合项目规范的 React 组件文件集  # 技能简介
trigger: ["创建组件", "新建React组件", "生成组件"]      # 触发关键词
tools: ["typescript", "react"]    # 依赖工具
author: your-name              # 技能作者
---



## 执行步骤
1. 确认组件名称和功能需求
2. 在 src/components/{componentName}/ 目录下创建文件
3. 按照 resources/template/ 中的模板生成代码
4. 运行 scripts/validate.js 验证组件结构

## 输出规范
- 所有文件创建完成后，报告创建的文件列表
- 给出组件的使用示例代码

## 错误处理
- 如果目录已存在，提示用户确认是否覆盖
- 如果缺少依赖包，提示安装命令

## 示例
给一个完整的输入→输出示例。

注意：Frontmatter（元数据）是可选的，很多简单的 Skill 可以省略它。但如果你的 Skill 需要被 Agent 系统自动发现和匹配，Frontmatter 中的 trigger 和 description 就非常重要 —— Agent 启动时只读取元数据，只有当用户任务匹配触发条件时，才会加载完整指令。这种"渐进式披露"的设计可以节省上下文窗口空间。

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

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

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 的决策记录）

提示：references/ 和 resources/ 的区别可以这样理解 —— resources/ 是"生产材料"（模板、配置，直接用于生成输出），references/ 是"参考书"（规范、标准、文档，用于指导 AI 做出正确决策）。

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

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

pandas>=2.0.0
openpyxl>=3.1.0

简单 vs 完整 Skill 的选择：

场景	推荐结构	说明
简单的编码规范	只需 SKILL.md	如 Git 提交规范、命名约定
代码生成类	SKILL.md + resources/template/	模板驱动，保证生成代码的一致性
数据处理类	SKILL.md + scripts/ + resources/config/	复杂逻辑封装到脚本，配置外部化
质量审查类	SKILL.md + references/	参考文档驱动，确保审查有据可依
完整工程流程	全套目录	如项目初始化、CI/CD 配置等复杂流程

Skill的类型分类

类型	描述	示例
代码生成类	按模板生成代码	React组件生成器、API端点生成器
工程流程类	执行标准化流程	项目初始化、CI/CD配置
质量保障类	代码审查与测试	安全审计Skill、代码审查Skill
文档生成类	自动生成文档	API文档生成、变更日志生成
调试修复类	排查和修复问题	错误诊断Skill、性能调优Skill

---

官方与社区 Skill 资源

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

Anthropic 官方 Skill 库

仓库地址：https://github.com/anthropics/skills

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

"Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks." （Skill 是由指令、脚本和资源组成的文件夹，Claude 会动态加载它们以提升在专业任务上的表现。）

官方 Skill 分类总览：

类别	Skill 示例	说明
文档处理	docx、pdf、pptx、xlsx	生成和处理 Office 文档、PDF，生产级质量
创意设计	algorithmic-art、canvas-design、slack-gif-creator	生成算法艺术、设计画布、动图
开发技术	frontend-design、mcp-builder、webapp-testing、artifacts-builder	前端设计、MCP Server 生成、Web 应用测试
企业沟通	brand-guidelines、internal-comms	品牌规范、内部沟通模板
工具	skill-creator	用 AI 创建新 Skill 的 Skill（"元技能"）

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

$ npx skills add anthropics/skills -g


$ npx skills add anthropics/skills@frontend-design -g
$ npx skills add anthropics/skills@mcp-builder -g
$ npx skills add anthropics/skills@skill-creator -g

提示：skill-creator 是一个非常有趣的"元技能" —— 它的功能是帮你创建新的 Skill。如果你刚开始学习 Skill 编写，可以先安装它，然后告诉 AI"帮我创建一个 XXX Skill"，它会按照标准规范帮你生成 SKILL.md 和目录结构。

手动安装（不使用 CLI）：

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

$ git clone https://github.com/anthropics/skills.git


$ cp -r skills/skills/frontend-design .claude/skills/

Vercel 官方 Skill 库

仓库地址：https://github.com/vercel-labs/skills

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

Vercel Skill 分类：

类别	覆盖内容
React / Next.js	React 最佳实践、Next.js App Router、性能优化
AI SDK	Vercel AI SDK 集成、AI 应用开发
设计与 UI	无障碍设计、高性能 UI 组件
浏览器自动化	浏览器交互自动化测试
部署	Vercel 平台部署流程
商业	电商和支付体验
工作流	持久化、弹性工作流
通用工具	find-skills（搜索发现新 Skill）

安装方式：

$ npx skills add vercel-labs/skills -g


$ npx skills add vercel-labs/skills@find-skills -g -y

提示：find-skills 是一个"技能发现者" Skill —— 当你需要完成某个任务但不知道有没有现成的 Skill 时，它会自动帮你搜索并推荐最合适的 Skill。强烈建议首先安装它。

Vercel Skill 的"包管理器"

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

基本用法：

$ npx skills find "react testing"


$ npx skills add <owner/repo>        # 安装仓库中的全部 Skill
$ npx skills add <owner/repo>@<name>   # 安装指定 Skill
$ npx skills add <owner/repo> -g      # 全局安装（所有项目可用）


$ npx skills list


$ npx skills init

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

Skill 库

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

精选 GitHub 仓库：

仓库	Skill 数量	特色
ComposioHQ/awesome-claude-skills	127+	10大分类，含59个SaaS应用集成Skill
alirezarezvani/claude-skills	235+	9大领域，含25个POWERFUL级高级Skill
travisvn/awesome-claude-skills	持续更新	精选列表，社区投票排名
glebis/claude-skills	专项	专注特定工作流的高质量Skill

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	说明
字节跳动/火山引擎	GitHub: bytedance/agentkit-samples	联网搜索、文本转语音（TTS）、图像理解	基于火山引擎 API，企业级 AgentKit 示例
科大讯飞	GitHub: iflytek/iFly-Skills	语音合成（TTS）、语音转写、PDF/图片OCR、发票OCR、机器翻译、文本校对	讯飞 AI 能力的 Skill 封装，语音和 OCR 最强
科大讯飞	GitHub: iflytek/skillhub	企业级 Skill 注册中心	私有部署的 Skill 商店，支持团队协作管理
阿里巴巴/通义灵码	通义灵码内置	代码审查、日志分析、API 文档生成	支持 SKILL.md 格式，可在 ~/.lingma/skills/ 自定义
腾讯/CodeBuddy	CodeBuddy Agent 平台	自定义 Skill 构建	支持 Skill 创建和集成，与腾讯云生态打通

安装国内大厂 Skill 示例：

$ git clone https://github.com/iflytek/iFly-Skills.git
$ cp -r iFly-Skills/ifly-pdf-image-ocr .claude/skills/



$ git clone https://github.com/bytedance/agentkit-samples.git
$ cp -r agentkit-samples/skills/byted-web-search .claude/skills/

提示：国内大厂的 Skill 大多基于各自的云服务 API，使用前需要注册对应平台并获取 API Key。但它们在中文处理、语音识别、OCR 等方面的能力远超海外同类 Skill，非常适合国内开发者。

聚合平台

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

平台	地址	Skill 数量	特色
skills.sh	https://skills.sh	48,000+	Vercel 官方推荐的发现平台
SkillsMP	https://skillsmp.com/zh	900,000+	最大的 Skill 市场，支持中文界面
AgentSkills.io	https://agentskills.io	开放标准	Agent Skills 开放标准定义

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

提示：SkillsMP 从 GitHub 上自动索引包含 SKILL.md 的仓库，所以你在 GitHub 上发布的 Skill 也可能被收录进去。

规则库

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

资源	地址	说明
cursor.directory	https://cursor.directory/	按技术栈分类的规则模板集合
cursorrules.org	https://cursorrules.org/	可参考旧版规则写法，再迁移到 .cursor/rules/*.mdc
awesome-cursorrules	GitHub: PatrickJS/awesome-cursorrules	社区精选规则合集

使用第三方 Skill 的安全评估

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

维度	检查项	举例
安全性	是否包含危险命令？是否会泄露敏感信息？	检查有无 rm -rf、curl 发送数据到外部
维护状态	最近更新时间？作者是否活跃？	超过6个月未更新的慎用
文档完整性	SKILL.md 是否清晰？有无使用说明和示例？	缺少文档的 Skill 质量可能不高
兼容性	是否与你使用的工具版本兼容？	检查 Frontmatter 中的 tools 字段
来源可信度	是官方/知名组织还是个人？Star 数？	优先选用官方库和高 Star 仓库

安全检查的最佳实践：

注意：永远不要盲目使用来历不明的 Skill。安装前至少通读一遍 SKILL.md 的内容和 scripts/ 目录中的脚本代码，确保没有危险操作。官方库（Anthropic、Vercel）优先，社区高 Star 仓库其次，个人仓库最后。

经典 Skill 实操体验

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

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

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

$ 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  # 周报模板

提示：skill-creator 会交互式地询问你一些问题（技能名称、触发词、执行步骤等），然后生成符合规范的 SKILL.md。初学者强烈建议先用 skill-creator 生成 Skill，再根据需要手动调整，比从零开始写效率高得多。

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

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

$ npx skills add anthropics/skills@pdf -g

安装后即可直接使用：

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

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

提示：同类的官方文档处理 Skill 还有 docx（Word 文档）、xlsx（Excel 表格）、pptx（PowerPoint 演示文稿）。它们的工作方式类似 —— 把文档格式（本质是 ZIP + XML）"翻译"成 Claude 能理解的结构，然后进行处理。

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

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

$ npx skills add anthropics/skills@frontend-design -g

使用示例：

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

---

构建自己的 Skill

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

识别 Skill 化的机会

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

• 你是否经常给AI写类似的Prompt？→ 把它变成Skill

• 你的项目是否有固定的开发模式？→ 把它变成Skill

• 你是否有标准化的审查流程？→ 把它变成Skill

提示：DRY原则（Don't Repeat Yourself）不仅适用于代码，也适用于Prompt。如果你发现自己连续3次写了类似的Prompt，就是时候把它Skill化了。

创建一个 React 组件生成 Skill

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

Step 1：创建 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-generator
version: 1.0
description: 根据组件名称和功能描述，生成符合项目规范的 React 组件文件集
trigger: ["创建组件", "新建React组件", "生成组件"]
tools: ["typescript", "react", "tailwindcss"]
author: your-name
---



## 触发条件
当用户要求创建新的 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>
  );
}

提示：resources/template/ 中的模板文件不是让 AI 原样复制的，而是给 AI 一个"参考样式"。AI 会根据模板的结构和风格，结合用户需求生成实际代码。这比纯文字描述更直观，生成质量也更高。

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 结构验证通过


创建一个 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-generator
version: 1.0
description: 为指定的数据模型生成标准的 CRUD API 端点
trigger: ["创建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
   }
  }
}

提示：把 API 的返回格式定义抽到 resources/config/ 中，好处是 SKILL.md 更简洁，而且修改格式时只需改 JSON 文件，不用动 Skill 指令。

创建一个 Git 规范化 Skill

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

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

---
name: git-commit-standard
version: 1.0
description: 在提交代码时，自动生成符合 Conventional Commits 规范的 commit message
trigger: ["提交代码", "git commit", "生成commit"]
---



## 执行步骤

1. 运行 `git diff --staged` 查看暂存区的修改
2. 分析修改内容，判断变更类型：
   - feat: 新功能
   - fix: 修复Bug
   - refactor: 重构（不改变功能）
   - style: 样式修改
   - docs: 文档更新
   - test: 测试相关
   - chore: 构建/工具变更

3. 生成 commit message，格式：
   ```
   <type>(<scope>): <description>

   <body>
   ```cpp

4. 显示给用户确认后执行 `git commit`

## 示例
修改了 src/components/BookmarkCard.tsx 中的样式

生成的 message：
​```
style(BookmarkCard): 优化书签卡片的响应式布局

- 调整了移动端下的卡片宽度
- 修复了标签溢出问题
​```cpp

提示：注意对比三个实战 Skill 的复杂度递减关系 —— React 组件 Skill（完整包：SKILL.md + scripts + resources）→ API 端点 Skill（中等：SKILL.md + resources/config）→ Git 提交 Skill（最简：仅 SKILL.md）。根据实际需求选择合适的结构，不必过度设计。

创建一个代码安全审计 Skill

前面三个案例分别展示了 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-audit
version: 1.0
description: 对指定代码进行安全审计，依据 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：

## 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），禁止直接写 SQL
3. 所有用户输入必须在服务端验证，不能只依赖前端验证
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/ 中的示例格式输出审计报告。

提示：注意 references/ 的价值 —— 如果不提供参考文档，AI 会按照自己的通用知识来审计，可能遗漏团队特有的安全要求。有了 references/，审计标准就变得确定、可控、可迭代 —— 团队安全规范更新了？改一下 references/team-security-standards.md 就行。

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

案例	核心组件	教学重点
React 组件 Skill	SKILL.md + scripts/ + resources/template/	完整包：脚本验证 + 模板驱动
API 端点 Skill	SKILL.md + resources/config/	配置外部化
Git 提交 Skill	仅 SKILL.md	最简结构
安全审计 Skill	SKILL.md + references/ + resources/examples/	参考文档驱动审查

创建自定义 Skill：api-crud-generator （代码生成）

在电商项目中，你会反复做同样的事情：

商品需要 CRUD → 写 Prisma 查询 + API Route + 管理页面
分类需要 CRUD → 写 Prisma 查询 + API Route + 管理页面
订单需要 CRUD → 写 Prisma 查询 + API Route + 管理页面

每次都是相似的代码结构，只是换了个模型名。如果每次都让 AI 从零写，不仅慢，而且每次的代码风格可能不一致。

Skill 就是解决这个问题的——把重复的模式封装成可复用的"标准操作流程"。

Skill 的目录结构

一个完整的 Skill 是一个目录，推荐放在 .claude/skills/ 下：

.claude/skills/api-crud-generator/
├── SKILL.md           ← 核心：技能描述文件（必选）
├── scripts/           ← 辅助脚本（可选）
├── resources/         ← 模板和配置（可选）
└── references/         ← 参考文档（可选）

编写 SKILL.md

创建 .claude/skills/api-crud-generator/SKILL.md：

---
name: api-crud-generator
version: 1.0
description: 根据 Prisma 模型生成标准的 Next.js API Route + 前端管理页面
trigger: ["生成CRUD", "生成接口", "生成管理页面"]
---



## 功能说明
根据指定的 Prisma 模型，自动生成标准的管理后台 CRUD 代码：
1. API Routes（5 个）：GET 列表、GET 详情、POST 创建、PUT 更新、DELETE 删除
2. 前端页面：数据列表页、创建/编辑表单

## 执行步骤

### 第 1 步：确认模型信息
询问用户：
- 要生成的模型名称（如 Product、Category）
- API 路径（如 /api/admin/products）
- 页面路由（如 /admin/products）

### 第 2 步：生成 API Route Handlers
按照标准模板生成以下文件：
1. `route.ts` — GET 列表 + POST 创建
2. `[id]/route.ts` — GET 详情 + PUT 更新 + DELETE 删除

### 第 3 步：生成前端管理页面
生成一个包含以下功能的管理页面：
- 数据表格（列出所有字段）
- "新增"按钮 + 表单
- 每行的"编辑"和"删除"按钮
- TailwindCSS 样式

### 第 4 步：确认并验证
- 列出所有生成的文件
- 提醒用户执行 npx prisma generate（如果模型有变更）
- 给出测试方法

## 注意事项
- 所有 UI 文案使用中文
- 使用 Next.js App Router 的 params 语法
- 创建和更新前做输入验证
- 密码字段永远不通过 API 返回

SKILL.md 的结构解析

每个 Skill 文件包含两部分：

1. Frontmatter（文件头部的 YAML 元数据）

---
name: 技能唯一名称
description: 一句话描述
trigger: 触发关键词列表
---

• name：技能的唯一标识

• description：帮助 AI 判断什么时候该用这个技能

• trigger：当用户消息包含这些关键词时，AI 知道要加载这个 Skill

2. 正文（Markdown 格式的指令）

这是 AI 执行任务时会阅读的"操作手册"。写得好坏直接决定 AI 的输出质量。

提示：写 Skill 时想象你在给一个聪明的实习生写工作说明书——告诉他做什么、用什么工具、注意什么坑。

在开发中使用 Skill

创建好 Skill 后，在 Claude Code 对话中，你只需要这样说：

请用 api-crud-generator Skill 为 Category 模型生成管理后台代码。
API 路径放在 /api/admin/categories，页面放在 /admin/categories。

AI 会：

1. 自动加载 SKILL.md 中的指令
2. 按照步骤 1-4 的标准流程执行
3. 生成符合项目规范的代码

这就是 Skill 的威力——一次编写，反复使用，标准统一。

Skill 与 AI 工具的集成

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

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

---

Skill 的迭代与版本管理

持续优化

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

• AI 哪些地方做得好？→ 保持

• AI 哪些地方做得不好？→ 在 Skill 中加入更明确的指令

• 有没有遗漏的边界情况？→ 补充到错误处理部分

版本管理

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

$ git add .claude/skills/react-component/
$ git commit -m "feat(skills): 新增 React 组件生成 Skill v1.0"


$ git add .claude/skills/react-component/SKILL.md
$ git commit -m "chore(skills): 升级 React 组件 Skill 至 v1.1，优化模板"

Superpowers 插件

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

什么是 Superpowers？

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

安装前后对比：

没装 Superpowers	装了 Superpowers
你：“加个批量导出功能”	你：“加个批量导出功能”
AI：“好的，我来实现...”（直接写代码）	AI：“在开始前我需要确认：1.导出格式？2.数据量多大？3.需要异步吗？”→给出 2-3 个方案，确认后再动手

核心 Skills 一览

Skill	功能	触发时机
头脑风暴 (brainstorming)	需求分析→设计规格，先想清楚再动手	新需求/新功能开始时
编写计划 (writing-plans)	把规格拆成可执行的实施步骤	确认设计后
执行计划 (executing-plans)	按计划逐步实施，每步验证	开发过程中
测试驱动开发 (TDD)	严格 TDD：先写测试，再写代码	开发核心逻辑时
系统化调试 (debugging)	四阶段调试法：定位→分析→假设→修复	遇到 Bug 时
代码审查 (code-review)	派遣审查 agent 检查代码质量	功能完成后
完成前验证 (verification)	声称完成前必须跑验证	任务结束前

安装方法

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

$ cd /your/project


$ npx superpowers


$ npx superpowers-zh

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

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

git clone https://github.com/jnMetaCode/superpowers-zh.git


cp -r superpowers-zh/skills /your/project/.claude/skills

注意：手动安装只复制了 Skills 文件，不会配置自动触发钩子。推荐使用 npx 方式一键安装。

是否必须安装？

不是必须的。 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仅对当前项目生效

Claude Code MCP

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。

提示：MCP 是一个进阶主题。初学者可以先专注于 Skill 的编写和使用，等熟练后再探索 MCP 扩展。

附录

附录A：常用命令速查表

Claude Code 命令速查

命令	功能
claude	启动交互式会话
claude --model <model>	使用指定模型启动
claude -p "prompt"	单次执行模式
/help	显示帮助
/model	查看/切换模型
/compact	压缩上下文
/clear	清空对话
/memory	管理记忆
/cost	查看费用
/review	代码审查，每次提交代码都可以调用一
/init	初始化CLAUDE.md
Ctrl+C	中断操作
Esc	取消生成

Git 命令速查

命令	功能
git init	初始化仓库
git status	查看状态
git add .	暂存所有修改
git commit -m "msg"	提交
git push	推送到远程
git pull	拉取远程更新
git checkout .	撤销所有未提交的修改
git log --oneline	查看提交历史
git diff	查看修改内容

npm 命令速查

命令	功能
npm init -y	初始化项目
npm install <包名>	安装依赖
npm install -g <包名>	全局安装
npm run dev	启动开发服务器
npm run build	构建项目
npm test	运行测试

终端基础命令速查

命令	功能	Windows 替代
pwd	查看当前目录	pwd (PowerShell)
ls	列出文件	dir
cd <路径>	切换目录	同左
mkdir <名称>	创建目录	同左
clear	清屏	cls

---

附录B：Prompt 模板库

项目初始化模板

我要创建一个 [项目类型] 项目。

项目名称：[名称]
简述：[一句话描述]
技术栈：[前端框架] + [后端框架] + [数据库]

核心功能（MVP）：
1. [功能1]
2. [功能2]
3. [功能3]

请先创建项目结构和基础配置文件，暂不实现具体功能。

功能实现模板

请在 [指定目录/文件] 中实现 [功能名称]。

具体需求：
1. [需求点1]
2. [需求点2]
3. [需求点3]

技术约束：
- 参考 [已有文件/模块] 的风格
- 使用 [指定技术/库]
- 返回格式遵循 [项目约定的格式]

请先说明实现计划，确认后再开始编码。

Bug 修复模板

发现一个Bug，需要修复：

现象：[实际看到的行为]
期望：[应该是什么行为]
复现步骤：
1. [步骤1]
2. [步骤2]

错误信息：
[粘贴完整的错误堆栈]

我已经尝试过：[你尝试的解决方案]

请定位问题原因并修复。

代码审查模板

请对 [文件路径或范围] 进行代码审查。

审查重点：
1. 安全性（输入验证、XSS防护、SQL注入）
2. 错误处理（异常是否被正确捕获和处理）
3. 性能（是否有明显的性能问题）
4. 代码质量（可读性、命名规范、重复代码）

请按严重程度分级：Critical / Warning / Info
并给出具体的修复建议。

架构设计模板

我需要设计一个 [系统/功能] 的架构。

业务需求：[描述]
性能要求：[QPS/响应时间/并发用户数]
技术约束：[必须使用的技术/限制条件]

请给出：
1. 系统架构图（文字描述即可）
2. 技术选型建议及理由
3. 数据模型设计
4. API 接口设计
5. 潜在的技术风险和应对方案

---

附录C：常见问题排查指南（FAQ 汇总）

类别	问题	解决方案
安装	npm install -g 报权限错误	macOS: 前加 sudo；Windows: 管理员运行
安装	下载超时	设置npm镜像: npm config set registry https://registry.npmmirror.com
安装	claude: command not found	检查npm全局路径是否在PATH中: npm config get prefix
连接	Invalid API Key (401)	检查Key是否完整复制，环境变量是否正确设置
连接	网络超时	国内用户使用中转服务或国产模型
连接	Rate limit exceeded	等待1分钟后重试，或升级API套餐
使用	AI修改了不该改的文件	Prompt中明确指定文件范围，或用 git checkout . 回退
使用	AI陷入修复循环	git checkout . 回退 + /clear 清空对话 + 重新描述需求
使用	对话太长AI遗忘	使用 /compact 压缩上下文
使用	AI推荐不存在的npm包	先到 npmjs.com 搜索确认包是否存在
费用	不确定花了多少钱	使用 /cost 查看当前会话费用
费用	想控制费用	简单任务用 Haiku/DeepSeek；设置月度预算
项目	数据库报错	运行 npx prisma db push 同步数据库
项目	端口被占用	杀掉占用端口的进程，或在命令中指定其他端口
部署	Vercel构建失败	检查构建日志中的错误信息，通常是依赖问题

---

附录E：术语表

英文术语	中文释义	简要说明
AI-Assisted Programming	AI辅助编程	使用AI工具帮助编写代码
Agent	智能体	能自主执行任务的AI系统
Agentic Engineering	智能体工程化	系统化的AI驱动开发方法论
API	应用程序接口	程序之间通信的规则
API Key	API密钥	访问AI服务的身份凭证
CLI	命令行界面	通过文字命令操作电脑
Context Window	上下文窗口	AI一次能处理的最大内容量
CRUD	增删改查	Create/Read/Update/Delete
Hallucination	幻觉	AI编造不存在的信息
IDE	集成开发环境	编写代码的专业软件
LLM	大语言模型	如Claude、GPT等AI模型
MCP	模型上下文协议	AI工具的扩展能力标准
MVP	最小可行产品	只包含核心功能的第一个版本
ORM	对象关系映射	用代码操作数据库的工具（如Prisma）
PRD	产品需求文档	描述产品"做什么"的文档
Prompt	提示词	给AI的指令/问题
RAG	检索增强生成	结合搜索和AI生成的技术
SDD	规范驱动开发	先写规范再让AI执行的方法
Skill	技能	封装的可复用AI指令集
SPEC	技术规范	描述产品"怎么做"的文档
Token	令牌	AI处理文本的基本单位
Vibe Coding	氛围编程	凭感觉和意图驱动的AI编程方式

---

结语

请记住五个核心原则：

1. 动手大于阅读 —— 学到的知识必须通过实践才能变成技能
2. 项目驱动学习 —— 带着目标去学，效率最高
3. 拥抱错误 —— AI会犯错，你也会，但每次错误都是学习
4. 持续迭代 —— 先做出来，再做好，没有一步到位的完美
5. 记录与分享 —— 把经验写下来，分享出去，帮助他人也巩固自己

AI编程领域发展极快，保持学习的节奏，关注新工具和新技术。

祝你在AI编程的世界里，创造出令自己骄傲的作品！

输入辅助密码即可