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

学习目标：掌握 Skill 系统的使用与创建，构建个人AI效率工具箱

完成标志：能创建自定义 Skill 并集成到 Claude Code 中使用

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

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

4.1 什么是AI技能（Skill）

4.1.1 Skill 的定义

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

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

Skill vs 单次 Prompt：

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

4.1.2 Skill 的核心价值

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

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

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

各组成部分详解：

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 验证组件结构

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

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

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

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

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

提示：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 配置等复杂流程

4.1.4 Skill 的类型分类

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

---

4.2 官方与社区 Skill 资源

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

4.2.1 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）：

# 安装 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

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

手动安装（不使用 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 库

仓库地址：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）

安装方式：

# 安装 Vercel 全部 Skill
$ npx skills add vercel-labs/skills -g

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

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

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 仓库：

仓库	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 示例：

# 科大讯飞 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

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

4.2.5 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 也可能被收录进去。

4.2.6 Cursor 规则库

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	社区精选规则合集

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

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

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

安全检查的最佳实践：

# 1. 安装前先浏览 Skill 内容（不要盲目安装）
# 在 GitHub 上直接阅读 SKILL.md

# 2. 检查 scripts/ 目录中的脚本（如果有的话）
# 确保没有网络请求、文件删除等危险操作

# 3. 在测试项目中先试用，确认安全后再用于正式项目

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

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

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

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

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

# 安装 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。

---

4.3 构建自己的 Skill

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

4.3.1 识别 Skill 化的机会

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

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

提示：DRY原则（Don't Repeat Yourself）不仅适用于代码，也适用于Prompt。如果你发现自己连续3次写了类似的Prompt，就是时候把它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-generator
version: 1.0
description: 根据组件名称和功能描述，生成符合项目规范的 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>
  );
}

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

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-generator
version: 1.0
description: 为指定的数据模型生成标准的 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
   }
  }
}

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

4.3.4 实战：创建一个 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"]
---

# 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): 优化书签卡片的响应式布局

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

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

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-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：

# 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），禁止直接写 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/	参考文档驱动审查

---

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 可以在合适的任务中调用这些方法论。

安装前后对比：

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

4.6.2 核心 Skills 一览

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

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

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

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。

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

---

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-standard
version: 1.0
description: 在提交代码时，自动生成符合 Conventional Commits 规范的 commit message
trigger: ["提交代码", "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 步：实际使用

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

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

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

验证：如果 Claude Code 自动读取了你的 Skill、分析了 git diff、并生成了符合 Conventional Commits 格式的 commit message，说明你的 Skill 创建成功！

第 5 步：用 Git 提交你的 Skill

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

提示：将 Skill 目录提交到 Git 仓库后，团队其他成员 pull 代码后也能使用这个 Skill。这就是 Skill 的共享价值。

4.8.2 进阶挑战（选做）

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

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

验证：如果你能独立创建一个 Skill 并在 Claude Code 中成功触发使用，恭喜完成第四部分！

---

第五部分：完整项目案例实操

学习目标：通过从零到一的完整项目开发，掌握AI编程的全流程

完成标志：独立使用 Claude Code 完成一个可运行的全栈项目

前面部分讲完了理论知识，这一部分动手做个项目：

一个完整可运行的微型商城——覆盖商品、用户、购物车、订单、后台管理全模块

提示：本章的每个步骤都包含完整的 Prompt（可直接复制使用）和验证方法。你可以一边阅读一边跟做。

跟做的 6 条经验

1. 把 Claude Code 当同事用 — 直接描述你想干什么，不用纠结措辞。越具体越好。
2. 多用 /plan 模式 — 复杂任务先让它出方案，你审核后再动手，避免返工。
3. 小步快跑 — 一个任务一个任务来，别一口气提太多需求。
4. 善用 CLAUDE.md — 放在项目根目录，cc 会自动读取，理解你的项目规范。
5. 创建任务列表 — 多步骤任务告诉它"创建任务列表"，cc 会跟踪进度不遗漏。
6. 反馈很重要 — 它做错了就说，它会记下来以后改进。

5.0 项目：微型商城（Mini Mall）—— 完整演示 Claude Code 13 项核心功能

这是一个完整的全栈电商项目，也是本教程的核心案例。你将在这个项目中从零构建一个可部署的 Web 应用，并依次体验 /plan、CLAUDE.md、Hook、Memory、Skill、/review、/security-review、多模型切换等 Claude Code 全部核心功能。

5.0.1 本章概述

在项目一中，你学会了用 Claude Code 做一个带 Web 界面的记账工具——那只是热身。本项目将带你从零构建一个真正可部署到互联网的 Web 应用：一个微型商城。

更重要的是，本项目将全程演示 Claude Code 的 13 项核心功能。你不只是学会做一个商城，你还将学会如何把 Claude Code 用到极致。

5.0.2 你将学到的 Claude Code 核心功能

#	功能	是什么	什么时候用
1	/plan	让 AI 先出方案，人审核后再动手	任何复杂任务开始前
2	/init + CLAUDE.md	自动生成项目规范文档	项目搭好后，让 AI 理解你的规范
3	Task 任务列表	把大任务拆成小步骤，逐个跟踪	多步骤任务时告诉 AI "创建任务列表"
4	自定义 Skill	把重复性工作封装成可复用的"操作手册"	相同的模式要重复做多次时
5	官方 Skill	使用社区维护的高质量技能	需要前端设计、文档生成等专业能力时
6	Hook 配置	让 AI 在特定操作前后自动执行命令	每次改完代码想自动格式化时
7	Memory 系统	让 AI 记住你的偏好，越用越懂你	你的技术偏好、项目约定
8	/review	让 AI 审查代码质量	每完成一个功能模块后
9	/security-review	安全检查：密码、认证、漏洞	认证模块完成 + 上线前
10	多模型切换	简单任务用便宜模型，复杂任务用强模型	省钱 + 提效
11	权限模式	控制 AI 的操作权限	保护你的代码不被意外修改
12	Git 工作流	版本控制，随时能"后悔"	每个功能完成后提交一次
13	环境变量管理	API 密钥、数据库连接等敏感信息	任何需要连接外部服务的项目

5.0.3 我们要做什么

一个微型电商网站，包含：

买家视角：浏览商品 → 搜索筛选 → 查看详情 → 注册登录 → 加入购物车 → 下单 → 模拟支付 → 查看订单
管理员视角：商品管理（增删改查）→ 订单管理（状态流转）→ 分类管理

5.0.4 技术栈说明

层面	选型	为什么选它
框架	Next.js 16	前后端一体化，一个项目搞定全部
语言	TypeScript	类型安全，AI 写代码时能自动发现低级错误
数据库	SQLite + Prisma 5	SQLite 零配置，Prisma 让数据库操作像写作文一样直观
样式	TailwindCSS 4	无需写 CSS 文件，直接在标签上加样式类名
认证	自制 Cookie Session	比第三方库更透明，能看到认证的每一步

提示： 为什么不用 MySQL/PostgreSQL？ SQLite 是一个单文件数据库，不需要安装数据库服务器，开箱即用。对于学习阶段和原型项目，它是完美的选择。如果将来需要迁移到 PostgreSQL，只需要改一行配置。

---

5.1 项目启动：用 /plan 做架构设计

本节目标：学会用 /plan 模式让 AI 在动手前先出方案

演示的 Claude Code 功能：/plan 模式、AskUserQuestion

5.1.1 什么是 /plan 模式，为什么重要

新手最容易犯的错误是：上来就让 AI 写代码。结果往往是 AI 写了一堆，方向偏了，又要重来。

/plan 模式的思路是先想清楚再动手：

你说"我要做什么"
  → AI 探索代码库、理解现状
  → AI 出一个详细方案
  → 你审核，确认方向正确
  → AI 按方案分步实施

这就像装修之前先出设计图——你不会让装修队直接开砸吧？

5.1.2 实际操作

在终端中进入项目目录后，启动 Claude Code：

$ claude

然后告诉它你的需求：

我要做一个微型电商项目，叫 Mini Mall。
技术栈用 Next.js 16 + TypeScript + Prisma 5 + SQLite + TailwindCSS 4。
功能包括：
- 商品浏览（列表、详情、搜索、分类筛选）
- 用户注册登录
- 购物车
- 下单和订单管理（模拟支付）
- 后台管理（商品CRUD、订单管理、分类管理）

请用 /plan 模式帮我做架构设计。

Claude Code 会进入 plan 模式，提出几个问题来确认你的需求（这就是 AskUserQuestion 功能），比如：

• 用什么语言？（TypeScript）
• 用什么样式方案？（TailwindCSS）
• 你是新手还是老手？（新手友好）

确认后，AI 会生成一份完整的架构方案，包括：

数据库设计：6 个表的 ER 关系图
页面路由：10 个页面的路径和权限
API 设计：18 个接口的请求/响应格式
项目目录结构：每个文件放哪里
实施步骤：按什么顺序开发

5.1.3 阅读和审核方案

AI 出的方案不是圣旨——你才是决策者。仔细看一下：

• 数据库设计合理吗？（用户-商品-购物车-订单的关系是否清晰）
• 页面路由符合预期吗？（有没有漏掉什么页面）
• 技术选型合适吗？（有没有过度设计）

确认无误后，告诉 AI "可以开始"。

验证：AI 输出了包含数据库设计、页面路由、API 列表的完整方案，你审核后表示同意。

5.1.4 你学到了什么

概念	说明
/plan 模式	先规划后编码，避免方向性返工
AskUserQuestion	AI 会主动问你不确定的问题，而不是瞎猜
架构方案	包含 ER 图、路由表、API 清单的完整设计文档

---

5.2 环境搭建：项目骨架 + CLAUDE.md

本节目标：创建 Next.js 项目，生成 CLAUDE.md 让 AI 始终理解你的项目

演示的 Claude Code 功能：/init、CLAUDE.md

5.2.1 创建项目

在终端执行以下命令：

# 1. 进入工作目录
cd ~/projects

# 2. 用 create-next-app 创建项目（会自动安装依赖）
npx create-next-app@latest mini-mall --typescript --tailwind --app --src-dir

# 3. 进入项目目录
cd mini-mall

# 4. 安装额外依赖
npm install prisma @prisma/client bcryptjs
npm install -D tsx @types/bcryptjs

注意： 避坑：项目路径不要用中文，否则某些工具会出奇怪的问题。

5.2.2 初始化 Prisma（数据库 ORM）

# 初始化 Prisma，选择 SQLite 作为数据库
npx prisma init --datasource-provider sqlite

这个命令会创建 prisma/schema.prisma 文件和 .env 环境变量文件。

5.2.3 CLAUDE.md — AI 的项目"说明书"

CLAUDE.md 是 Claude Code 最核心的概念之一。它是一个放在项目根目录的 Markdown 文件，每次你和 AI 对话时，AI 都会自动读取它。

你可以把 CLAUDE.md 理解为给 AI 的"项目说明书"——里面写了：

• 用了什么技术栈
• 文件怎么组织的
• 命名规范是什么
• 有什么特殊的约定

5.2.3.1 两种方式创建 CLAUDE.md

方式一：让 AI 自动生成

在 Claude Code 对话中输入：

/init

AI 会扫描你的项目结构，自动生成一份 CLAUDE.md。

方式二：自己写（更精确）

你可以在 CLAUDE.md 中写任何你想让 AI 记住的信息。以下是我们项目的 CLAUDE.md 内容：

# Mini Mall 项目规范

## 技术栈
- 框架：Next.js 16 (App Router) + TypeScript
- 样式：TailwindCSS 4
- 数据库：SQLite + Prisma 5
- 认证：自制 Cookie Session + bcryptjs

## 目录结构
- src/app/ — 页面和 API
- src/components/ — 可复用组件
- src/lib/ — 工具函数
- prisma/ — 数据库模型

## 命名规范
- 文件名：kebab-case（如 product-card.tsx）
- 组件：PascalCase（如 ProductCard）
- 函数：camelCase（如 getProducts）

## 约定
- 所有 UI 文案和注释用中文
- 优先使用 Server Components
- API 返回 JSON，错误返回 { error: string }

提示：有了 CLAUDE.md，你不需要每次对话都重新解释项目背景。AI 会自动读取它，就像新同事入职时先看员工手册一样。

5.2.4 定义数据库模型

在 prisma/schema.prisma 中定义 6 个数据模型。以下是完整的模型定义：

// 用户
model User {
  id      Int      @id @default(autoincrement())
  name     String
  email    String    @unique
  password  String
  role     String    @default("USER")  // USER 或 ADMIN
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt
  cartItems CartItem[]
  orders   Order[]
}

// 商品分类
model Category {
  id      Int      @id @default(autoincrement())
  name    String   @unique
  slug    String   @unique      // URL 友好的英文标识
  products Product[]
}

// 商品
model Product {
  id        Int       @id @default(autoincrement())
  name      String
  description String     @default("")
  price      Float
  image      String     @default("")
  stock      Int       @default(0)
  categoryId  Int
  category   Category   @relation(fields: [categoryId], references: [id])
  createdAt   DateTime   @default(now())
  updatedAt   DateTime   @updatedAt
  cartItems   CartItem[]
  orderItems  OrderItem[]
}

// 购物车项
model CartItem {
  id      Int     @id @default(autoincrement())
  userId   Int
  productId Int
  quantity  Int     @default(1)
  user     User    @relation(fields: [userId], references: [id], onDelete: Cascade)
  product   Product  @relation(fields: [productId], references: [id], onDelete: Cascade)
  @@unique([userId, productId])  // 同一用户同一商品只允许一条记录
}

// 订单
model Order {
  id      Int       @id @default(autoincrement())
  userId   Int
  status   String     @default("PENDING")
  total    Float
  createdAt DateTime   @default(now())
  user     User      @relation(fields: [userId], references: [id])
  items    OrderItem[]
}

// 订单明细
model OrderItem {
  id        Int    @id @default(autoincrement())
  orderId    Int
  productId   Int
  productName String  // 下单时锁定商品名，防止后续改名影响历史订单
  price      Float   // 下单时锁定价格
  quantity   Int
  order      Order   @relation(fields: [orderId], references: [id], onDelete: Cascade)
  product    Product @relation(fields: [productId], references: [id])
}

然后执行迁移：

# 生成 Prisma 客户端 + 创建数据库表
npx prisma migrate dev --name init

提示：Prisma 的 migrate dev 做了三件事：1）对比 schema 和数据库；2）生成迁移 SQL 文件；3）应用到数据库。这些迁移文件可以提交到 Git，团队成员都能复现相同的数据库结构。

5.2.5 填充种子数据

空数据库没法开发。写一个种子脚本，插入 12 个商品和 2 个测试用户。

创建 prisma/seed.ts：

import { PrismaClient } from "@prisma/client";
import bcrypt from "bcryptjs";

const prisma = new PrismaClient();

async function main() {
  // 创建 5 个分类
  const categories = await Promise.all([
   prisma.category.create({ data: { name: "数码电子", slug: "digital" } }),
   prisma.category.create({ data: { name: "服装鞋帽", slug: "clothing" } }),
   prisma.category.create({ data: { name: "家居生活", slug: "home" } }),
   prisma.category.create({ data: { name: "食品饮料", slug: "food" } }),
   prisma.category.create({ data: { name: "图书教育", slug: "books" } }),
  ]);

  // 创建 12 个商品（代码略，见完整源码）
  // ...

  // 创建管理员和测试用户
  const adminPassword = await bcrypt.hash("admin123", 10);
  const userPassword = await bcrypt.hash("user123", 10);
  await prisma.user.create({
   data: { name: "管理员", email: "admin@example.com", password: adminPassword, role: "ADMIN" },
  });
  await prisma.user.create({
   data: { name: "测试用户", email: "user@example.com", password: userPassword, role: "USER" },
  });

  console.log("种子数据创建完成！");
}

main().finally(() => prisma.$disconnect());

在 package.json 中添加 seed 配置：

"prisma": {
  "seed": "tsx prisma/seed.ts"
}

执行：

npx prisma db seed

验证：终端输出 "种子数据创建完成"。数据库中已有 5 个分类、12 个商品、2 个用户。

5.2.6 你学到了什么

概念	说明
create-next-app	Next.js 官方脚手架，一键生成项目
Prisma	ORM 工具，用代码定义数据库结构
Prisma Migrate	数据库版本管理，像 Git 管理代码一样管理数据库
Seed 脚本	开发阶段用来填充测试数据
CLAUDE.md	AI 的项目说明书，每次对话自动加载

---

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

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

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

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

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

在我们的项目中，创建一个 .claude/settings.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。但初期不建议配置太多，够用就好。

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

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

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

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

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

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

• 你的技术偏好："我喜欢用 TypeScript 严格模式"
• 项目约定："这个项目用 TailwindCSS，不要写 CSS 文件"
• 你踩过的坑："上次用 Prisma 7 有兼容问题，这次用 Prisma 5"

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

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

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

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

5.3.4 你学到了什么

概念	说明
settings.json	Claude Code 的配置文件，控制权限、Hook 等
Hook	事件触发的自动命令
权限模式	Safe / Approve / Edit 三种级别
Memory	跨对话持久化的记忆系统

---

5.4 创建自定义 Skill：api-crud-generator 重点

本节目标：手把手创建你的第一个自定义 Skill，理解 Skill 的完整结构

演示的 Claude Code 功能：自定义 Skill、Skill 的四层目录结构

5.4.1 为什么要创建 Skill

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

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

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

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

5.4.2 Skill 的目录结构

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

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

对于我们这个项目，只需要 SKILL.md 就够了。

5.4.3 编写 SKILL.md

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

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

# API 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 返回

5.4.4 SKILL.md 的结构解析

每个 Skill 文件包含两部分：

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

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

• name：技能的唯一标识
• description：帮助 AI 判断什么时候该用这个技能
• trigger：当用户消息包含这些关键词时，AI 知道要加载这个 Skill

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

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

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

5.4.5 在开发中使用 Skill

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

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

AI 会：

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

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

5.4.6 你学到了什么

概念	说明
Skill 的定义	封装了特定能力的可复用指令集
Frontmatter	Skill 的元数据，AI 用来判断何时加载
SKILL.md	Skill 的核心载体
触发关键词	用户说什么话会激活这个 Skill
@ 引用	安装官方 Skill 的方式，如 anthropics/skills@frontend-design

---

5.5 商品模块开发

本节目标：完成商品的增删查改全流程，学会用 Skill 加速开发

演示的 Claude Code 功能：自定义 Skill 实战、/review、官方 Skill

5.5.1 开发思路

商品模块是最核心的模块，包含：

后端 API        前端页面
──────────      ──────────
GET /api/products    →  首页商品列表（搜索 + 分类筛选 + 分页）
GET /api/products/[id] →  商品详情页
GET /api/categories   →  顶部导航的分类标签

（管理员接口稍后在 6.8 节实现）

5.5.2 用 Prompt 驱动开发

在 Claude Code 对话中输入：

请实现商品模块的公开 API：
1. GET /api/products — 商品列表，支持 search（模糊搜索）、category（按slug筛选）、page（分页，每页9条）
2. GET /api/products/[id] — 商品详情，包含关联的分类信息
3. GET /api/categories — 分类列表，包含每个分类下的商品数量

然后实现前端页面：
1. 首页 — 商品网格展示 + 搜索框 + 分类标签切换 + 分页
2. 商品详情页 — 大图 + 名称/价格/描述/库存 + "加入购物车"按钮

要求：
- 用 Server Component 做数据获取
- 用 TailwindCSS 做样式
- UI 文案用中文
- 参考 CLAUDE.md 中的项目规范

AI 会：

1. 读取 CLAUDE.md 了解项目规范
2. 读取 Prisma schema 了解数据模型
3. 按照你的要求生成代码
4. 告诉你每个文件的用途

5.5.3 代码审查：用 /review 检查质量

每个模块开发完后，用 /review 让 AI 做一次代码审查：

/review

AI 会检查：

• 代码是否符合项目规范
• 有没有潜在的性能问题（如 N+1 查询）
• 错误处理是否完善
• 类型定义是否正确

提示：/review 类似于让一个高级工程师帮你 Code Review。它可能不会发现所有问题，但能帮你揪出大部分低级错误。

5.5.4 你学到了什么

概念	说明
Server Component	Next.js 默认的服务端组件，可以直接访问数据库
分页实现	skip + take 实现数据库级分页
关联查询	Prisma 的 include 语法加载关联数据
/review	让 AI 审查代码质量

---

5.6 用户认证模块

本节目标：实现注册登录系统，理解认证的基本原理

演示的 Claude Code 功能：/security-review、多模型切换

5.6.1 认证基础：Cookie + Session

我们用最简单也最透明的认证方案——Cookie Session：

注册：用户填邮箱+密码 → bcrypt 哈希密码 → 存入数据库
登录：验证邮箱+密码 → 生成 session token → 写入 Cookie
鉴权：每次请求读取 Cookie → 解析出用户 ID → 判断权限

提示： 为什么不直接用 next-auth？ next-auth 很强大，但它是"黑盒"——你不知道内部怎么工作的。对于教学来说，自己实现一个简易的认证系统，能看到每一步的细节，更容易理解认证的本质。学会原理后，再用 next-auth 也不迟。

5.6.2 实现认证系统

在 Claude Code 中输入：

请实现一个简易的用户认证系统：

1. 创建 src/lib/auth.ts，包含以下函数：
   - hashPassword(password) — 用 bcryptjs 哈希密码
   - verifyPassword(password, hash) — 验证密码
   - setSession(userId, role) — 把用户信息写入 httpOnly Cookie
   - getSession() — 从 Cookie 读取当前用户信息
   - getCurrentUser() — 获取当前用户的完整信息
   - clearSession() — 清除 Cookie（退出登录）

2. 实现 API：
   - POST /api/auth/register — 注册（验证邮箱唯一性，密码至少6位）
   - POST /api/auth/login — 登录（验证密码，写入session）
   - GET /api/auth/me — 获取当前用户
   - POST /api/auth/logout — 退出登录

3. 实现前端页面：
   - /login — 登录表单
   - /register — 注册表单

要求：
- 密码用 bcryptjs 哈希存储，绝不能存明文
- 登录失败时不要暴露"用户不存在"和"密码错误"的区别（防止撞库攻击）
- Session Cookie 设置 httpOnly + sameSite + secure（生产环境）

5.6.3 安全审查：用 /security-review 检查

认证模块涉及用户数据安全。让 AI 做一次安全检查：

/security-review

AI 会检查：

• 密码是否正确哈希存储（绝对不能明文）
• 有没有 SQL 注入风险（Prisma 已经帮我们预防了）
• Session Cookie 的安全属性是否正确
• 错误信息是否泄露了系统内部信息

注意：/security-review 是一个参考性检查，不能替代专业的安全审计。但它能帮你发现大部分常见的安全问题，是上线前的重要一步。

5.6.4 多模型切换实战

在这个项目中，你可以体验多模型切换的实际收益：

任务	推荐模型	理由
写用户认证逻辑	Claude Opus	安全相关，要确保万无一失
写登录页面 UI	Claude Haiku	简单表单，Haiku 足够且更快更便宜
日常功能开发	Claude Sonnet	速度和质量的最佳平衡

切换模型只需一条命令：

/model opus     ← 切换到 Opus，处理复杂逻辑
/model sonnet   ← 切回 Sonnet，日常开发
/model haiku    ← 切换到 Haiku，快速轻量任务

提示： 省钱技巧：每天开发结束时，用 /cost 查看当天的 API 费用。如果发现账单太高，下次更多用 Haiku 处理简单任务。

5.6.5 你学到了什么

概念	说明
bcrypt	密码哈希算法，即使数据库泄露，密码也无法被还原
Cookie Session	最简单的认证方案，Cookie 里存标识，服务端验证
httpOnly Cookie	JavaScript 无法读取，防止 XSS 攻击偷取 Cookie
/security-review	AI 辅助的安全检查
/model 切换	按任务复杂度选择不同级别的模型

---

5.7 购物车 + 订单模块

本节目标：实现电商的核心交易流程

演示的 Claude Code 功能：Task 任务列表、复杂业务逻辑处理

5.7.1 用 Task 管理复杂模块

购物车和订单模块涉及多个子任务。告诉 AI：

请创建任务列表，跟踪购物车和订单模块的开发进度。

AI 会帮你拆分成：

□ 购物车 API（GET、POST、PUT、DELETE）
□ 购物车页面（展示、修改数量、删除、提交订单）
□ 订单 API（GET 列表、GET 详情、POST 下单）
□ 订单页面（列表页、详情页）
□ 订单状态机（PENDING → PAID → SHIPPED → COMPLETED）

每完成一项，AI 会自动标记为完成，你随时知道进度。

5.7.2 实现购物车

在 Claude Code 中输入：

请实现购物车功能：

API：
- GET /api/cart — 获取当前用户的购物车（需登录）
- POST /api/cart — 加入购物车（productId + quantity）
  - 如果购物车已有该商品，增加数量
  - 检查库存，库存不足返回错误
- PUT /api/cart/[id] — 修改数量
- DELETE /api/cart/[id] — 删除某项

前端页面 /cart：
- 列表展示购物车商品（图片、名称、单价、数量、小计）
- 每项可以 + / - 调整数量，或删除
- 底部显示总价，"提交订单"按钮
- 未登录时跳转到登录页

5.7.3 实现订单和"模拟支付"

请实现订单功能：

API：
- POST /api/orders — 从购物车创建订单
  - 在数据库事务中：创建订单 → 扣减库存 → 清空购物车
  - 如果库存不足，返回具体哪个商品缺货
- GET /api/orders — 我的订单列表
- GET /api/orders/[id] — 订单详情
- PUT /api/orders/[id] — 模拟支付（PENDING → PAID）

前端页面：
- /orders — 订单列表（订单号、金额、状态标签、时间）
- /orders/[id] — 订单详情（商品明细、合计、状态、模拟支付按钮）

订单状态流转：
PENDING（待付款）→ PAID（已支付）→ SHIPPED（已发货）→ COMPLETED（已完成）
                                               CANCELLED（已取消）← 可从任意状态取消

5.7.4 核心业务逻辑解析

为什么下单要用数据库事务？

下单涉及三个操作：创建订单 + 扣减库存 + 清空购物车。这三个操作必须要么全做，要么全不做。如果创建了订单但库存扣减失败了——用户付了钱但库存没减，后续会超卖。

Prisma 的事务写法：

const order = await prisma.$transaction(async (tx) => {
  // 1. 创建订单
  const newOrder = await tx.order.create({ data: { ... } });
  // 2. 扣减库存
  await tx.product.update({ where: { id }, data: { stock: { decrement: qty } } });
  // 3. 清空购物车
  await tx.cartItem.deleteMany({ where: { userId } });
  return newOrder;
});
// 如果任何一步失败，前面已执行的操作会自动回滚

为什么订单明细要存 productName 和 price？

历史订单不应该受后续商品修改影响。如果一个月后商品改名或涨价，你的历史订单不应该跟着变。所以下单时把商品名和价格"快照"到 OrderItem 表里。

5.7.5 你学到了什么

概念	说明
数据库事务	保证多个操作要么全成功要么全失败
库存扣减时机	下单时扣减，防止超卖
数据快照	历史数据不应该受后续修改影响
Task 管理	复杂模块拆成小任务，逐个跟踪

---

5.8 后台管理模块

本节目标：用 Skill 快速生成后台 CRUD，实现管理功能

演示的 Claude Code 功能：自定义 Skill 的复用、权限校验

5.8.1 使用自定义 Skill 加速开发

还记得 6.4 节创建的 api-crud-generator Skill 吗？现在它派上用场了：

请用 api-crud-generator Skill 为后台管理生成以下模块：

1. 商品管理 /admin/products
   - API: GET/POST /api/admin/products
   - API: PUT/DELETE /api/admin/products/[id]
   - 页面：表格列表 + 新增/编辑表单

2. 订单管理 /admin/orders
   - API: GET /api/admin/orders（所有订单列表）
   - API: PUT /api/admin/orders/[id]（更新订单状态）
   - 页面：表格列表 + 状态流转按钮

3. 分类管理 /admin/categories
   - API: GET/POST /api/admin/categories
   - API: DELETE /api/admin/categories/[id]
   - 页面：列表 + 新增表单

所有后台页面需要验证当前用户是否为 ADMIN 角色。

提示：这就是 Skill 的价值——如果没有 api-crud-generator，你需要为三个模块分别写几乎相同的 Prompt。有了 Skill，一句话就搞定了。

5.8.2 权限校验

后台页面通过 Server Component 做权限校验：

// src/app/admin/page.tsx
import { getCurrentUser } from "@/lib/auth";
import { redirect } from "next/navigation";

export default async function AdminPage() {
  const user = await getCurrentUser();
  if (!user || user.role !== "ADMIN") {
   redirect("/login");  // 非管理员直接跳转
  }
  // ... 页面内容
}

注意：服务端校验是必须的。不能只在客户端隐藏按钮——用户可以通过浏览器开发者工具直接调用 API。所以 API Route 里也要做权限检查（本项目简化处理，实际生产环境每个管理 API 都应该做）。

5.8.3 更新导航栏

后台模块完成后，更新 Navbar 组件：

• 未登录时：显示"登录"按钮
• 登录后：显示用户名 + 购物车 + 我的订单
• 管理员：额外显示"后台管理"入口
• 点击"退出"：清除 Cookie，回到首页

AI 能根据会话状态动态展示导航菜单，提升用户体验。

5.8.4 你学到了什么

概念	说明
Skill 复用	一次创建，在多个模块中反复使用
权限校验	服务端检查用户角色，不能只靠前端
redirect	Next.js 的服务端跳转方法

---

5.9 上线前审查 + 项目复盘

本节目标：用 /review 和 /security-review 做最终检查，回顾完整项目

演示的 Claude Code 功能：/review、/security-review、Git 工作流

5.9.1 全量安全审查

所有功能完成后，做一次完整的安全检查：

/security-review

AI 会从多个维度检查：

维度	检查内容
认证安全	密码正确哈希？Session 安全？
数据安全	API 是否暴露了不该暴露的字段？
输入验证	是否有未验证的用户输入？
权限控制	管理接口是否正确保护？

注意：AI 的安全审查不能替代专业安全审计。如果是真的上线的项目，还需要做渗透测试、依赖漏洞扫描等。

5.9.2 最终代码审查

/review

AI 会给出代码质量报告，包括：

• 代码风格是否一致
• 有没有未使用的变量/导入
• 有没有潜在的运行时错误
• 改进建议

5.9.3 Git 工作流回顾

看看我们一路走来的提交历史：

git log --oneline

理想情况下，你应该看到类似这样的提交历史：

a1b2c3d feat: 后台管理模块（商品/订单/分类 CRUD）
d4e5f6g feat: 购物车 + 订单模块
g7h8i9j feat: 用户认证模块（注册/登录/Session）
j0k1l2m feat: 商品模块（API + 前端页面）
m3n4o5p feat: 数据库模型 + 种子数据
p6q7r8s chore: 项目初始化

每个功能一个 commit，提交信息清晰明了。这就是良好的 Git 实践。

提示：用 AI 开发时，养成一个习惯——在让 AI 做大改动之前，先 git add . && git commit。这样即使 AI 改坏了，你也能随时回到上一个正确的版本。这是无数 AI 编程老手的血泪经验。

5.9.4 项目运行指南

# 1. 进入项目
cd mini-mall

# 2. 安装依赖
npm install

# 3. 初始化数据库
npx prisma migrate dev
npx prisma db seed

# 4. 启动开发服务器
npm run dev

# 5. 浏览器打开 http://localhost:3000

测试账号：

• 管理员：admin@minimall.com / admin123
• 用户：user@example.com / user123

5.9.5 完整用户流程测试

1. 打开首页 → 看到 12 个商品，按分类筛选，搜索
2. 点击商品 → 查看详情
3. 注册新账号 → 登录
4. 加入购物车 → 修改数量 → 删除某项
5. 提交订单 → 查看订单列表 → 点击"模拟支付"
6. 退出 → 管理员登录 → 访问 /admin
7. 后台添加商品 → 编辑商品 → 管理订单状态

5.9.6 你学到了什么

概念	说明
/security-review	AI 辅助的安全检查，上线前必做
/review	AI 代码审查，保证质量
Git 提交规范	每个功能一个 commit，清晰可追溯
完整的项目交付	从架构设计到最终审查的完整闭环

---

5.10 项目总结：13 项 Claude Code 功能清单

#	功能	你在本项目中哪里用过	什么时候再用
1	/plan	6.1 项目启动	任何新项目/新功能开始前
2	CLAUDE.md	6.2 环境搭建	每个项目都要有
3	Task 任务列表	6.7 购物车开发	多步骤复杂任务
4	自定义 Skill	6.4 创建 + 6.8 复用	重复性工作封装
5	官方 Skill	文档提到 frontend-design	需要专业能力时
6	Hook 配置	6.3 配置	项目初始化时配置一次
7	Memory	6.3 配置	偏好和约定记录
8	/review	6.5 + 6.9	每个模块完成后
9	/security-review	6.6 + 6.9	认证模块 + 上线前
10	多模型切换	6.6.4 讨论	复杂逻辑用 Opus，UI 用 Haiku
11	权限模式	6.3.2 讨论	根据信任程度调整
12	Git 工作流	6.9.3 回顾	全程
13	.env 管理	6.2	存储密钥和配置

---

5.11 下一步

完成了这个复杂项目，你已经掌握了 Claude Code 的核心用法。接下来进入第六部分——独立实战。从项目列表中选择一个你感兴趣的项目，不再依赖详细的 Prompt，自己规划、自己驱动。你准备好了。

如果你在独立实战中遇到问题，记住这个口诀：

先想清楚再问 AI（/plan）
让 AI 知道项目背景（CLAUDE.md）
小步快跑逐个来（Task）
做完一步存一步（Git commit）

---

第六部分：项目实战（独立完成）

学习目标：运用前五部分学到的方法，独立完成至少一个适合 Vibe Coding 的真实项目

完成标志：独立完成一个项目，能运行、能展示、能部署，并能写出清晰的复盘说明

6.1 独立实战说明

恭喜你走到了这里！前面的章节是"师傅领进门"，这一部分是"修行在个人"。

从现在开始，你需要自己选择项目、自己驱动 AI 完成开发。你可以使用 Claude Code，也可以使用 Codex Desktop，甚至两者配合：Claude Code 负责深度编码和代码审查，Codex 负责文件整理、部署、自动化和桌面操作。

独立开发流程（复用第五部分的方法论）：

1. 选择项目 → 写一句话描述
2. 用AI生成PRD → 人工审查修改
3. 用AI生成SPEC → 确认技术方案
4. 创建CLAUDE.md → 建立项目上下文
5. 骨架搭建 → 验证可运行
6. 逐功能开发 → 每个功能一个commit
7. Code Review + 测试
8. 部署上线
9. 复盘总结

6.2 选项目的三个原则

不要只选“看起来高级”的项目。适合 Vibe Coding 的项目，最好满足三个条件：

1. 需求能用一句话说清楚：比如“给我做一个可以记录支出的记账工具”。
2. 有可视化结果：页面、图表、报表、文件、部署链接都可以，方便你验收。
3. 边界不太大：第一版最好 3 天到 2 周能做完，不要一上来就做完整 SaaS。

Claude Code 和 Codex 的分工可以这样理解：

项目特征	更适合的工具	原因
代码文件多、需要重构、要跑测试	Claude Code	终端工作流和代码审查更强
文件整理、文档生成、部署、自动化	Codex Desktop	图形界面和桌面任务更顺手
从零做 Web App	两者都适合	Claude Code 写核心代码，Codex 辅助部署与整理
面向非程序员的轻量工具	Codex Desktop	交互门槛低，适合用自然语言驱动

6.3 初级项目清单：先做出可用工具

项目	更适合	你会练到什么	核心功能	预计周期
番茄钟 + 任务记录	Codex / Claude Code	状态管理、计时器、轻量 UI	计时、暂停、任务列表、完成统计	1-2 天
个人记账工具	Claude Code	CRUD、图表、数据建模	收支记录、分类统计、月度报表	3-5 天
习惯追踪器	Claude Code	日历视图、连续打卡逻辑	习惯创建、每日打卡、趋势图	3-5 天
Markdown 笔记应用	两者都适合	编辑器、预览、文件导出	实时预览、分类、搜索、导出	3-5 天
在线简历生成器	Codex	文档生成、模板化输出	表单录入、模板切换、PDF 导出	3-5 天
图片压缩与格式转换工具	Codex	文件批处理、命令行工具调用	批量上传、压缩、WebP 转换	2-4 天
课程资料整理器	Codex	本地文件操作、命名规范	扫描文件夹、重命名、生成目录	2-4 天
个人作品集网站	两者都适合	页面结构、响应式、部署	项目展示、关于我、联系方式	3-7 天

初级项目的目标不是“技术多复杂”，而是完整跑通：需求 → 计划 → 实现 → 验收 → 部署 → 复盘。

6.4 中级项目清单：做出完整业务闭环

项目	更适合	你会练到什么	核心功能	预计周期
团队任务看板	Claude Code	拖拽、权限、多人协作	看板、任务、成员、状态流转	1-2 周
读书/课程知识库	两者都适合	搜索、标签、摘要生成	资料导入、标签、全文搜索、摘要	1-2 周
AI 周报生成器	Codex	自动化、文档整合	读取 Git/任务记录、生成周报	3-7 天
博客/CMS 系统	Claude Code	内容模型、MDX、后台管理	文章、分类、草稿、发布	1-2 周
URL 短链接服务	Claude Code	API、数据库、统计	短链生成、访问统计、后台	3-7 天
问卷调查系统	Claude Code	动态表单、统计图表	表单设计、提交、结果分析	1-2 周
食谱管理应用	两者都适合	搜索过滤、图片与结构化数据	食谱录入、食材清单、收藏	1 周
部署监控面板	Codex / Claude Code	API 调用、定时检查	网站状态、日志摘要、告警	1-2 周
AI 知识库问答系统	Claude Code	RAG、向量检索、引用来源	文档上传、检索、问答、引用	2-3 周
小型电商 MVP	Claude Code	全栈业务、订单流程	商品、购物车、订单、后台	2-4 周

中级项目建议每个功能单独提交一次 Git。让 AI 做实现，你负责检查业务逻辑是否真的闭环。

6.5 进阶项目清单：挑战 Agent 工作流

项目	更适合	关键挑战	第一版验收标准
AI 客服机器人	Claude Code	工具调用、知识库、会话状态	能基于资料回答，并展示引用
多人协作白板	Claude Code	Canvas、实时同步、冲突处理	多人能同时绘制和移动元素
会议纪要流水线	Codex	音频转写、摘要、文档生成	输入录音，输出纪要和待办
GitHub 热门项目推荐器	Codex	自动化、信息筛选、定时执行	每周生成一篇项目推荐稿
个人数据驾驶舱	两者都适合	多数据源、图表、权限	展示健康/学习/财务核心指标
代码库体检工具	Claude Code	静态分析、规则设计、报告生成	输出质量评分和修复建议
SaaS 订阅管理	Claude Code	认证、支付、权限、账单	用户可订阅、取消、查看账单
浏览器自动化助手	Codex	浏览器操作、表单、截图验证	自动完成一组网页重复操作

进阶项目不要一次性全做。先做“最小可用版本”，再用 AI 帮你列第二阶段路线图。

6.6 推荐起步项目：从这五个里面选

如果你不知道从哪个开始，优先选下面五个。它们最适合训练 Claude Code 和 Codex 的 Vibe Coding 工作流。

推荐项目	为什么适合	第一条 Prompt 示例
个人记账工具	业务闭环清晰，适合练 CRUD 和图表	“请先帮我设计一个个人记账工具的 PRD，不要写代码。”
课程资料整理器	Codex 能发挥本地文件处理优势	“请扫描这个课程文件夹，先给出整理方案和命名规则。”
AI 周报生成器	适合练自动化与文档输出	“请基于 Git 提交、任务记录和笔记生成本周周报模板。”
团队任务看板	适合练复杂状态和拖拽交互	“请先设计任务看板的数据模型和页面结构。”
小型电商 MVP	覆盖全栈核心能力	“请进入计划模式，帮我规划一个微型商城的第一版。”

通用开场 Prompt：

我想做一个「项目名称」。请先不要写代码。
请你先完成三件事：
1. 用小白能看懂的话整理 PRD；
2. 拆成 3-5 个开发阶段；
3. 告诉我第一版最小可用功能应该包含什么。
等我确认后，再开始创建项目文件。

6.7 从学习项目到开源贡献

当你完成了一个项目并想分享给社区时：

一个好的 GitHub 开源项目需要：

1. README.md：项目介绍、功能截图、安装使用说明
2. LICENSE：开源协议（推荐 MIT 协议）
3. .gitignore：确保不提交敏感信息
4. Contributing 指南（可选）：告诉别人如何参与贡献

你可以让 Claude Code 帮你生成这些文件：

> 请为这个项目生成一个完整的 README.md，包含：
> - 项目介绍和功能截图位置
> - 技术栈
> - 本地开发环境搭建步骤
> - 使用说明
> - MIT License 声明

第七部分：Codex Desktop 安装和使用教程

学习目标：认识 Codex Desktop 的产品定位，完成安装配置，并掌握在真实项目中使用桌面 Agent 的基本方法。

完成标志：你能独立创建 Codex 项目、授权它读取本地文件、让它执行命令、管理记忆与插件，并知道什么时候应该交给 Codex、什么时候需要自己把关。

前面几部分我们重点学习了 Claude Code、Skills、MCP 和项目实战。到了这一部分，我们换一个视角：用 OpenAI 的 Codex Desktop 来理解“桌面 Agent”到底能帮我们做什么。

不要把 Codex 只理解成一个聊天窗口。它更像是运行在你电脑旁边的执行型助手：能读项目文件、调用终端、创建文档、部署网站、连接外部服务，也能在你授权后完成一些跨软件的操作。本章的重点不是把每个按钮背下来，而是建立一套使用桌面 Agent 的工作习惯。

7.1 Codex Desktop 适合解决什么问题

Codex 和 Claude Code 都属于编程 Agent，但二者的侧重点不完全一样。Claude Code 以终端开发工作流起家，现在也有 IDE、Desktop 和 Web 入口，适合深度编码、代码审查、复杂重构；Codex Desktop 更强调图形界面、本地项目管理、插件连接和日常自动化，对零基础用户更友好。

对比维度	Claude Code	Codex Desktop
主要入口	终端 CLI，也支持 IDE / Desktop / Web 等入口	桌面应用，也可配合 CLI / VSCode 插件
学习门槛	终端形态需要熟悉命令行	更接近 ChatGPT 的对话体验
项目上下文	当前工作目录 + CLAUDE.md	本地项目文件夹 + agents.md
典型优势	编码、重构、规划、代码审查	文件处理、图形化管理、插件、自动化任务
扩展方式	Skills、MCP、Hooks 等	Skills、MCP、插件、自动化等
适合人群	有一定开发经验的用户	新手、非技术用户、希望用 GUI 管理任务的人

实际选型可以简单一点：

• 刚入门，害怕终端：优先从 Codex Desktop 开始。
• 已经在做工程项目：Claude Code 和 Codex 可以一起用，一个偏深度开发，一个偏日常执行。
• 要处理文件、部署、安装软件、定时任务：Codex Desktop 的桌面形态会更顺手。
• 要做复杂代码设计和长链路重构：Claude Code 的工程化体验通常更适合。

不必纠结“只能选谁”。Agent 工具之间不是互斥关系，关键是让不同工具承担它擅长的工作。

7.2 安装与首次启动

7.2.1 准备账号

使用 Codex Desktop 需要 ChatGPT 账号。免费账号通常也可以体验，但额度和能力会受限制；付费套餐的可用额度更多，适合高频使用。具体价格、额度和模型名称会随官方策略变化，正式使用前以 OpenAI 页面显示为准。

7.2.2 下载客户端

官方下载入口：

https://chatgpt.com/codex/download

下载完成后按安装向导操作即可。首次启动时，系统可能会询问你的主要用途，例如日常办公、学习或编程。这个选择只是为了初始化体验，不需要太紧张，后面可以继续调整。

7.2.3 认识主界面

Codex Desktop 的界面大体可以分成三块：

区域	作用
左侧栏	查看项目、会话、任务状态和插件入口
中间区域	输入需求、阅读回复、确认计划
右侧栏	展示预览、文件内容、浏览器页面或任务细节

第一次打开时，不需要把所有入口都研究一遍。建议先创建一个测试项目，用一个无风险的小任务熟悉流程，例如“帮我整理这个文件夹里的 Markdown 文件标题”。桌面 Agent 的学习方式和传统软件不同，边交代任务边观察它如何申请权限、如何拆解步骤，会比单纯看菜单更快。

7.3 权限模式：先理解安全边界

Codex 能读写本地文件、执行命令、连接插件，所以权限设置非常重要。它不是普通聊天机器人，而是可能真正改变你电脑文件状态的执行工具。

权限模式	含义	建议使用场景
自动审查模式	常规操作自动执行，高风险操作再请求确认	日常学习和普通项目，推荐新手使用
手动审查模式	涉及工具调用时更频繁地等待你确认	重要目录、生产环境、敏感文件
完全自动模式	尽量减少确认步骤，让任务连续执行	临时项目、沙盒环境、你明确知道风险时

新手建议从自动审查模式开始。它能减少频繁弹窗，又不会完全放开高风险操作。对于公司代码、客户资料、生产配置等重要目录，建议切换到更谨慎的模式，并在执行前要求 Codex 先给出计划。

一个好习惯是：

先让 Codex 说明它准备读哪些文件、改哪些文件、执行哪些命令，再让它动手。

7.4 核心能力一：管理本地文件

Codex Desktop 的“项目”本质上对应你电脑上的一个文件夹。你选择了某个文件夹，它才能在授权范围内读取、分析和修改里面的内容。

7.4.1 项目文件夹就是上下文边界

进入项目工作区后，Codex 会把该文件夹视为当前任务的主要上下文。它可以根据文件内容回答问题，也可以生成、移动、重命名或修改文件。

适合练习的任务包括：

• 批量整理课程资料文件名
• 把零散笔记合并成一份 Markdown 文档
• 根据图片或视频素材生成清单
• 检查项目目录结构是否混乱
• 把已有文档改写成更适合发布的版本

建议一开始用副本文件夹测试，确认行为符合预期后，再让 Codex 处理正式资料。

7.4.2 同一项目可以开多个会话

一个项目里可以并行存在多个会话。你可以让一个会话分析需求，让另一个会话整理文档，也可以把不同任务拆开，避免上下文互相干扰。

不过，并行不等于随意。涉及同一批文件的任务，最好避免同时修改，否则容易出现覆盖或冲突。更稳妥的做法是：一个会话负责写，另一个会话只负责审查或给建议。

7.4.3 产物会落在本地

Codex 在项目中生成的 Markdown、图片、PDF、PPT、代码文件等，都会保存到你的本地文件夹里。这一点很关键：它不是只在聊天记录里给你一段文本，而是能把结果变成真实文件。

记住一句话：项目文件夹既是 Codex 的工作台，也是它能看见的主要上下文。

7.5 核心能力二：调用终端和安装工具

Codex 可以在你授权后运行终端命令。对非技术用户来说，这个能力尤其有价值，因为很多开发环境配置、依赖安装和部署操作，本质上都是一串命令。

7.5.1 安装基础环境

例如你可以直接说：

请检查我电脑上是否已经安装 Node.js 和 Git。如果没有，请给出安装方案，确认后再执行。

相比直接说“帮我安装”，更推荐加上“先检查、再说明、确认后执行”。这样你可以知道它准备做什么，也能避免重复安装或装错版本。

7.5.2 安装其他开发工具

当你想安装某个新工具、CLI 或 Agent 时，可以让 Codex 先搜索官方文档，再根据系统环境选择安装方式。例如：

帮我安装 Hermes。请优先查官方仓库或官方文档，安装后验证版本，并告诉我启动方式。

这个提示词比单纯一句“帮我装一下”更可靠，因为它明确要求了来源、验证和交付结果。

7.5.3 安装 Skills、MCP 或插件相关依赖

对于不太知名的工具，最好把 GitHub 仓库、官网文档或安装说明链接直接发给 Codex。这样能减少它误判同名项目的概率。

这是我要安装的 Skill 仓库链接：xxx。请阅读 README，说明安装位置和启用方式，确认后再修改我的配置。

7.5.4 并行任务要有边界

Codex 支持同时运行多个任务，但不建议把多个会写同一目录的任务同时放出去。可以并行的任务通常有这些：

• 一个任务安装工具，另一个任务阅读文档
• 一个任务生成方案，另一个任务做资料整理
• 一个任务部署项目，另一个任务准备发布文案

涉及同一份代码或同一批文件时，先排队，再执行，会更稳。

7.6 常用操作：上下文、额度与模型

7.6.1 上下文管理

对话越长，模型需要携带的历史信息越多。Codex 会用界面上的上下文指示器提醒你当前会话的占用情况。当上下文接近上限时，它可能会自动压缩历史。

一个任务完成后，也可以主动让它总结当前状态：

请把当前项目进展、已修改文件、未完成事项和下一步建议压缩成一份简短摘要。

如果界面支持斜杠命令，也可以使用对应的压缩或状态命令。命令名称可能会随版本变化，按你当前客户端显示为准。

7.6.2 查看额度

额度通常可以在设置或状态面板中查看。有些版本也支持在对话中通过状态命令显示当前会话的上下文、短周期额度和周期额度。

这里要注意两点：

• 复杂任务、长上下文、高速模式或高推理强度通常会消耗更多额度。
• 额度、刷新周期和套餐权益会变化，不建议在教程里写死太多数字。

7.6.3 选择模型和推理强度

日常文件整理、文档改写、简单脚本，可以选择默认或中等智能程度。涉及架构设计、复杂调试、跨文件重构时，再提高模型能力或推理强度。

一个实用原则是：

低风险任务追求速度，高风险任务追求可解释和可确认。

7.7 核心能力三：持久记忆与 agents.md

Codex 的持久记忆可以分成两类：一类是你主动写下来的规则，另一类是系统自动总结的记忆。对教程学习者来说，最值得掌握的是 agents.md。

7.7.1 全局规则

全局规则适合存放跨项目都适用的偏好，例如：

- 默认使用中文回答。
- 修改文件前先说明计划。
- 重要操作前先列出影响范围。
- 文档改写时保留原意，不制造未经确认的数据。

这些规则相当于你对 Codex 的长期工作约定。写得越清楚，后续沟通成本越低。

7.7.2 项目规则

项目级 agents.md 只服务当前项目，适合记录技术栈、目录结构、运行命令、测试方式、提交规范和禁止事项。

推荐在项目初步成型后，让 Codex 读取项目并生成一版草稿：

请阅读当前项目结构，帮我生成一份项目级 agents.md。内容包括技术栈、常用命令、目录说明、开发约束和测试要求。先给我预览，不要直接写入。

审核通过后再写入，比一开始凭空写规则更贴合实际。

7.7.3 自动记忆

自动记忆适合作为补充，不适合作为唯一依赖。它可能会根据对话和任务自动总结信息，但触发时机、记录内容和召回方式不一定完全可控。

明确、稳定、重要的要求，仍然建议写进 agents.md；临时偏好和低风险背景，可以交给自动记忆辅助。

7.8 核心能力四：计划模式与实战开发

做复杂任务时，不要急着让 Codex 直接写文件。先进入计划模式，让它把需求拆开、列出步骤、说明风险，再决定是否执行。

7.8.1 用个人主页练手

你可以创建一个空项目，输入：

我想做一个个人主页。请先用计划模式和我确认目标用户、内容模块、视觉风格、技术栈和部署方式，不要立刻写代码。

Codex 通常会追问你一些选择题或开放问题，例如页面内容、风格偏好、是否需要响应式、是否部署等。你确认方案后，它再开始初始化项目。

7.8.2 执行中及时纠偏

当 Codex 生成过程中方向不对，不需要等它全部做完再说。你可以直接补充：

当前风格太像营销页了，请改成更像作品集：少用大段宣传语，多展示项目和联系方式。

很多时候，反馈会在下一轮工具调用前被加入上下文。这样既保留了当前进度，也能及时修正方向。

7.8.3 使用 Fork 保留好上下文

如果前半段讨论很有价值，但后面走偏了，可以从某条回复 Fork 出一个新会话。它相当于从历史分岔点重新开始，适合保留前面已经整理好的需求、方案和约束。

7.8.4 预览与批注

前端项目尤其适合使用内置预览。你可以边看页面边提出修改意见，有些版本还支持直接在预览区域批注具体元素。

修改页面时，尽量给 Codex 可执行的反馈：

• “按钮太靠下，移动到首屏右上角”
• “移动端标题换行不好看，请调整字号和宽度”
• “这张图与主题不符，请换成更贴近产品的图片”

比起“优化一下”，这类反馈更容易得到稳定结果。

7.9 核心能力五：插件系统

插件的作用，是让 Codex 连接外部平台和工具。不同版本、账号和系统环境下可见插件可能不同，但常见方向大致包括部署、浏览器操作、代码托管和外部应用连接。

插件类型	典型用途
部署类	将网站发布到 Vercel、Netlify 等平台
代码托管类	读取仓库、创建分支、处理 Issue 或 PR
浏览器类	打开网页、点击按钮、填写表单、截图验证
桌面操作类	在授权后控制部分本地应用或系统界面

7.9.1 部署网站

以前端项目为例，可以让 Codex 先检查构建命令，再连接部署平台：

请检查这个项目是否可以部署到 Netlify。先运行构建验证，说明需要的环境变量和部署步骤，确认后再连接插件执行部署。

部署完成后，让它返回访问链接、构建日志摘要和后续维护建议。

7.9.2 浏览器操作类插件

浏览器能力很适合做网页验证、后台配置、资料搜集和表单测试。但涉及账号、付款、删除、提交审批等敏感动作时，一定要求 Codex 停下来让你确认。

可以加一条长期规则：

凡是涉及登录、付款、删除、发布、提交表单的操作，必须先说明影响并等待我确认。

7.10 核心能力六：Skills

Skills 是把可复用流程沉淀下来的机制。前面我们已经详细讲过 Skills，在 Codex 中也可以用类似思路：把高频、稳定、步骤清晰的任务封装成技能。

适合做成 Skill 的任务包括：

• 每周生成技术资讯摘要
• 把课堂录音整理成讲义
• 检查前端页面的响应式问题
• 根据固定模板生成项目周报
• 按统一标准润色课程文档

创建 Skill 有两种常用路径。

第一种：先描述目标，让 Codex 帮你起草。

我想创建一个“课程文档润色”Skill，用于把口语稿改成正式教程。请先和我确认输入、输出、规则和示例。

第二种：先跑通一次真实任务，再沉淀。

这种方式更推荐。因为你已经知道流程中哪些步骤有效、哪些检查必须保留，生成出来的 Skill 会更实用。

7.11 核心能力七：MCP

MCP 可以理解为让 Agent 连接外部数据源或工具服务的一种协议。对于初学者，不需要一开始就深入配置细节，先知道它解决什么问题即可：当 Codex 需要访问某个外部知识库、数据库、文档系统或业务工具时，MCP 可能就是连接方式之一。

安装 MCP 时建议遵循三个原则：

• 优先使用官方文档或可信仓库。
• 安装前让 Codex 说明配置文件位置、权限范围和凭据保存方式。
• 安装后用一个最小任务验证是否真的连通。

示例提示词：

请根据这个 MCP 官方文档帮我完成配置。先说明它会访问哪些数据、需要哪些密钥、配置会写到哪里，等我确认后再执行。

7.12 核心能力八：自动化任务

自动化任务的价值，不是“定个闹钟让 AI 说一句话”，而是把一套可重复流程交给 Agent 定时执行。

例如：

• 每周一汇总 GitHub 趋势项目，生成中文推荐稿
• 每天早上检查网站是否可访问，并整理异常日志
• 每三天汇总课程资料文件夹，生成新增内容清单
• 每周生成一次学习进度报告

7.12.1 创建自动化的两种方式

你可以在自动化面板里手动创建，通常需要填写任务提示词、触发时间、模型和推理强度。

也可以直接在对话中描述：

请帮我创建一个自动化任务：每周一上午 9 点，读取我的项目资料文件夹，生成一份本周新增资料摘要。创建前先展示任务内容、执行频率和输出格式。

自动化任务要特别注意边界：它会在你不盯着屏幕的时候运行，所以提示词必须写清楚输入来源、允许做什么、禁止做什么、结果发到哪里。

7.13 手机端远程控制

部分版本支持通过 ChatGPT 手机 App 连接电脑上的 Codex，从手机端发起任务。这个能力适合临时下发轻量任务，例如让家里电脑继续整理资料、检查项目状态或生成草稿。

一般流程是：

1. 手机 ChatGPT 和电脑 Codex 都更新到支持该功能的版本。
2. 在手机端进入 Codex 入口。
3. 按提示完成电脑端配对。
4. 在电脑上确认允许该设备远程控制。

远程控制的便利性很高，但也意味着风险更高。建议只对可信设备开启，并避免在手机端随手发起删除、部署、付款、批量修改等高影响操作。

7.14 本部分小结

这一部分我们从“会安装”走到了“会安排任务”。Codex Desktop 的核心能力可以压缩成这张表：

能力	你应该掌握的重点
本地文件	项目文件夹就是 Codex 的工作范围和主要上下文
终端命令	先检查、再说明、确认后执行，避免盲目安装
上下文管理	长任务要阶段性总结，重要信息写入规则文件
持久记忆	全局偏好写全局规则，项目约束写项目 agents.md
计划模式	复杂任务先讨论方案，再进入执行
插件	连接部署、浏览器、代码托管等外部服务
Skills	把高频流程变成可复用能力
MCP	连接外部知识库和工具系统
自动化	把重复任务变成定时执行的流程
手机控制	远程下发任务，但要控制权限和风险

学完本章，请记住两件事。

第一，Codex 不是“更会聊天的搜索框”，而是可以在你电脑上执行任务的工作代理。它能节省时间，也需要你设定边界。

第二，使用 Agent 的能力不只在于会提问，更在于会管理：给清楚的目标，提供必要上下文，要求它先计划，执行中及时纠偏，最后验收结果。你越会管理任务，AI 编程工具越能发挥价值。

Codex 和 Claude Code 怎么搭配？

使用场景	推荐选择
零基础上手、图形界面学习	Codex Desktop
深度编码、代码审查、复杂重构	Claude Code
文件整理、部署、安装工具	Codex Desktop
编写 Skills、沉淀工作流	两者都可以
想获得更完整的 Agent 体验	两者搭配使用

附录

附录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编程的世界里，创造出令自己骄傲的作品！

---

本教程中的价格、版本信息已在 2026-07-03 按各平台官方文档核对，请以各服务商官网最新信息为准。