引言：痛点在哪里？
当你用 Claude Code 参与第三方项目——无论是开源贡献、接手维护遗留代码，还是帮朋友修复 Bug，会不会遇到这些问题？
- AI 不了解项目已有规范，按照自己习惯乱写，代码风格和原有项目格格不入
- AI 上来就重构，把整个目录结构都改了，提 PR 被维护者礼貌打回
- AI 强行把 JavaScript 转成 TypeScript，破坏了原项目的技术选型约定
- 你想手动写一份规范告诉 AI 该怎么做，但又懒得读遍所有配置文件
问题的本质：自己新建项目可以从零定义规范，但第三方项目已有规范，你需要让 AI "入乡随俗"，而不是"改天换地"。
核心原则：新项目立规矩，第三方守规矩
| 项目类型 | 核心目标 | CLAUDE.md 作用 | 写作方式 |
|---|---|---|---|
| 从零新建项目 | 建立统一编码规范 | 定义规则，指导 AI 从零开始 | 手动完整编写 |
| 第三方已有项目 | 尊重现有约定，只做最小修改 | 传递规则，让 AI 遵守现有约定 | AI 自动扫描生成，人工微调 |
高效工作流：三步搞定
这是实践下来最高效的流程，比手动写快 10 倍：
第一步：进入项目，让 AI 自动扫描
cd /path/to/your/third-party-project
直接给 AI 发这个 Prompt：
请帮我基于当前项目生成 CLAUDE.md 规范草案：
1. 扫描项目根目录所有配置文件，包括 package.json、框架配置文件（next.config.js、vite.config.ts）、代码检查配置（.eslintrc.*、biome.json）、格式化配置（.prettierrc.*、.editorconfig）以及 .gitignore。
2. 分析 src 目录的代码结构、命名风格、技术选型
3. 从 package.json 提取所有常用开发命令
4. 基于你发现的现有规范，生成一份完整的 CLAUDE.md
5. 重点明确：哪些目录可以修改，哪些文件绝对不要碰
Claude 会自动读取项目根目录下的配置文件（如 package.json、.eslintrc 等），并结合对 src 目录下若干源文件的抽样分析来推断项目风格。
第二步：AI 输出草案，你做四项检查
AI 生成之后，你只需要花 1-2 分钟检查这四件事：
| 检查项 | 检查什么 | 如何调整 |
|---|---|---|
| 技术栈对不对 | AI 有没有认错框架？ | 错了改过来，比如把 Vue 改成 React |
| 命令对不对 | 启动、构建、测试命令一致吗？ | 跟 package.json 对一下，错了改 |
| 风格对不对 | 缩进/分号/引号符合原项目吗？ | 打开任意源文件一看便知 |
| 范围对不对 | 哪些能改哪些不能碰，划清了吗？ | 明确你的任务边界，加上限制 |
第三步：人工微调 → 保存 → 开始干活
AI 负责生成初稿框架，但你需要逐项核对关键规范（缩进、引号、命名）是否与项目真实代码一致。
完整模板参考
文件位置：将生成的 CLAUDE.md 放在项目根目录下。如果你希望更精细地管理 AI 行为，也可以使用 .claude/ 目录（参见官方文档）。
以下是 AI 生成后，经过优化的标准模板，你可以直接用：
# CLAUDE.md - 第三方项目贡献规范
## 基本原则（必须遵守）
1. **先学习，后修改**：修改任何代码前，先阅读相关文件理解上下文
2. **尊重原有风格**：严格遵循原项目现有的代码风格、命名规则、注释习惯
3. **最小改动**：只改需要修复的问题，不重构不相关代码，不清理"看起来不好"的地方
4. **不碰基础设施**：不要修改版本号、CHANGELOG、LICENSE，由项目维护者处理
---
## 项目信息
**项目名称**: [填入项目名称]
**原项目仓库**: [https://github.com/xxx/xxx](填入原仓库链接)
**技术栈分析**（从 package.json 提取）:
- 框架: React 18
- 语言: TypeScript / JavaScript
- 构建工具: Vite / Webpack
- 包管理器: pnpm / npm / yarn
**常用命令**:
```bash
npm install # 安装依赖
npm run dev # 启动开发服务器
npm run build # 生产构建
npm test # 运行测试
npm run lint # ESLint 检查
```
代码风格对齐
项目已有配置，请严格遵循:
- ESLint: ✅ 已有 .eslintrc，生成代码必须符合规则
- Prettier: ✅ 已有 .prettierrc，按此格式化
- 缩进: [检测结果，例如 2 空格]
- 分号: [检测结果，是/否]
- 引号: [检测结果，单/双]
命名规则（观察原项目总结）:
- 文件: kebab-case (
user-profile.tsx) - 组件: PascalCase (
UserProfile) - 函数/Hooks: camelCase (
useLocalStorage) - 常量: UPPER_SNAKE_CASE (
MAX_RETRY_COUNT)
目录结构
src/
├── components/ # 通用组件
├── hooks/ # 自定义 Hooks
├── utils/ # 工具函数
├── assets/ # 静态资源
└── ...
允许修改范围:
src/components/src/utils/
通常禁止修改范围（除非当前任务明确要求升级或修复依赖）：
- 锁定文件：
package-lock.jsonyarn.lockpnpm-lock.yaml - 构建产物：
build/dist/node_modules/ - 项目元信息：
LICENSECHANGELOG.md
禁止行为
- 不要大规模重构原项目代码结构
- 不要把原项目的 JavaScript 全改成 TypeScript（除非任务就是这个）
- 不要修改原项目的依赖版本（除非任务就是升级依赖）
- 不要删除原作者注释和版权信息
- 不要添加原项目不需要的依赖
---
## 场景化变种
### 场景一：只改小 Bug，用极简版
如果你只是修复一个小问题，不需要长篇大论：
```markdown
# CLAUDE.md
## 基本原则
这是第三方项目，请严格遵守：
1. 先阅读现有代码，理解逻辑再修改
2. 完全遵循原项目的代码风格，不要改变命名格式
3. 只修复问题本身，不重构不相关代码
4. 不要修改版本号、CHANGELOG、lock 文件
## 常用命令
npm install
npm run dev
npm test
场景二：原项目已有贡献指南
如果原项目根目录已经有 CONTRIBUTING.md，加上这一段：
## 贡献指南
原项目已有 CONTRIBUTING.md 文件，所有贡献必须严格遵守其中约定：
@see ./CONTRIBUTING.md
场景三：只修复特定 Issue
如果你的目标很明确，只修复某个问题，加上范围限制：
## 当前任务范围
只修复 Issue #123 描述的问题：
- 问题描述：表单提交时不验证必填项
- 修复目标：修复验证逻辑，保持现有 API 不变
- 不允许：修改表单组件的整体架构
- 约束细则：保持组件对外导出的 Props 接口完全不变，不引入新的状态管理库或重构组件层级。
常见陷阱 & 注意事项
不要这样做
- 不要让 AI 从零手写：AI 不知道原项目用 2 空格还是 4 空格，必须先扫描
- 不要保留矛盾规则：如果你说"遵循原项目"又说"用 2 空格"，AI 会混乱
- 不要放开所有修改权限：明确告诉 AI 哪些不能碰，避免事故
- 不要忘记提交：CLAUDE.md 要提交到项目分支，方便后续协作
最佳实践
- AI 干体力活，人干判断活：扫描、阅读、整理交给 AI，对错、范围交给人
- 渐进完善：一开始不需要完美，随着修改深入发现问题再补充规则
- 提交进分支：把 CLAUDE.md 加到你的 PR 分支，其他协作者也能受益
- 建议随 PR 保留：如果该 CLAUDE.md 精准描述了项目规范且未泄露隐私，建议一并提交到 PR 分支。这对后续维护者使用 AI 工具极有裨益。
效果对比
| 方式 | 耗时 | 准确率 |
|---|---|---|
| 手动阅读配置，从头编写 | 10-15 分钟 | 容易漏看配置，出错率高 |
| AI 扫描生成 + 人工校验 | 1-2 分钟 | AI 不会漏，人只做判断，准确率高 |
总结：记住这个口诀
- 让 AI 扫 —— 别自己读，交给 AI
- 让 AI 写 —— AI 比你记得全
- 你只改 —— 对错你判断，范围你划清
这个方法我在多个开源贡献和接手遗留项目中用过，屡试不爽。它解放了你的时间，让你专注解决问题本身，而不是给 AI 写说明书。
如果你有更好的实践，欢迎交流讨论
