CLAUDE.md：为AI编程助手定制项目专属开发规范

1. 项目概述为什么你的 AI 助手需要一份“入职手册”如果你用过 Claude Code、Cursor 或者 GitHub Copilot大概率有过这样的体验你让它帮你写个函数它吭哧吭哧给你生成了一堆代码乍一看还行但仔细一瞧包管理器用的是npm而你的项目明明用的是pnpm文件路径乱放完全无视你精心设计的src/目录结构甚至它可能会自作主张地引入一些你项目里根本不存在的依赖或者使用已经被废弃的 API。这种“幻觉”和“不听话”的感觉是不是让你觉得 AI 助手像个刚入职、对公司规矩一无所知的新人问题的根源在于AI 模型虽然强大但它对你这个“具体项目”的上下文一无所知。它不知道你的技术栈偏好、项目结构约定、代码风格规范更不知道那些只有项目老手才懂的“潜规则”和“天坑”。CLAUDE.md文件就是为解决这个问题而生的。你可以把它理解为给 AI 助手的一份“项目专属入职手册”或“开发规范白皮书”。它的核心目的不是教 AI 怎么写代码这它已经很擅长了而是告诉它“在我们这个项目里代码应该‘这样’写。”awesome-claude-md这个项目正是这样一个宝藏仓库。它不是一个教你如何写 Prompt 的教程而是一个实打实的、开箱即用的最佳实践集合。它收集了 GitHub 上众多高质量开源项目里经过实战检验的CLAUDE.md文件并按语言Python、TypeScript、框架Next.js、Vue、Spring Boot和场景Monorepo、微服务、CLI工具分门别类。无论你是前端、后端、全栈还是正在开发桌面应用、浏览器插件你几乎都能在这里找到一个高度适配的模板复制、微调几分钟内就能让你的 AI 助手从“愣头青”变成“懂规矩的老兵”。接下来我将从一个深度使用者的角度为你彻底拆解如何利用好awesome-claude-md并分享我踩过坑后总结出的、让CLAUDE.md效力倍增的独家心法。这篇文章适合所有正在或打算使用 AI 编程助手的开发者无论你是想提升日常开发效率还是希望在新项目中建立规范的 AI 协作流程。2. 核心思路拆解从“模糊要求”到“精确指令”的范式转变在深入模板之前我们必须先扭转一个思维定势我们不是在向一个“人”描述需求而是在为一个“确定性有限但学习能力极强的工具”编写配置。这决定了CLAUDE.md的写作哲学与写给人看的README.md截然不同。2.1 原则一具体化杜绝模糊形容词这是最重要也是最容易被忽视的原则。AI 无法理解“高质量”、“优雅”、“简洁”这类主观形容词的具体标准。错误示例“请编写高性能、可读性强的代码。”问题“高性能”指什么是算法复杂度 O(n) 以下还是减少 DOM 操作“可读性强”又是什么AI 会陷入猜测。正确示例## 代码规范 - **函数长度**单个函数不超过 50 行非空行。 - **命名**组件使用 PascalCase工具函数使用 camelCase常量使用 UPPER_SNAKE_CASE。 - **错误处理**所有异步操作必须使用 try-catch 包裹并记录错误日志到 Sentry。 - **禁止**禁止使用 any 类型禁止在 React 函数组件中直接修改 state必须用 setState。为什么有效每一条都是客观、可验证的。AI 在生成代码时可以逐条对照检查。2.2 原则二项目特异性只说“人无我有”的规则不要浪费宝贵的上下文窗口去写 AI 已经知道或者搜索引擎能查到的通用知识。比如不需要解释“什么是 React Hooks”或“如何安装 Python”。CLAUDE.md的价值在于封装你这个项目独一无二的“上下文”。应该写什么技术栈选型与版本Node.js 18,Python 3.11,Next.js 14 (App Router),Prisma 5.x。这能防止 AI 使用旧版本或不被支持的语法。项目独有的目录结构API 路由统一放在 /src/app/api/[route]/route.ts工具类函数放在 /src/lib/utils.ts静态资源在 /public/assets/。团队/个人编码习惯导入顺序React 库 - 第三方库 - 本地模块使用双引号而非单引号。“天坑”与禁忌本项目使用 pnpm绝对不要生成 npm 或 yarn 的命令数据库连接字符串从环境变量DATABASE_URL读取不要硬编码在 Server Components 中禁止使用useState和useEffect。2.3 原则三以“行动指令”为核心而非“知识描述”CLAUDE.md的本质是一份操作指南。它的句式应该以祈使句或规则陈述句为主。知识描述低效“我们使用 ESLint 和 Prettier 进行代码检查和格式化。ESLint 配置继承了antfu/eslint-config。”行动指令高效## 开发命令 - 格式化代码运行 pnpm format - 检查代码问题运行 pnpm lint - 提交代码前必须确保 pnpm lint 通过。 ## 代码风格 - 遵循项目中的 .eslintrc 和 .prettierrc 配置。 - 不要修改这些配置文件的规则。2.4 原则四结构化与可扫描性AI 在读取长文本时也会关注结构。一个清晰的结构能帮助它快速定位相关信息。awesome-claude-md提供的“万能模板”就是一个极佳的起点# CLAUDE.md ## 项目概述 [一句话说清项目是干嘛的] ## 技术栈 [精确到版本号的语言、框架、核心库] ## 项目结构 [关键目录的用途只写反直觉或重要的] ## 开发规范 [具体的、可执行的编码和提交规则] ## 构建与部署 [从安装依赖到上线的完整命令链] ## 注意事项 (最重要) [新人最易踩的坑、历史遗留问题的处理方式、与常规实践不同的地方]这个结构像一份检查清单确保你覆盖了所有关键维度。在实际使用中我强烈建议把“注意事项”部分放在最前面或加粗强调因为这里面的信息往往能避免最严重的错误。3. 实操指南手把手打造你的第一份高威力 CLAUDE.md理论说再多不如动手做一遍。我们以创建一个Next.js 14 (App Router) TypeScript Tailwind CSS的全栈项目为例演示如何利用awesome-claude-md快速生成并优化一份专属配置。3.1 第一步寻找并复制基础模板打开awesome-claude-md仓库进入by-framework/nextjs/目录。你会发现这里通常会有多个模板比如CLAUDE.md(基础版)、CLAUDE.comprehensive.md(详细版)。对于新手我建议从基础版开始。复制模板直接将by-framework/nextjs/CLAUDE.md的内容复制到你项目根目录下的同名文件中。快速浏览模板内容通常已经具备了良好的结构包含了 Next.js 项目的常见配置如对 App Router 的支持、对 Server/Client Components 的区分提示等。3.2 第二步个性化改造注入项目灵魂现在打开你刚创建的CLAUDE.md开始进行关键的“本地化”改造。这是决定其效果的核心步骤。a. 修正技术栈与版本找到“技术栈”部分根据你的package.json进行精确更新。## 技术栈 - **运行时**: Node.js 20.12.0 (使用 .nvmrc 或 engines 字段锁定) - **前端框架**: Next.js 14.2.5 (使用 App Router**不使用** Pages Router) - **语言**: TypeScript 5.4.5 (严格模式 strict: true) - **样式**: Tailwind CSS 3.4.0使用 tailwindcss/forms 插件 - **ORM**: Prisma 5.10.2 (数据库PostgreSQL 16) - **包管理器**: pnpm 8.15.6 (本项目使用 pnpm-workspace.yaml**禁止**使用 npm 或 yarn) - **身份验证**: NextAuth.js 5.0.0-beta.18注意明确声明版本和“禁止”事项能强力约束 AI 的行为避免它引入不兼容的 API 或错误的包管理命令。b. 定义清晰的项目结构在“项目结构”部分不要罗列所有文件夹只解释那些容易让人困惑或具有特殊约定的。## 项目结构 - /src/app/: App Router 核心目录。每个子目录对应一个路由。 - (dashboard)/, (auth)/: 路由组用于组织路由但不影响 URL 路径。 - api/: API 路由。内部结构为 /api/[route]/route.ts。 - /src/components/: 共享的 React 组件。 - ui/: 使用 shadcn/ui 构建的基础 UI 组件 (如 Button, Card)。 - shared/: 业务相关的共享组件。 - /src/lib/: 工具函数、配置、常量。 - prisma.ts: Prisma Client 单例。 - utils.ts: 通用工具函数。 - /public/: 静态资源。图片请放入 /public/images/。提示这种结构化的描述能帮助 AI 在生成新文件时准确地知道该放在哪里。c. 制定铁律般的开发规范这是CLAUDE.md的“肌肉”部分。规则要具体到可以自动检查。## 开发规范 ### 组件与代码 1. **组件定义**: 优先使用 export default function ComponentName() 形式。 2. **Props 类型**: 使用 interface 定义 Props并添加 JSDoc 注释。 3. **状态管理**: - 简单的状态使用 React useState。 - 复杂的、跨组件的状态使用 Zustand (store 在 /src/stores/)。 - **禁止**在 Server Components 中使用任何状态 Hook。 4. **数据获取**: - 在 Server Components 中直接使用 async/await 获取数据。 - 在 Client Components 中使用 SWR 进行客户端数据获取和缓存。 5. **样式**: - 使用 Tailwind CSS 工具类。**禁止**在组件中编写 style{{}} 内联样式。 - 复杂的样式组合请提取到 /src/lib/utils.ts 中的 cn() 函数。 6. **错误边界**: 所有数据获取操作必须用 try-catch 包裹并使用 console.error 和 Sentry 记录。 ### 提交与协作 1. **提交信息**: 遵循 Conventional Commits 格式 (feat:, fix:, docs:, style:, refactor:, test:, chore:)。 2. **分支策略**: 新功能从 develop 分支切出 feat/xxx 分支修复 Bug 切出 fix/xxx 分支。 3. **代码检查**: 提交前必须运行 pnpm lint (ESLint) 和 pnpm type-check (TypeScript 类型检查)。d. 填充最重要的“注意事项”这部分是精华来自血泪教训。你可以通过回答以下问题来填充最近一次构建失败是因为什么- “本地开发时需要先运行pnpm db:generate生成 Prisma Client。”新同事最常问的问题是什么- “环境变量文件是.env.local不是.env。数据库连接字符串变量名是DATABASE_URL。”AI 最容易在这里犯什么错- “生成 API 路由时请确保是route.ts而不是api.ts并且使用export async function GET/POST(request: NextRequest)格式。”## 注意事项 (务必遵守) - **环境变量**: 复制 .env.example 到 .env.local 并填写。**切勿**将 .env.local 提交到 Git。 - **数据库**: 1. 修改 prisma/schema.prisma 后**必须**运行 pnpm db:generate。 2. 运行 pnpm db:push 将更改同步到开发数据库。 - **Next.js 特定**: - 在 app/ 目录下的 page.tsx 默认是 Server Component。如果需要交互性必须在文件顶部显式添加 use client。 - 图片优化使用 next/image 组件不要用普通的 img。 - **绝对不要**在 Server Component 中导入或使用 useState, useEffect, useContext 等客户端 Hook。 - **样式冲突**: 如果引入第三方组件库样式冲突在 tailwind.config.ts 的 content 字段中添加对应路径。3.3 第三步测试与迭代写完CLAUDE.md后不要以为就结束了。你需要验证它的效果。基础测试在项目中打开 AI 助手如 Cursor 的 Chat 或 Claude Code 的编辑器问它一些项目相关的问题“我们用什么包管理器”“如何创建一个新的 API 路由” 观察它的回答是否严格遵循了CLAUDE.md的约定。实战测试给它一个具体的编码任务比如“在/src/app/api/users/下创建一个 GET 路由用于查询用户列表使用 Prisma 并分页。” 检查生成的代码文件路径是否正确是否使用了 Prisma Client 的正确导入方式分页逻辑是否符合项目惯例有没有使用被禁止的any类型迭代优化如果 AI 在某个地方“犯错”了比如又用了npm install不要只是手动纠正代码。立刻回到CLAUDE.md在“技术栈”或“注意事项”里把这条规则写得更强硬、更醒目。例如加上“重申本项目使用且仅使用 pnpm。所有package.json操作命令都必须以pnpm开头。生成任何安装、卸载、运行命令时请务必使用 pnpm。”经过这样几轮“训练”你的CLAUDE.md就会越来越精准AI 助手也会变得越来越“懂你”。4. 进阶技巧从“好用”到“精通”的深度玩法当你熟练使用基础模板后可以尝试以下进阶技巧让你的 AI 协作水平再上一个台阶。4.1 为不同场景创建多个“角色”配置一个复杂的项目可能包含前端、后端、脚本等不同部分。你可以创建多个CLAUDE-*.md文件让 AI 在不同上下文中扮演不同“角色”。CLAUDE.backend.md: 专注于 API 设计、数据库操作、业务逻辑验证。可以强调“所有 API 响应必须遵循统一的 JSON 格式{ success: boolean, data?: any, error?: string }”。CLAUDE.frontend.md: 专注于组件设计、状态管理、用户体验。可以强调“所有交互组件必须提供加载状态和错误状态 UI。”CLAUDE.script.md: 专注于数据迁移、批量处理等一次性脚本。可以强调“脚本必须是幂等的可以安全地多次运行。需要包含详细的日志输出。”在 Cursor 中你可以通过指令来引用特定配置。在 Claude Code 中虽然通常只认根目录的CLAUDE.md但你可以通过在该文件中用条件注释来划分章节引导 AI 根据当前打开的文件类型聚焦相关部分。4.2 利用“真实案例”章节进行高阶学习awesome-claude-md的“真实案例”部分是金矿。不要只是看一眼要深入分析。比如看看workers-sdkCloudflare 的 monorepo的配置它如何严格约束工具链看看basic-memory项目它如何规定“编辑前必须完整读取文件”的 Code/Test/Verify 循环这些来自顶级项目的实践能教你如何为大型、复杂的工程制定 AI 协作规范。4.3 将 CLAUDE.md 与其它工具集成CLAUDE.md不是孤立的它可以成为你开发生态的一部分。与 Linter 结合在CLAUDE.md中引用的规则如“函数不超过 50 行”应该在 ESLint 或 Biome 等工具中有对应的配置。这样AI 生成的代码能通过CLAUDE.md进行“软约束”再通过 Linter 进行“硬检查”双重保障代码质量。与代码片段Snippets结合对于 AI 容易出错的固定模式比如创建 Prisma 模型你可以在CLAUDE.md中给出最佳实践示例同时在编辑器中配置对应的代码片段。AI 生成大体框架你用片段快速填充细节效率更高。作为团队 onboarding 文档一份优秀的CLAUDE.md本身就是一个极佳的项目入门指南。新成员通过阅读它能快速掌握项目的技术栈、结构和规范减少沟通成本。5. 避坑指南与常见问题排查在实际使用中你可能会遇到一些典型问题。以下是我总结的排查清单5.1 问题AI 似乎完全忽略了 CLAUDE.md 的内容。可能原因 1文件位置或名称错误。排查确保文件名为CLAUDE.md全大写并且位于项目的根目录下。对于 Cursor有时也支持放在.cursor/目录下。解决检查文件路径和大小写。重启你的 AI 助手或编辑器。可能原因 2上下文窗口被占满。排查CLAUDE.md文件是否过于冗长AI 有上下文长度限制如果文件太大后面的内容可能不会被纳入考虑。解决精简你的CLAUDE.md删除所有通用知识和冗余描述只保留最核心、最独特的规则。优先保证“注意事项”和“开发规范”在靠前的位置。可能原因 3AI 模型版本或设置问题。排查确认你使用的 AI 助手如 Claude Code支持并启用了项目级指令功能。解决查阅对应工具的官方文档确认CLAUDE.md是其认可的配置方式。5.2 问题AI 遵守了大部分规则但在某些细节上总是犯错。可能原因规则描述不够具体或存在歧义。案例你写了“使用正确的错误处理”但 AI 仍然生成了没有try-catch的异步代码。解决将规则具体化、场景化。改为“所有async函数无论是 API 路由还是工具函数都必须使用try-catch块包裹。在catch中必须使用console.error打印错误并根据情况返回统一的错误响应或抛出经过封装的AppError。”可能原因规则之间存在冲突或未覆盖边缘情况。解决仔细审查你的规则。例如如果既要求“使用函数式组件”又要求“使用类组件生命周期”AI 就会困惑。确保规则的一致性。5.3 问题不同 AI 助手Claude, Cursor, Copilot对 CLAUDE.md 的支持程度不同。现状CLAUDE.md最初是为 Claude Code 设计的但概念已被广泛接受。Cursor 有类似的.cursorrules文件GitHub Copilot 有copilot-instructions.md。它们的语法和功能可能略有差异。策略以CLAUDE.md为核心先撰写一份内容精良、技术栈描述清晰的CLAUDE.md。这是项目信息的核心载体。为不同工具创建适配文件如果需要可以在根目录创建.cursorrules其内容可以大部分引用或简化自CLAUDE.md。例如在.cursorrules中写“请参考本项目根目录下的CLAUDE.md文件了解详细规范。特别强调使用 pnpm禁止 any 类型。”关注社区进展awesome-claude-md项目计划提供其他工具的模板可以保持关注。5.4 如何评估一份 CLAUDE.md 的好坏一个简单的自检清单[ ]长度能否在一分钟内读完理想 50-200 行[ ]特异性换到另一个同类型项目这份文件是否大部分需要重写[ ]可操作性每一条规则能否被毫无歧义地执行或验证[ ]问题预防它是否明确列出了已知的、AI 容易犯的“经典错误”[ ]更新频率当项目技术栈或核心规范变更时你是否会同步更新它一份好的CLAUDE.md应该像一份优秀的 API 文档简洁、准确、无二义性让使用者无论是人还是 AI都能清晰地知道“在这里事情该怎么做”。6. 总结与个人实践心得经过在多个个人和团队项目中的实践我深刻体会到投资时间编写一份好的CLAUDE.md其回报率远超预期。它不仅仅是一个让 AI 更“听话”的配置文件更是一个强迫你梳理项目规范、沉淀团队知识的过程。我个人的工作流已经变成了这样启动任何新项目在初始化完技术栈后第一件事不是写代码而是去awesome-claude-md找对应模板快速搭建起CLAUDE.md的骨架。然后在开发过程中每当 AI 助手给出了一个不符合预期的答案或者我手动纠正了一个重复出现的错误模式我的第一反应不是烦躁而是兴奋“太好了又发现了一条需要写入CLAUDE.md的规则” 这份文件就这样随着项目一起生长、迭代最终成为项目最重要的“元文档”之一。最后分享一个小心得不要试图在第一天就写出一份完美的CLAUDE.md。它应该是一个“活文档”。从一个简单的模板开始在真实的编码协作中不断收集“故障案例”然后用一条条具体的规则去修复这些故障点。几周之后你就会拥有一份真正为你和你的 AI 伙伴量身定制的、威力强大的协作协议。你会发现你花在纠正 AI、解释上下文上的时间越来越少而真正用于创造性编程的时间越来越多。这或许就是人机协同编程当下最切实的进化路径。