WEB项目地址：AI智能商品导购系统
安卓APP下载地址：精打细算

你有没有遇到过这种情况：让 AI 帮你写代码，结果它用了你从来不用的技术栈；让它处理一个文件，它顺手改了其他不该动的地方；明明团队约定用单引号，它老给你输出双引号……

折腾半天，改来改去，比你自己写还累。

这其实不是 AI 笨，是你没告诉它“规矩”。就像来了个新同事，你不给他讲项目规范，他肯定按自己习惯来。

今天要说的 CLAUDE.md 就是干这个用的——写一个文件，让 AI 进门就懂你的规矩。全程手把手，跟着做就行。

① 为什么需要项目规则文件

先说痛点。你用 AI 写代码，最怕什么？

  • 风格不一致：有的文件缩进 2 格，有的 4 格，有的用 tab，看得脑仁疼
  • 技术栈乱入：你明明用 Vue，它建议你装 React 组件
  • 越界操作：让它改一个函数，它顺手帮你重命名了文件夹
  • 重复踩坑：上次修复过的 bug，换个对话又犯

CLAUDE.md 就是解决这些问题的。它不是给程序员看的文档，是给 AI 读的“员工手册”。你把技术栈、代码风格、文件边界、禁止事项全写进去，AI 每次干活前先读一遍，之后的行为就规规矩矩。

核心价值就三条：

  1. 一致性：AI 输出跟你手写的一模一样
  2. 安全性：明确告诉它哪些不能碰
  3. 省时间：不用每次都重复交代“用 TypeScript 啊”“别动配置文件”

② 命名与存放位置

文件名

就用 CLAUDE.md，大小写别搞错。别的名字 AI 不认，别自作聪明改成 PROJECT_RULES.md。

放哪

项目根目录，和 package.json、README.md 平级。

你的项目/
├── CLAUDE.md          ← 放这
├── src/
├── tests/
└── package.json

如果你项目比较大，分了多个子模块，也可以在子目录里放额外的 CLAUDE.md——后面会讲多文件怎么玩。

一个例外

有些团队会用 .claude/CLAUDE.md（放一个隐藏文件夹里）。也行，但新手不推荐，容易找不到。先老老实实放根目录。

③ 写一个最小可用的结构

别想得太复杂。第一版能跑通就行，后面慢慢加。

最简单的 CLAUDE.md 长这样：

# 项目：我的博客系统

## 技术栈
- 前端：React 18 + TypeScript
- 状态：Zustand
- 样式：TailwindCSS
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 代码风格
- 缩进：2 空格
- 字符串：双引号
- 分号：必须加

## 禁止事项
- 不要改动 `.env` 文件
- 不要直接修改 `node_modules`
- 不要自动安装新依赖

就这几行，AI 就不会给你乱推 Vue 了。你可以把它复制过去，改改技术栈就能用。

④ 定义技术栈和代码风格（含写法）

新手最容易漏的就是“写清楚版本号”。光写“React”不够，得写“React 18.2 + TypeScript 5.0”，不然 AI 可能用旧版语法。

技术栈的标准写法

## 技术栈（必读）

### 前端
- 框架：Next.js 14 (App Router)
- 语言：TypeScript 5.x（严格模式，禁用 any）
- UI 库：shadcn/ui
- 样式：CSS Modules（不是 Tailwind）

### 后端
- 运行时：Node.js 20 LTS
- 框架：NestJS 10
- ORM：Prisma 5.x

### 测试
- 单元测试：Vitest
- E2E 测试：Playwright

为什么写这么细？因为 Next.js 有 Pages Router 和 App Router 两套写法，不指明的话 AI 混着写，你改都改不过来。

代码风格怎么描述

不要只说“保持整洁”，AI 不懂什么叫整洁。要写死规则：

## 代码风格（强制执行）

### 命名
- 组件：PascalCase（`UserProfile.tsx`）
- 函数/变量：camelCase（`getUserInfo`）
- 常量：SCREAMING_SNAKE_CASE（`MAX_RETRY_COUNT`）
- 文件夹：kebab-case（`user-profile/`）

### 格式
- 缩进：2 空格（不要 tab）
- 行宽：100 字符（超了就换行）
- 引号：单引号（JS/TS 里用 `'`，JSON 里用 `"`）
- 分号：必须加
- 尾随逗号：多行对象/数组必须加

### 导入顺序（按这个排）
1. 内置模块（`fs`, `path`）
2. 第三方库（`react`, `lodash`）
3. 项目内别名（`@/`）
4. 相对路径（`./`）

有个小技巧：把你团队已有的 ESLint/Prettier 配置贴进去，AI 会自动遵守。比如：

## 代码规范参照
本项目使用以下配置，生成代码请遵守：
- ESLint: `.eslintrc.js`（见文件末尾的配置摘要）
- Prettier: `.prettierrc`（单引号、无尾随逗号、120 字符）

⑤ 设定工作流约束和禁止行为

这是 AI 最容易闯祸的地方。你得把它当“实习生”管——明确什么不能碰。

禁止行为清单

用“不要”“禁止”“避免”这种强否定词，比“建议不”管用得多。

## 绝对禁止（碰到就拒绝）

❌ 不要修改以下文件：
- `.env` / `.env.local`（环境变量）
- `package-lock.json` / `yarn.lock`（锁文件）
- `node_modules/` 整个目录
- 任何以 `.secret.` 结尾的文件

❌ 不要做的事：
- 自动运行 `npm install` / `yarn add`
- 删除 `tests/` 以外的任何文件夹
- 修改数据库迁移文件（`migrations/`）
- 提交代码到 git（由开发者手动操作）

## 需确认才能做（先问）

⚠️ 如果遇到以下情况，先问我：
- 需要安装新依赖包
- 要删除超过 10 行的代码
- 需要改动 `tsconfig.json` 或 `vite.config.ts`
- 不确定某个 API 是否废弃

工作流约束

比如你在一个 Next.js 项目里，App Router 下页面用 app/ 文件夹，但老代码还有 pages/。你可以规定：

## 工作流规则

1. **新增页面**：一律放在 `app/` 下，使用 `page.tsx` 命名
2. **API 路由**：放在 `app/api/`，不要再用 `pages/api/`
3. **组件复用**：优先用 `@/components/ui/` 里的，没有再自己写
4. **状态管理**：局部用 useState，全局用 Zustand，不用 Redux

⑥ 用示例代码强化理解

光说“写一个获取用户信息的函数”不够，AI 不知道你的错误处理偏好、返回值格式。给个例子，它就懂了。

## 代码示例（按这个风格来）

### 好的写法 ✅

typescript
async function fetchUser(userId: string): Promise {
try {
const response = await api.get(/users/${userId});
return response.data;
} catch (error) {
console.error(‘Failed to fetch user:’, error);
return null; // 失败返回 null，不抛异常
}
}

### 坏的写法 ❌

typescript
async function fetchUser(userId) { // 缺类型
const res = await fetch(‘/users/’ + userId); // 没用 api 实例
return res.json(); // 没处理错误
}

## 组件模板

新建页面组件时，套用这个模板：

tsx
export default function PageName() {
return (

{/* 你的内容 */}
);
}

```

注意：示例里的注释要写清楚“为什么好”“为什么坏”，AI 会记住这些原则。

## ⑦ 多文件协作时的优先级

大项目一个 `CLAUDE.md` 可能不够用，因为前端、后端、工具脚本的规则不一样。这时候可以用多级文件。

规则很简单：**子目录的规则覆盖父目录的**。

### 实际例子

项目/
├── CLAUDE.md # 全局规则（后端 + 前端通用）
├── frontend/
│ ├── CLAUDE.md # 前端专属（覆盖样式相关规则）
│ └── src/
└── backend/
└── CLAUDE.md # 后端专属（覆盖 API 相关规则）

**全局规则** (`/CLAUDE.md`)：

markdown

  • 技术栈：全栈项目，前端 React，后端 NestJS
  • 缩进：2 空格
  • 禁止：改数据库 schema
**前端规则** (`/frontend/CLAUDE.md`)：

markdown

  • 继承全局规则（缩进 2 空格保留）
  • 覆盖：样式用 TailwindCSS（全局没定义样式方案）
  • 新增：组件必须写单元测试
**后端规则** (`/backend/CLAUDE.md`)：

markdown

  • 继承全局规则
  • 覆盖：允许改数据库 schema（只在 dev 环境）
  • 新增：所有 API 需要 Swagger 注解
AI 在处理 `frontend/src/App.tsx` 时，会先读全局的，再读 `frontend/` 的，后者优先级更高。

### 优先级口诀
> 叶子目录 > 上级目录 > 根目录

别把同一个规则在不同文件里写成相反的值，AI 会混乱。

## ⑧ 快速验证规则是否生效

写了半天规则，怎么知道 AI 真读了？有两种土办法。

### 方法一：问它

直接在聊天里问：
> “根据项目规则，我的代码应该用单引号还是双引号？”

如果它答“单引号”，说明读对了。如果答“都可以”，那它可能没加载上你的 `CLAUDE.md`。

### 方法二：写一个测试请求

故意让它写一段违反规则的代码，看它会不会自己纠正。

比如你的规则写“不能用 `var`，只能用 `const/let`”，你问：
> “写一个循环，从 1 到 10 求和”

如果它给出：

javascript
let sum = 0;
for (let i = 1; i <= 10; i++) {
sum += i;
}

那就对了。如果它写 `var sum = 0;`，说明规则没生效。

### 常见不生效的原因

- 文件名写错了（大小写，下划线等）
- 放错了目录（要放根目录或正在操作的子目录）
- 没保存文件（有时候你改了但 IDE 没自动保存）
- 对话上下文已满（开新对话试试）

## ⑨ 常见配置错误与修正

新手容易踩的坑，我列几个高频的。

### 坑1：规则写得太“虚”

markdown

  • 代码要整洁
  • 性能要好
  • 注释要清楚
没用。AI 不知道什么叫“整洁”。改成具体可执行的：

markdown

  • 每个函数不超过 30 行
  • 循环里避免频繁创建新对象
  • 每个文件顶部写一段注释说明用途
### 坑2：规则之间矛盾

markdown

  • 字符串用双引号
  • JSON 文件用单引号 ← 矛盾了（JSON 标准是双引号）
AI 会卡住。建议统一成“所有地方都用双引号，除了 JSON 里不用纠结”。

### 坑3：忘了更新规则

项目升级了，从 Vue 2 换到 Vue 3，但规则文件还写“Vue 2 Options API”，AI 给你的代码全是旧写法。

**修正方案**：每次技术栈大改，顺手改一下 `CLAUDE.md`，花不了两分钟。

### 坑4：规则太长

有些人写几千行的规则，AI 读着读着就忘了前半部分。

建议把最重要的 20 条写在前面，加个“核心规则（必读）”的标题。次要的放后面，或者拆到子目录的 `CLAUDE.md` 里。

## ⑩ 进阶技巧：动态调整与团队共享

用顺手之后，可以玩点高级的。

### 技巧1：动态规则（按场景切换）

你可以在不同分支用不同规则。比如 `feature-xx` 分支要实验新架构，就在分支里临时改 `CLAUDE.md`，合并回主分支时删掉。

更优雅的做法：用 Git hooks，在切换分支时自动替换规则文件。

### 技巧2：团队共享

把 `CLAUDE.md` 提交到 Git 仓库里，所有人共享一套规则。新人 clone 项目后，AI 自动遵守团队规范。

但注意：有些个人偏好（比如有人喜欢用 tab 缩进，有人喜欢空格）不适合放全局。可以每个人自己维护一个 `CLAUDE.local.md`（我在规则里写“优先读 `CLAUDE.local.md`，如果没有再读 `CLAUDE.md`”）。不过这个需要配合脚本，不是原生支持的。

### 技巧3：集成 CI 检查

你可以写个简单的脚本，在 PR 时检查 AI 生成的代码是否符合 `CLAUDE.md` 里的规则。比如用正则匹配一下有没有出现 `var`、双引号等。不符合的就拦截。

这只是个思路，真要做的话，可以用 `grep` 或写个 Node 脚本。

### 技巧4：规则模板化

把你常用的规则存成模板，新项目直接复制过去改改就行。我自己的模板长这样：

markdown

项目：[项目名]

技术栈（替换成你的）

  • 语言：TypeScript
  • 框架：Next.js (App Router)
  • UI：shadcn/ui + TailwindCSS

核心规则（前 10 条）

  1. 函数必须有返回值类型注解
  2. 禁止使用 any
  3. 所有异步操作要 try-catch
  4. 组件文件必须是 export default
  5. 工具函数用 export const
  6. 测试覆盖率 > 80%
  7. 提交前跑一遍 lint
  8. 注释用英文（代码用中文也行）
  9. 时间处理一律用 dayjs
  10. 请求用项目内的 request 实例，不要裸写 fetch

（下面继续加项目特有规则）

## 收个尾

写 `CLAUDE.md` 就像给你的 AI 助手发一本员工手册。花 10 分钟写个初版，能省下以后无数次的“不是，你搞错了，我是要……”这种废话。

别追求完美，从今天开始，在你的项目根目录建一个 `CLAUDE.md`，把今天用到的技术栈和一条你最在意的规则写进去。比如：

markdown

我的项目

  • 技术栈：React + Vite + TypeScript
  • 最重要：不要用 any，永远不要
    “`

试试看，然后问 AI 一个代码问题，你会回来感谢我的。