给AI写CLAUDE.md入职说明书，让AI不再乱改代码

文章目录

• • 前言
  • 1. 这文件到底放哪儿
  • • 1.1 它在项目根目录，名字必须全大写
    • 1.2 加载顺序：项目级 > 全局级 > 内置
  • 2. 语法没你想的那么玄
  • • 2.1 推荐结构
  • 3. 四个核心模块，缺一个都像相亲只给照片
  • • 3.1 项目简介：AI 的入职第一课
    • 3.2 代码规范：别让它有样学样
    • 3.3 开发流程：先读代码，别上来就重写
    • 3.4 约束条件：最后一道防线
  • 4. 一份能直接抄的中级模板
  • 5. 文件太大？拆！
  • 6. CLAUDE.md 和 Skills，谁管谁
  • 7. 跟 OpenSpec 组队，AI 就有导航了
  • 8. 写得好不好，就看这几条
  • • 8.1 推荐这么做
    • 8.2 千万别这么干
  • 9. AI 不听话了？按顺序排查
  • 10. 两个直接能用的例子
  • • 10.1 最小可用版：个人项目够用
    • 10.2 多文件版：团队项目标配
  • 11. 你可能会问的 8 个问题
  • • 11.1 和 .claude/instructions/ 冲突了怎么办？
    • 11.2 全局和项目级啥关系？
    • 11.3 上下文被挤占怎么办？
    • 11.4 别的工具能用吗？
    • 11.5 能用环境变量吗？
    • 11.6 项目里有多个前端怎么办？
    • 11.7 改完要重启吗？
    • 11.8 密钥不小心提交了？
  • 小结

P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，
传送门https://blog.csdn.net/H1727548

前言

先说个扎心的现实：你花一晚上写的注释，AI 可能一眼都不看；你在 CLAUDE.md 里随手写的三行字，它每次开工前都要恭恭敬敬读一遍。

像不像你对象查你手机——你精心准备的说辞她记不住，你随手删掉的那条她记得清清楚楚。

所以，给 AI 写一份好用的「入职说明书」，是你这个月性价比最高的一件事。

1. 这文件到底放哪儿

1.1 它在项目根目录，名字必须全大写

CLAUDE.md 就躺在项目根目录，后缀都不能错。名字全大写，跟你的偶像包袱一样重。

Claude Code 一启动就自动读取，像极了入职第一天 HR 塞给你的《员工手册》——只不过这次手册是你写的，员工是个 AI。

my-project/
├── CLAUDE.md ← Claude Code 启动时自动读取
├── .gitignore
├── src/
├── tests/
└── package.json

1.2 加载顺序：项目级 > 全局级 > 内置

三个层级，一个表格说清楚：

简单翻译：项目级管这个项目，全局级管你这个人，内置是它天生自带的技能。三者会合并，项目级的字段说了算。

换句话说：全局文件是你的「出厂设置」，项目文件是「这个项目专属皮肤」。AI 一看，哦，这个项目有自己的规矩，行，按规矩来。

2. 语法没你想的那么玄

就一个硬性要求：Markdown。别整花活。

它靠章节标题理解你的意图，你也靠章节标题找它要的东西。你俩达成一种奇妙的默契，像极了开会时只念 PPT 标题的领导——内容不重要，标题对了就行。

2.1 推荐结构

# CLAUDE.md
## 项目简介
简短描述项目是什么、主要技术栈。
## 代码规范
– 代码风格、命名规则、文件组织方式
– 测试要求与覆盖率标准
## 开发流程
– 新功能开发的步骤
– 提交信息的格式规范
– 分支策略
## 约束条件
– 不要修改的文件或目录
– 需要谨慎操作的部分
– 依赖管理规则

3. 四个核心模块，缺一个都像相亲只给照片

项目简介、代码规范、开发流程、约束条件，这四样凑齐，AI 才算正式上岗。

3.1 项目简介：AI 的入职第一课

这是最重要的部分。AI 第一次进项目，两眼一抹黑，全靠这段文字认门。

你不写，它就只能靠猜。AI 猜你的技术栈，就像你猜对象为什么生气——方向大概率对，细节全错，最后挨骂的还是你。

# CLAUDE.md
## 项目简介
基于 Express + Prisma + PostgreSQL 的电商后台管理系统。
– 前端: React 18 + TypeScript + Tailwind CSS
– 后端: Express + Prisma ORM
– 数据库: PostgreSQL
– 测试: Vitest (前端) + Jest (后端)
– 包管理: pnpm
– 运行时: Node.js 20+

3.2 代码规范：别让它有样学样

命名规则、目录结构、导入顺序，全给它写明白。不然它真敢写一个叫 data 的变量，然后理直气壮地看着你。

说句公道话：你要是自己命名都随心所欲，就别怪 AI 继承你的「优良传统」。它比你想象中更懂什么叫入乡随俗。

## 代码规范
### 命名规则
– 组件: PascalCase (UserCard, OrderTable)
– 函数/变量: camelCase (fetchUserData, isLoading)
– 常量: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
– 文件: kebab-case (user-card.tsx, order-service.ts)
– 数据库字段: snake_case (created_at, user_id)
### 导入顺序
1. 外部依赖 (react, express)
2. 内部模块 (@/components, @/lib)
3. 类型定义 (types)
4. 样式文件 (.css, .module.css)

3.3 开发流程：先读代码，别上来就重写

告诉它：先理解现有代码，再动手；先写测试，再写实现；提交信息按格式来。

不然它会很贴心地帮你把整个项目重写一遍，然后自豪地说「我觉得这样更好」。那一刻你只想问它：你觉得我工资要不要也顺便重写一下？

## 开发流程
1. 先阅读现有代码理解架构，不要重写已经存在的功能
2. 新功能使用 OpenSpec 流程: propose → explore → apply → archive
3. 写代码之前先写测试，遵循测试驱动开发
4. 每次修改后运行相关测试: pnpm test — –related
5. 保持提交粒度适中，一个功能点一个提交
### 提交信息格式
<type>: <简短描述>
类型: feat / fix / refactor / test / docs / chore
示例: feat: add user login API

3.4 约束条件：最后一道防线

这是防止 AI 越界的唯一指望。

记住一个真理：告诉 AI 什么不能做，比告诉它能做什么有用一百倍。跟养孩子一个道理——「别摸电门」比「随便玩」管用。

## 约束条件
– 【禁止】修改 node_modules/、dist/、.next/ 等生成目录
– 【禁止】修改数据库迁移文件（由 DBA 统一管理）
– 【谨慎】修改 package.json 中的依赖版本需要说明理由
– 【必须】所有 API 新增端点需要补充对应的类型定义
– 【必须】修改环境变量配置需要更新 .env.example

4. 一份能直接抄的中级模板

下面这份直接抄，抄完把项目信息填进去，就是你的专属配置。

友情提示：模板是死的，项目是活的。别抄完就觉得自己功德圆满——AI 替你打工，但不替你背锅。

# CLAUDE.md
## 项目简介
前后端分离的电商后台管理系统。
**技术栈：**
– 前端: React 18 + TypeScript + Tailwind CSS + TanStack Query
– 后端: Express.js + Prisma ORM + Zod 验证
– 数据库: PostgreSQL 15
– 测试: Vitest + Playwright
– CI/CD: GitHub Actions
## 代码规范
1. TypeScript 严格模式，避免使用 any
2. 组件文件使用默认导出，工具函数使用具名导出
3. 所有 API 响应都要包装在统一格式中: { code, data, message }
4. 错误优先使用自定义业务异常，不要直接 throw Error
5. 函数长度控制在 50 行以内，超过则拆分
## 开发流程
1. 新功能: OpenSpec 规范驱动 (/opsx:propose → explore → apply → archive)
2. 小修复: 直接在对话中描述需求
3. 紧急修复: 直接改代码，但事后补充测试
4. 每次提交前运行: pnpm run check (lint + type-check + test)
## 测试要求
– 新增工具函数必须写单元测试
– API 端点必须有集成测试覆盖正常和异常路径
– 测试不 mocking 过多层，优先集成测试
## 约束条件
– 不要修改 .github/ 下的 CI 配置文件
– 不要手动编辑 prisma/schema.prisma（使用 prisma migrate）
– 所有环境变量必须从 process.env 读取，无硬编码
– 敏感信息（密码、token）不得写入代码或日志

5. 文件太大？拆！

CLAUDE.md 写太长，AI 的上下文被挤占，就像你的手机内存，塞满了就卡。

解决办法：拆成 .claude/instructions/ 目录，一个文件管一件事。

my-project/
├── CLAUDE.md ← 主文件（项目概览 + 核心约束）
├── .claude/
│ └── instructions/
│ ├── coding-style.md ← 代码规范细则
│ ├── test-requirements.md ← 测试要求
│ ├── git-workflow.md ← Git 分支/提交规范
│ └── security-rules.md ← 安全编码规则

主文件里引用子文件，AI 需要时按需读取：

## 代码规范
详见 `.claude/instructions/coding-style.md`。
## 开发流程
详见 `.claude/instructions/git-workflow.md`。
## 约束条件
详见 `.claude/instructions/security-rules.md`。

主文件只留核心约束，细则全丢子文件。AI 用到哪读到哪，像极了当代年轻人——不背知识，需要时才搜。

6. CLAUDE.md 和 Skills，谁管谁

一句话：CLAUDE.md 说「这个项目是什么」，Skills 说「这事儿我能怎么干」。

一个像简历，一个像技能证书。公司先看简历决定要不要你，干活的时候才翻你的证书。

# CLAUDE.md
## 开发流程
– 使用 /skill review 对代码进行审查
– 使用 /skill write-test 为新功能补充测试
– 提交前运行: pnpm run check

7. 跟 OpenSpec 组队，AI 就有导航了

团队用规范驱动开发？把流程写进 CLAUDE.md，AI 就像开了导航，不会再乱打方向盘。

## 开发流程
本项目使用 OpenSpec 规范驱动开发：
1. 新功能: /opsx:propose → 审核 → /opsx:explore → 审核 → /opsx:apply
2. 小修复: 直接在对话中描述，跳过 propose
3. 紧急修复: 直接 apply，事后 /opsx:archive 补流程
4. 已归档的 spec 可在 openspec/archive/ 查阅

8. 写得好不好，就看这几条

8.1 推荐这么做

章节标题要明确；约束用【禁止】【必须】【谨慎】标等级；例子给完整；测试命令写清楚；定期跟技术栈同步更新。

翻译成人话：标题清楚点，规矩写明白点，例子给全点，更新勤快点。你写 CLAUDE.md 的样子，像极了给新人写操作手册的运维老哥。

8.2 千万别这么干

别写矛盾规则（一边说 React 一边说 Vue）；别写「写出高质量的代码」这种废话；别塞项目无关内容；更别把密钥写进去。

把密钥写进 CLAUDE.md 再提交，这操作像把银行卡密码写在卡背面——方便是方便，就是有点费钱。

9. AI 不听话了？按顺序排查

别慌，按顺序来，大概率是小事。

# 检查文件是否存在
ls -la CLAUDE.md
# 检查文件编码（必须是 UTF-8）
file CLAUDE.md
# 检查文件名大小写（必须是 CLAUDE.md，不是 claude.md）
echo "CLAUDE.md" | grep -E '^CLAUDE\\.md$'
# 在对话中提问："请告诉我你从 CLAUDE.md 读取了哪些配置"

最后那招最绝：直接问它「你从 CLAUDE.md 读到了什么」。这相当于面试官问「你了解我们公司吗」——它要是支支吾吾，说明它压根没看，你前面全白写了。

10. 两个直接能用的例子

10.1 最小可用版：个人项目够用

# CLAUDE.md
## 项目
TypeScript + Bun 的 CLI 工具。
## 规范
– Bun 运行时，不使用 Node.js
– 使用 Bun 内置测试框架 (bun test)
– 文件命名: kebab-case
## 流程
1. 先阅读现有 src/ 下的文件了解风格
2. 新命令在 src/commands/ 下创建
3. 运行 bun test 验证
4. 运行 bun run src/index.ts 端到端测试

10.2 多文件版：团队项目标配

主文件：

# CLAUDE.md
## 项目
Express + Prisma + React 全栈电商平台。
## 模块引用
请参考 .claude/instructions/ 下的文件获取完整规范：
– coding-style.md — 代码风格细则
– test-requirements.md — 测试要求
– security.md — 安全编码规则
## 约束条件
– 【禁止】修改 node_modules/、dist/、.next/
– 【必须】每个 API 端点添加输入验证

子文件 .claude/instructions/coding-style.md：

# 代码规范
## 命名
– 组件: PascalCase (UserProfile)
– 函数: camelCase (getUserData)
– 常量: UPPER_SNAKE_CASE (API_BASE_URL)
## 文件组织
– 每个组件一个文件
– 同目录下不超过 10 个文件，超出则创建子目录

11. 你可能会问的 8 个问题

11.1 和 .claude/instructions/ 冲突了怎么办？

以 instructions 里的为准。它后加载，后加载的说了算，跟 Git 里后提交的覆盖先提交的一个道理。核心约束留主文件，可变的流程细则放子文件，各管各的。

11.2 全局和项目级啥关系？

项目级覆盖全局级的同名字段。全局写个人习惯（比如提交信息格式），项目写项目特色（比如技术栈、目录结构）。

你要是全局写了「用 React」，项目里却用 Vue，AI 会陷入长达三秒的人生思考，然后按全局的来——你怪谁？

11.3 上下文被挤占怎么办？

拆！细则丢子文件，按需读取。别什么都往主文件塞——你手机内存也不允许你什么都装。

11.4 别的工具能用吗？

各有各的名字：Codex 用 CODEX.md，OpenCode 没标准格式，Hermes 靠系统提示词。

想统一管理？写个脚本一键生成。程序员嘛，能用脚本解决的事，绝不手动——哪怕写脚本比手动还累。

11.5 能用环境变量吗？

不能。纯静态 Markdown，不支持变量插值或模板渲染。想按环境切换，去 instructions 里按需处理。

11.6 项目里有多个前端怎么办？

写条件式说明：React 目录用 React，Vue 目录用 Vue。

不然 AI 会在 Vue 项目里给你写 JSX，然后一脸无辜地看着你，仿佛错的是你。

## 项目结构
– web/react-app/ — React 应用（主前端）
– web/admin-vue/ — Vue 管理后台
## 代码规范
– 在 react-app/ 下工作时：使用 React + JSX
– 在 admin-vue/ 下工作时：使用 Vue 3 + Composition API

11.7 改完要重启吗？

不用。CLAUDE.md 每次加载项目时都会读。AI 已经在干活了？跟它说一声文件更新了，或者输入 /reload。它比你想象中好沟通——至少比某些同事好沟通。

11.8 密钥不小心提交了？

马上处理：清 Git 历史 + 轮换密钥，双管齐下。

# 从 Git 历史中彻底删除（谨慎！会重写历史）
git filter-branch –force –index-filter \\
'git rm –cached –ignore-unmatch CLAUDE.md' \\
–prune-empty — –all
# 修改文件内容后强制推送
git push –force –all

记住：清理历史能救代码，救不了你当时的手贱。密钥这种东西，轮换比道歉有用。

小结

最后总结三句：约束写明白，上下文给足，别让它猜。

你让 AI 猜需求的样子，像极了让对象猜心思——猜对了你惊喜，猜错了你生气。可人家本来就没义务会读心术啊。

CLAUDE.md 写得好，AI 是你最省心的同事；写得不好，它就是你最会甩锅的队友。选哪个，你自己定。

P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，传送门https://blog.csdn.net/H1727548