尧图网页设计 
1. 项目概述为什么你需要一份 CLAUDE.md如果你最近在折腾 AI 编程助手比如 Cursor、Claude Code、Codex或者各种基于 AI 的 Agents 工具那你大概率已经不止一次地听到过CLAUDE.md这个名字了。这玩意儿乍一看就是个普通的 Markdown 文件但它在实际工作流里扮演的角色远比你想象的要重要。简单来说CLAUDE.md是你和 AI 助手之间的一份“项目宪法”或“协作手册”。它不是一个强制性的配置文件而是一个高度定制化的上下文说明文档专门用来告诉 AI“在这个项目里我是谁我要做什么我的代码应该长什么样以及有哪些规矩必须遵守。”为什么这变得如此关键因为现在的 AI 工具能力越来越强但“个性”和“背景知识”却千差万别。你直接用 Claude 3.5 Sonnet 问一个问题和你在 Cursor 里带着项目上下文问一个问题AI 给出的答案可能天壤之别。CLAUDE.md的核心价值就在于它能将这种“项目上下文”固化、标准化确保无论你切换分支、隔了几天再打开项目还是把项目分享给队友AI 都能基于同一套高质量、高一致性的背景知识来为你工作。这直接决定了 AI 生成代码的准确性、符合项目规范的程度以及你后期维护的心智负担。对于任何希望将 AI 深度集成到开发流程中的开发者或团队而言精心维护一份CLAUDE.md是提升效率、保证质量的基石性工作。2. 核心思路与设计哲学2.1 从临时对话到持久化上下文思维模式的转变在使用 AI 编程助手的早期我们习惯于“即问即答”的模式遇到一个错误把报错信息贴进去想写个函数用自然语言描述一下需求。这种方式的问题在于每次对话都是孤立的。AI 不知道你这个项目的技术栈选型是用 React 还是 Vue、代码风格是 Airbnb 规范还是 Standard、甚至是目录结构的特殊约定。于是你不得不花费大量口舌在每次对话中重复这些基础信息或者忍受 AI 生成一些风格迥异、甚至与项目架构冲突的代码。CLAUDE.md的出现标志着我们从“临时对话”转向“持久化上下文”管理。它的设计哲学很明确一次性定义全局生效。你应该把项目中所有静态的、共识性的、基础性的信息都沉淀到这个文件里。这包括技术栈、架构说明、代码规范、API 设计原则、测试策略等。这样AI 在分析你的需求或处理你的文件时会首先加载这份“背景知识”从而使其输出从一开始就建立在正确的基础上。这不仅仅是省去了重复输入的时间更重要的是大幅减少了因上下文缺失导致的“方向性错误”让协作从一开始就走在正确的轨道上。2.2 与 .cursorrules、agents.md 的定位辨析在讨论CLAUDE.md时常会与.cursorrules和agents.md这两个文件混淆。理解它们的区别是有效利用它们的关键。.cursorrules: 这是Cursor IDE特有的配置文件。它的定位更偏向于“项目级设置与自动化规则”。你可以在这里定义项目级别的快捷键、代码片段、文件生成模板甚至是一些简单的自动化脚本。例如规定所有新生成的组件文件必须放在src/components/下并且自动导入必要的样式文件。.cursorrules的作用域和生效机制由 Cursor 编辑器本身控制它更“主动”更像是一个项目脚手架和自动化工具。agents.md: 这个文件通常与AI Agent 框架如 LangChain、AutoGPT 或自定义 Agent 系统相关。它用于定义“智能体Agent的行为、能力、目标和约束”。例如在一个自主完成数据抓取和分析的 Agent 项目中agents.md会详细说明 Agent 可以调用哪些工具如浏览器、计算器、它的核心目标是什么、以及它不能做什么如不能访问某些网站。它的内容是指令性的用于驱动一个自主或半自主的 AI 进程。CLAUDE.md: 如前所述它的核心是“项目上下文与知识库”。它不直接触发自动化像.cursorrules也不驱动自主行为像agents.md。它是被动提供信息的。当 AI特别是 Claude 系列模型或在 Cursor 中集成的 AI需要理解你的项目时它会去读取这个文件以此来丰富自己的知识背景从而做出更准确的判断和生成。它的内容是描述性和规范性的。一个简单的类比如果把你的项目比作一个公司那么.cursorrules是公司的行政流程手册规定怎么盖章、报销agents.md是某个特定部门如市场部的 KPI 和行动指南而CLAUDE.md则是公司的企业文化、发展历史、主营业务和核心技术的介绍白皮书是新员工AI入职时必须阅读的材料。2.3 通用性与工具适配性一个常见的误区是认为CLAUDE.md只适用于 Claude 模型或 Cursor。实际上这个命名更多是一种约定俗成源于早期实践者多使用 Claude 模型。其理念和格式是通用的。任何能够读取项目根目录下 Markdown 文件作为上下文的 AI 编程工具都能从中受益。例如GitHub Copilot 虽然没有一个官方的同名文件但你可以通过创建类似PROJECT_CONTEXT.md的文件并在合适的时机通过“”引用或粘贴部分内容来达到类似效果。一些新兴的、支持自定义系统提示词System Prompt的 AI IDE 或插件都可以将CLAUDE.md的内容作为系统提示词的一部分加载。因此维护一份高质量的CLAUDE.md是一项对未来友好的投资。即使你更换 AI 工具或模型这份精心整理的项目知识库其大部分内容依然具有极高的复用价值。3. CLAUDE.md 核心内容架构与撰写指南一份优秀的CLAUDE.md应该结构清晰、信息完备、语言精确。下面我将拆解其核心模块并给出具体的撰写建议和示例。3.1 项目元信息与核心目标这是文件的“开门见山”部分旨在用最精炼的语言让 AI 瞬间抓住项目的本质。项目名称与简介用一两句话说明项目是做什么的。例如“NextCRM- 一个基于 Next.js 14 和 Prisma 构建的现代客户关系管理系统专注于销售流程自动化和客户数据分析。”核心技术与版本明确列出项目的技术栈及其关键版本。这是防止 AI 推荐过时或错误 API 的关键。## 核心技术栈 - **前端**: Next.js 14 (App Router), React 18, TypeScript 5.4, Tailwind CSS 3.4 - **状态管理**: Zustand - **后端/全栈**: Next.js API Routes, Prisma ORM 5.0 - **数据库**: PostgreSQL 15 (通过 Supabase 托管) - **身份验证**: NextAuth.js v5 (Auth.js) - **部署**: Vercel核心目标与原则阐述项目的最高指导原则。例如“本项目的首要目标是开发体验优先和性能最佳实践。所有代码都应易于理解、测试和维护。优先使用服务端组件RSC和服务器操作减少客户端 JavaScript 体积。”注意版本号非常重要。明确告诉 AI “我们使用 Next.js 14 的 App Router”可以避免它生成基于 Pages Router 的代码或者使用已被弃用的 API。3.2 代码风格与规范这是保证生成代码一致性的“法律条文”。不要只说“遵循 Airbnb 规范”要给出本项目具体的、可能与众不同的约定。命名约定文件命名kebab-case(如user-profile.tsx) 还是PascalCase(如UserProfile.tsx)变量/函数camelCase。组件PascalCase。常量UPPER_SNAKE_CASE。TypeScript 接口/类型PascalCase并以I前缀(不推荐) 还是直接命名(如User而非IUser)。导入/导出规范导入顺序先第三方库再内部模块。是否使用/别名默认导出 vs 命名导出组件一律使用命名导出便于重构和 tree-shaking工具函数视情况而定。示例// 好的例子 import { useState } from react; import { cn } from /lib/utils; import { Button } from /components/ui/button; import { User } from prisma/client; // 避免 import React, { useState } from react; // 在 Next.js 14 中不需要显式导入 React代码格式化工具明确项目使用的工具如 Prettier 和 ESLint并指出任何特殊的规则覆盖。例如“本项目使用 Prettier 进行自动格式化所有代码提交前必须通过 ESLint 检查。我们禁用了typescript-eslint/no-explicit-any规则的警告但强烈建议使用更具体的类型。”3.3 目录结构解析与模块约定AI 需要知道文件应该放在哪里以及不同目录的职责。提供清晰的目录树摘要不需要完整的tree输出但需要说明核心目录的用途。## 项目结构/src ├── app/ # Next.js 14 App Router 主要目录 │ ├── (auth)/ # 路由组认证相关页面 │ ├── (dashboard)/ # 路由组主控台页面 │ ├── api/ # API 路由处理程序 │ └── globals.css # 全局样式 ├── components/ # 可复用 React 组件 │ ├── ui/ # 基础 UI 组件 (按钮、输入框等) │ └── shared/ # 业务共享组件 ├── lib/ # 工具函数、配置、客户端第三方库初始化 ├── prisma/ # Prisma schema 和迁移文件 ├── public/ # 静态资源 └── types/ # 全局 TypeScript 类型定义关键约定说明app/api/下的每个子目录都是一个路由必须导出名为GET、POST等的函数。components/ui/下的组件是纯展示组件不应包含业务逻辑或数据获取。lib/下的工具函数必须是纯函数或仅包含轻量级副作用且需要良好的错误处理。3.4 数据层与 API 设计模式这是 AI 生成数据操作代码的蓝图。描述越清晰生成的 Prisma 查询或 API 路由就越准确。数据库与 ORM 模式简要说明核心数据模型之间的关系。可以附上 Prisma Schema 中关键模型的定义片段。// 来自 prisma/schema.prisma 的片段 model User { id String id default(cuid()) email String unique name String? posts Post[] createdAt DateTime default(now()) }API 设计原则响应格式统一使用{ success: boolean, data?: T, error?: string }的包装结构。错误处理使用 HTTP 状态码并在lib中定义统一的错误类。数据验证使用 Zod 进行输入验证模式定义在lib/validations目录下。示例 API 模板// app/api/users/route.ts 的模板 import { NextRequest, NextResponse } from next/server; import { createUserSchema } from /lib/validations/user; import { prisma } from /lib/prisma; import { handleApiError } from /lib/api-error; export async function POST(request: NextRequest) { try { const body await request.json(); const validatedData createUserSchema.parse(body); // Zod 验证 const user await prisma.user.create({ data: validatedData }); return NextResponse.json({ success: true, data: user }, { status: 201 }); } catch (error) { return handleApiError(error); // 统一错误处理 } }3.5 组件设计体系与 UI 库集成如果使用了特定的 UI 库如 Shadcn/ui, MUI, Chakra或有一套内部组件规范必须在此说明。UI 库与主题“本项目使用 Shadcn/ui 作为组件库基础所有基础交互组件Button, Dialog, Form 等应从/components/ui导入禁止手动编写这些组件的原始 HTML。”样式方案“使用 Tailwind CSS 进行样式编写。颜色、间距、字体等均遵循tailwind.config.js中的主题扩展定义。自定义工具类放在src/lib/utils.ts的cn函数中用于条件合并 className。”新组件创建指南在components/下创建PascalCase命名的目录。主组件文件为index.tsx类型定义放在types.ts。如果组件复杂相关的子组件、钩子、样式应放在同一目录下。必须编写 JSDoc/TSDoc 注释说明组件 Props 和用途。3.6 测试、部署与开发工作流让 AI 了解项目的质量保障和交付流程。测试策略“单元测试使用 Vitest 和 React Testing Library测试文件与被测文件同名后缀为.test.ts或.test.tsx放在同一目录。组件测试重点在于用户交互而非实现细节。”环境变量“敏感配置通过.env.local管理其模板为.env.example。AI 在生成涉及环境变量的代码时如数据库连接应使用process.env并提示变量名但不要写出真实值。”Git 工作流“遵循 Conventional Commits 规范。feat:用于新功能fix:用于修复chore:用于工具变更等。”4. 高级技巧与动态上下文管理一份静态的CLAUDE.md是基础但要发挥最大威力需要一些进阶策略。4.1 模块化与引用避免单一巨型文件当项目非常庞大时一个CLAUDE.md文件可能变得臃肿不堪。此时可以采用模块化方法。创建docs/或.claude/目录在项目根目录下建立专门存放上下文文档的目录。拆分文件ARCHITECTURE.md: 详细架构设计。API_GUIDELINES.md: 详细的 API 设计规范。FRONTEND_CONVENTIONS.md: 前端特定规范。DATABASE.md: 数据库设计与优化指南。在主CLAUDE.md中引用主文件变得非常精简只包含最高级别的概述和到详细文档的链接。# 项目综合上下文 关于本项目的完整上下文请参阅以下文档 - [架构概述](./docs/ARCHITECTURE.md) - [API 设计指南](./docs/API_GUIDELINES.md) - [前端开发规范](./docs/FRONTEND_CONVENTIONS.md) - [数据库指南](./docs/DATABASE.md)大多数先进的 AI 工具如新版 Cursor能够跟随这些链接并读取链接文件的内容从而构建完整的上下文。这保持了主文件的简洁同时提供了深度信息的入口。4.2 结合.cursorrules实现智能触发虽然CLAUDE.md是被动提供上下文但我们可以通过 Cursor 的.cursorrules让它“主动”起来。例如你可以在.cursorrules中设置规则当用户创建新组件或 API 路由时自动引用CLAUDE.md中的相关模板或规范。// .cursorrules 示例片段 { rules: [ { when: creating a file matching **/app/api/**/route.ts, then: suggest using the API handler template from CLAUDE.md and remind about error handling and validation with Zod. }, { when: creating a file matching **/components/**/index.tsx, then: remind to check the component design guidelines in CLAUDE.md, especially about props typing and JSDoc comments. } ] }这样在你实际编码时Cursor 不仅会读取CLAUDE.md的全局背景还会在特定操作下给出更具针对性的提示形成“全局背景 场景化提示”的双重保障。4.3 针对不同任务的上下文聚焦AI 的上下文窗口是有限的。虽然CLAUDE.md提供了全局视图但在处理具体任务时你可能希望 AI 更专注于某个方面。方法一对话中引用在向 AI 提问时可以明确指出“请参考CLAUDE.md中关于 API 设计的原则”或“按照CLAUDE.md的组件规范修改这个文件”。这能引导 AI 优先调用相关部分的记忆。方法二创建任务专属提示文件对于非常复杂或重复的任务可以创建一个独立的TASK_SPECIFIC.md文件。例如在重构一个大型模块前先写一份REFACTOR_PLAN.md详细说明重构目标、边界、不能破坏的接口等然后让 AI 同时参考这个文件和CLAUDE.md。任务结束后可以将REFACTOR_PLAN.md中有长期价值的部分反向合并到CLAUDE.md中。5. 维护、迭代与团队协作实践CLAUDE.md不是一份写完后就可以束之高阁的文档。它应该是一个“活文档”随着项目一起成长。5.1 版本控制与更新时机纳入 Git 管理毫无疑问CLAUDE.md及其拆分出的文档都应该和其他源代码一样接受版本控制。它的每一次修改都应该有清晰的 Commit Message说明为什么更新例如“更新 CLAUDE.md增加对新的数据获取模式useSWR的规范说明”。关键的更新时机技术栈升级当 Next.js、React、Prisma 等主要依赖升级大版本时。架构重大调整如从 REST API 迁移到 GraphQL或引入新的状态管理方案。规范新增或变更团队制定了新的代码规范或发现原有规范存在普遍性问题时。新人入职后新成员在熟悉项目过程中如果反复遇到因CLAUDE.md缺失信息而导致的 AI 误判这正是补充文档的好机会。5.2 团队内的推广与共识建立在团队中推行CLAUDE.md最大的挑战不是技术而是习惯。以身作则展示价值作为倡导者你首先要在自己的工作中严格使用并维护它。当队友看到你总能快速、准确地让 AI 生成符合要求的代码时自然会产生兴趣。将其纳入 onboarding 流程新成员入职清单中必须包含“阅读并理解CLAUDE.md”这一项。可以安排一个简短的会议由你或技术负责人讲解文档的重点和背后的设计决策。建立轻量的评审机制对CLAUDE.md的修改可以像修改重要配置文件一样要求至少一名其他核心成员进行 Review。这保证了变更的合理性和共识。鼓励“文档驱动开发”在开始一项新功能或重构前鼓励开发者先思考“这部分设计是否需要更新或补充到CLAUDE.md里” 这能将最佳实践及时沉淀下来。5.3 效果评估与持续优化如何知道你的CLAUDE.md是否有效定性指标AI 生成代码的“首次通过率”是否提高生成后无需大改就能直接使用或仅需微调的比例是否增加团队沟通成本是否降低关于“这个应该怎么写”的讨论是否减少了新成员上手速度是否加快定量检查可选可以定期如每两周抽样检查 AI 生成的代码对照CLAUDE.md的规范看符合度如何。不符合的地方是规范没写清楚还是开发者没引导 AI 去读取定期回顾在团队技术例会中可以花 10 分钟快速过一遍CLAUDE.md看看是否有过时的内容或者大家最近是否遇到了因文档缺失而导致的共性问题。6. 常见陷阱、问题排查与实战心得在实际使用和维护CLAUDE.md的过程中你会遇到一些典型问题。这里记录了我踩过的坑和总结出的经验。6.1 常见问题速查表问题现象可能原因解决方案AI 完全忽略CLAUDE.md的内容1. 文件未放在项目根目录。2. AI 工具不支持自动读取该文件。3. 文件格式错误如不是.md后缀。1. 确认文件位于项目根目录。2. 查阅你所用的 AI 工具文档确认其上下文加载机制。在 Cursor 中需确保设置中启用了相关功能。3. 尝试在对话中手动提及或粘贴部分关键内容测试 AI 是否能理解。AI 理解了规范但生成代码仍不符合1. 规范描述过于模糊或存在歧义。2. 上下文中存在冲突的指令如之前的对话历史与CLAUDE.md冲突。3. AI 模型的优先级或“注意力”问题。1. 检查并重写有问题的规范使其更具体、可操作。使用代码示例。2. 开启新的聊天会话确保纯净的上下文始于CLAUDE.md。3. 在提问时更明确地强调规范例如“请严格遵守 CLAUDE.md 中关于组件命名的 PascalCase 规范为这个功能创建一个新组件。”文件过于冗长AI 似乎无法吸收全部信息1. 超出了 AI 模型的上下文窗口限制。2. 信息组织混乱重点不突出。1. 采用4.1节提到的模块化方法拆分文件让主文件只保留最核心、最常用的信息。2. 优化文档结构使用清晰的标题和列表。将“必须遵守”的强规范放在前面将“参考建议”放在后面。团队中不同成员维护的CLAUDE.md副本产生分歧缺乏统一的维护流程和版本控制。1. 立即将CLAUDE.md纳入 Git 管理并且只保留一个权威版本在主分支。2. 建立简单的修改流程如创建 PR 并需他人 Review。3. 在团队内同步丢弃所有本地不一致的副本。6.2 实操心得与独家技巧从“问题日志”开始如果你不知道CLAUDE.md该写什么一个极好的起点是记录下最近一周内你因为 AI 不理解项目背景而不得不反复解释或纠正它的所有问题。这些问题就是你的CLAUDE.md初版的核心内容。多用“正例”慎用“反例”在定义规范时尽量提供“应该怎么做”的正确代码示例。心理学和机器学习都有个现象模型更容易学习你明确展示的模式。过多描述“不要怎么做”有时反而会混淆模型。保持语言精准、中性避免使用“最好”、“可能”这类模糊词汇。使用“必须”、“应该”、“可以”等 RFC 2119 关键词来表述要求的强制程度。例如“组件必须使用命名导出。”“对于简单的状态可以优先使用useState而非 Zustand。”将CLAUDE.md视为“可执行的架构文档”传统的架构图Architecture Diagram是给人看的而CLAUDE.md是同时给人和AI看的架构文档。它的表述应该足够结构化、机器可读以便 AI 能提取出关键约束。这意味着多使用列表、代码块、结构化标题。定期“投喂”与测试不要写完就完事了。定期比如每周找一个项目中的小任务如修复一个简单的 bug添加一个简单的 UI 组件在一个全新的聊天会话中仅依靠CLAUDE.md和任务描述来让 AI 完成。观察其输出这是检验文档质量最直接的方法。根据测试结果迭代文档。处理“规范冲突”有时项目历史遗留代码的风格可能与你在CLAUDE.md中定义的新规范冲突。一个务实的做法是在CLAUDE.md中设立一个“遗留代码区”章节明确指出“在src/legacy/目录下的代码由于其历史原因允许不符合下述规范。但在所有新代码和重构中必须遵循新规范。” 这给了 AI 清晰的边界。维护一份好的CLAUDE.md初期需要一些投入但它带来的长期收益是指数级的。它不仅是你的 AI 助手的使用说明书更是项目知识的核心载体是团队技术决策的活化石也是保证项目在快速迭代中不偏离航向的罗盘。当你和你的团队习惯了这种“文档即代码上下文即生产力”的工作模式后你会发现与 AI 协作不再是碰运气而是一种稳定、高效、可预期的软件开发新常态。 CLAUDE.md：AI编程助手的项目上下文管理手册
1. 项目概述为什么你需要一份 CLAUDE.md如果你最近在折腾 AI 编程助手比如 Cursor、Claude Code、Codex或者各种基于 AI 的 Agents 工具那你大概率已经不止一次地听到过CLAUDE.md这个名字了。这玩意儿乍一看就是个普通的 Markdown 文件但它在实际工作流里扮演的角色远比你想象的要重要。简单来说CLAUDE.md是你和 AI 助手之间的一份“项目宪法”或“协作手册”。它不是一个强制性的配置文件而是一个高度定制化的上下文说明文档专门用来告诉 AI“在这个项目里我是谁我要做什么我的代码应该长什么样以及有哪些规矩必须遵守。”为什么这变得如此关键因为现在的 AI 工具能力越来越强但“个性”和“背景知识”却千差万别。你直接用 Claude 3.5 Sonnet 问一个问题和你在 Cursor 里带着项目上下文问一个问题AI 给出的答案可能天壤之别。CLAUDE.md的核心价值就在于它能将这种“项目上下文”固化、标准化确保无论你切换分支、隔了几天再打开项目还是把项目分享给队友AI 都能基于同一套高质量、高一致性的背景知识来为你工作。这直接决定了 AI 生成代码的准确性、符合项目规范的程度以及你后期维护的心智负担。对于任何希望将 AI 深度集成到开发流程中的开发者或团队而言精心维护一份CLAUDE.md是提升效率、保证质量的基石性工作。2. 核心思路与设计哲学2.1 从临时对话到持久化上下文思维模式的转变在使用 AI 编程助手的早期我们习惯于“即问即答”的模式遇到一个错误把报错信息贴进去想写个函数用自然语言描述一下需求。这种方式的问题在于每次对话都是孤立的。AI 不知道你这个项目的技术栈选型是用 React 还是 Vue、代码风格是 Airbnb 规范还是 Standard、甚至是目录结构的特殊约定。于是你不得不花费大量口舌在每次对话中重复这些基础信息或者忍受 AI 生成一些风格迥异、甚至与项目架构冲突的代码。CLAUDE.md的出现标志着我们从“临时对话”转向“持久化上下文”管理。它的设计哲学很明确一次性定义全局生效。你应该把项目中所有静态的、共识性的、基础性的信息都沉淀到这个文件里。这包括技术栈、架构说明、代码规范、API 设计原则、测试策略等。这样AI 在分析你的需求或处理你的文件时会首先加载这份“背景知识”从而使其输出从一开始就建立在正确的基础上。这不仅仅是省去了重复输入的时间更重要的是大幅减少了因上下文缺失导致的“方向性错误”让协作从一开始就走在正确的轨道上。2.2 与 .cursorrules、agents.md 的定位辨析在讨论CLAUDE.md时常会与.cursorrules和agents.md这两个文件混淆。理解它们的区别是有效利用它们的关键。.cursorrules: 这是Cursor IDE特有的配置文件。它的定位更偏向于“项目级设置与自动化规则”。你可以在这里定义项目级别的快捷键、代码片段、文件生成模板甚至是一些简单的自动化脚本。例如规定所有新生成的组件文件必须放在src/components/下并且自动导入必要的样式文件。.cursorrules的作用域和生效机制由 Cursor 编辑器本身控制它更“主动”更像是一个项目脚手架和自动化工具。agents.md: 这个文件通常与AI Agent 框架如 LangChain、AutoGPT 或自定义 Agent 系统相关。它用于定义“智能体Agent的行为、能力、目标和约束”。例如在一个自主完成数据抓取和分析的 Agent 项目中agents.md会详细说明 Agent 可以调用哪些工具如浏览器、计算器、它的核心目标是什么、以及它不能做什么如不能访问某些网站。它的内容是指令性的用于驱动一个自主或半自主的 AI 进程。CLAUDE.md: 如前所述它的核心是“项目上下文与知识库”。它不直接触发自动化像.cursorrules也不驱动自主行为像agents.md。它是被动提供信息的。当 AI特别是 Claude 系列模型或在 Cursor 中集成的 AI需要理解你的项目时它会去读取这个文件以此来丰富自己的知识背景从而做出更准确的判断和生成。它的内容是描述性和规范性的。一个简单的类比如果把你的项目比作一个公司那么.cursorrules是公司的行政流程手册规定怎么盖章、报销agents.md是某个特定部门如市场部的 KPI 和行动指南而CLAUDE.md则是公司的企业文化、发展历史、主营业务和核心技术的介绍白皮书是新员工AI入职时必须阅读的材料。2.3 通用性与工具适配性一个常见的误区是认为CLAUDE.md只适用于 Claude 模型或 Cursor。实际上这个命名更多是一种约定俗成源于早期实践者多使用 Claude 模型。其理念和格式是通用的。任何能够读取项目根目录下 Markdown 文件作为上下文的 AI 编程工具都能从中受益。例如GitHub Copilot 虽然没有一个官方的同名文件但你可以通过创建类似PROJECT_CONTEXT.md的文件并在合适的时机通过“”引用或粘贴部分内容来达到类似效果。一些新兴的、支持自定义系统提示词System Prompt的 AI IDE 或插件都可以将CLAUDE.md的内容作为系统提示词的一部分加载。因此维护一份高质量的CLAUDE.md是一项对未来友好的投资。即使你更换 AI 工具或模型这份精心整理的项目知识库其大部分内容依然具有极高的复用价值。3. CLAUDE.md 核心内容架构与撰写指南一份优秀的CLAUDE.md应该结构清晰、信息完备、语言精确。下面我将拆解其核心模块并给出具体的撰写建议和示例。3.1 项目元信息与核心目标这是文件的“开门见山”部分旨在用最精炼的语言让 AI 瞬间抓住项目的本质。项目名称与简介用一两句话说明项目是做什么的。例如“NextCRM- 一个基于 Next.js 14 和 Prisma 构建的现代客户关系管理系统专注于销售流程自动化和客户数据分析。”核心技术与版本明确列出项目的技术栈及其关键版本。这是防止 AI 推荐过时或错误 API 的关键。## 核心技术栈 - **前端**: Next.js 14 (App Router), React 18, TypeScript 5.4, Tailwind CSS 3.4 - **状态管理**: Zustand - **后端/全栈**: Next.js API Routes, Prisma ORM 5.0 - **数据库**: PostgreSQL 15 (通过 Supabase 托管) - **身份验证**: NextAuth.js v5 (Auth.js) - **部署**: Vercel核心目标与原则阐述项目的最高指导原则。例如“本项目的首要目标是开发体验优先和性能最佳实践。所有代码都应易于理解、测试和维护。优先使用服务端组件RSC和服务器操作减少客户端 JavaScript 体积。”注意版本号非常重要。明确告诉 AI “我们使用 Next.js 14 的 App Router”可以避免它生成基于 Pages Router 的代码或者使用已被弃用的 API。3.2 代码风格与规范这是保证生成代码一致性的“法律条文”。不要只说“遵循 Airbnb 规范”要给出本项目具体的、可能与众不同的约定。命名约定文件命名kebab-case(如user-profile.tsx) 还是PascalCase(如UserProfile.tsx)变量/函数camelCase。组件PascalCase。常量UPPER_SNAKE_CASE。TypeScript 接口/类型PascalCase并以I前缀(不推荐) 还是直接命名(如User而非IUser)。导入/导出规范导入顺序先第三方库再内部模块。是否使用/别名默认导出 vs 命名导出组件一律使用命名导出便于重构和 tree-shaking工具函数视情况而定。示例// 好的例子 import { useState } from react; import { cn } from /lib/utils; import { Button } from /components/ui/button; import { User } from prisma/client; // 避免 import React, { useState } from react; // 在 Next.js 14 中不需要显式导入 React代码格式化工具明确项目使用的工具如 Prettier 和 ESLint并指出任何特殊的规则覆盖。例如“本项目使用 Prettier 进行自动格式化所有代码提交前必须通过 ESLint 检查。我们禁用了typescript-eslint/no-explicit-any规则的警告但强烈建议使用更具体的类型。”3.3 目录结构解析与模块约定AI 需要知道文件应该放在哪里以及不同目录的职责。提供清晰的目录树摘要不需要完整的tree输出但需要说明核心目录的用途。## 项目结构/src ├── app/ # Next.js 14 App Router 主要目录 │ ├── (auth)/ # 路由组认证相关页面 │ ├── (dashboard)/ # 路由组主控台页面 │ ├── api/ # API 路由处理程序 │ └── globals.css # 全局样式 ├── components/ # 可复用 React 组件 │ ├── ui/ # 基础 UI 组件 (按钮、输入框等) │ └── shared/ # 业务共享组件 ├── lib/ # 工具函数、配置、客户端第三方库初始化 ├── prisma/ # Prisma schema 和迁移文件 ├── public/ # 静态资源 └── types/ # 全局 TypeScript 类型定义关键约定说明app/api/下的每个子目录都是一个路由必须导出名为GET、POST等的函数。components/ui/下的组件是纯展示组件不应包含业务逻辑或数据获取。lib/下的工具函数必须是纯函数或仅包含轻量级副作用且需要良好的错误处理。3.4 数据层与 API 设计模式这是 AI 生成数据操作代码的蓝图。描述越清晰生成的 Prisma 查询或 API 路由就越准确。数据库与 ORM 模式简要说明核心数据模型之间的关系。可以附上 Prisma Schema 中关键模型的定义片段。// 来自 prisma/schema.prisma 的片段 model User { id String id default(cuid()) email String unique name String? posts Post[] createdAt DateTime default(now()) }API 设计原则响应格式统一使用{ success: boolean, data?: T, error?: string }的包装结构。错误处理使用 HTTP 状态码并在lib中定义统一的错误类。数据验证使用 Zod 进行输入验证模式定义在lib/validations目录下。示例 API 模板// app/api/users/route.ts 的模板 import { NextRequest, NextResponse } from next/server; import { createUserSchema } from /lib/validations/user; import { prisma } from /lib/prisma; import { handleApiError } from /lib/api-error; export async function POST(request: NextRequest) { try { const body await request.json(); const validatedData createUserSchema.parse(body); // Zod 验证 const user await prisma.user.create({ data: validatedData }); return NextResponse.json({ success: true, data: user }, { status: 201 }); } catch (error) { return handleApiError(error); // 统一错误处理 } }3.5 组件设计体系与 UI 库集成如果使用了特定的 UI 库如 Shadcn/ui, MUI, Chakra或有一套内部组件规范必须在此说明。UI 库与主题“本项目使用 Shadcn/ui 作为组件库基础所有基础交互组件Button, Dialog, Form 等应从/components/ui导入禁止手动编写这些组件的原始 HTML。”样式方案“使用 Tailwind CSS 进行样式编写。颜色、间距、字体等均遵循tailwind.config.js中的主题扩展定义。自定义工具类放在src/lib/utils.ts的cn函数中用于条件合并 className。”新组件创建指南在components/下创建PascalCase命名的目录。主组件文件为index.tsx类型定义放在types.ts。如果组件复杂相关的子组件、钩子、样式应放在同一目录下。必须编写 JSDoc/TSDoc 注释说明组件 Props 和用途。3.6 测试、部署与开发工作流让 AI 了解项目的质量保障和交付流程。测试策略“单元测试使用 Vitest 和 React Testing Library测试文件与被测文件同名后缀为.test.ts或.test.tsx放在同一目录。组件测试重点在于用户交互而非实现细节。”环境变量“敏感配置通过.env.local管理其模板为.env.example。AI 在生成涉及环境变量的代码时如数据库连接应使用process.env并提示变量名但不要写出真实值。”Git 工作流“遵循 Conventional Commits 规范。feat:用于新功能fix:用于修复chore:用于工具变更等。”4. 高级技巧与动态上下文管理一份静态的CLAUDE.md是基础但要发挥最大威力需要一些进阶策略。4.1 模块化与引用避免单一巨型文件当项目非常庞大时一个CLAUDE.md文件可能变得臃肿不堪。此时可以采用模块化方法。创建docs/或.claude/目录在项目根目录下建立专门存放上下文文档的目录。拆分文件ARCHITECTURE.md: 详细架构设计。API_GUIDELINES.md: 详细的 API 设计规范。FRONTEND_CONVENTIONS.md: 前端特定规范。DATABASE.md: 数据库设计与优化指南。在主CLAUDE.md中引用主文件变得非常精简只包含最高级别的概述和到详细文档的链接。# 项目综合上下文 关于本项目的完整上下文请参阅以下文档 - [架构概述](./docs/ARCHITECTURE.md) - [API 设计指南](./docs/API_GUIDELINES.md) - [前端开发规范](./docs/FRONTEND_CONVENTIONS.md) - [数据库指南](./docs/DATABASE.md)大多数先进的 AI 工具如新版 Cursor能够跟随这些链接并读取链接文件的内容从而构建完整的上下文。这保持了主文件的简洁同时提供了深度信息的入口。4.2 结合.cursorrules实现智能触发虽然CLAUDE.md是被动提供上下文但我们可以通过 Cursor 的.cursorrules让它“主动”起来。例如你可以在.cursorrules中设置规则当用户创建新组件或 API 路由时自动引用CLAUDE.md中的相关模板或规范。// .cursorrules 示例片段 { rules: [ { when: creating a file matching **/app/api/**/route.ts, then: suggest using the API handler template from CLAUDE.md and remind about error handling and validation with Zod. }, { when: creating a file matching **/components/**/index.tsx, then: remind to check the component design guidelines in CLAUDE.md, especially about props typing and JSDoc comments. } ] }这样在你实际编码时Cursor 不仅会读取CLAUDE.md的全局背景还会在特定操作下给出更具针对性的提示形成“全局背景 场景化提示”的双重保障。4.3 针对不同任务的上下文聚焦AI 的上下文窗口是有限的。虽然CLAUDE.md提供了全局视图但在处理具体任务时你可能希望 AI 更专注于某个方面。方法一对话中引用在向 AI 提问时可以明确指出“请参考CLAUDE.md中关于 API 设计的原则”或“按照CLAUDE.md的组件规范修改这个文件”。这能引导 AI 优先调用相关部分的记忆。方法二创建任务专属提示文件对于非常复杂或重复的任务可以创建一个独立的TASK_SPECIFIC.md文件。例如在重构一个大型模块前先写一份REFACTOR_PLAN.md详细说明重构目标、边界、不能破坏的接口等然后让 AI 同时参考这个文件和CLAUDE.md。任务结束后可以将REFACTOR_PLAN.md中有长期价值的部分反向合并到CLAUDE.md中。5. 维护、迭代与团队协作实践CLAUDE.md不是一份写完后就可以束之高阁的文档。它应该是一个“活文档”随着项目一起成长。5.1 版本控制与更新时机纳入 Git 管理毫无疑问CLAUDE.md及其拆分出的文档都应该和其他源代码一样接受版本控制。它的每一次修改都应该有清晰的 Commit Message说明为什么更新例如“更新 CLAUDE.md增加对新的数据获取模式useSWR的规范说明”。关键的更新时机技术栈升级当 Next.js、React、Prisma 等主要依赖升级大版本时。架构重大调整如从 REST API 迁移到 GraphQL或引入新的状态管理方案。规范新增或变更团队制定了新的代码规范或发现原有规范存在普遍性问题时。新人入职后新成员在熟悉项目过程中如果反复遇到因CLAUDE.md缺失信息而导致的 AI 误判这正是补充文档的好机会。5.2 团队内的推广与共识建立在团队中推行CLAUDE.md最大的挑战不是技术而是习惯。以身作则展示价值作为倡导者你首先要在自己的工作中严格使用并维护它。当队友看到你总能快速、准确地让 AI 生成符合要求的代码时自然会产生兴趣。将其纳入 onboarding 流程新成员入职清单中必须包含“阅读并理解CLAUDE.md”这一项。可以安排一个简短的会议由你或技术负责人讲解文档的重点和背后的设计决策。建立轻量的评审机制对CLAUDE.md的修改可以像修改重要配置文件一样要求至少一名其他核心成员进行 Review。这保证了变更的合理性和共识。鼓励“文档驱动开发”在开始一项新功能或重构前鼓励开发者先思考“这部分设计是否需要更新或补充到CLAUDE.md里” 这能将最佳实践及时沉淀下来。5.3 效果评估与持续优化如何知道你的CLAUDE.md是否有效定性指标AI 生成代码的“首次通过率”是否提高生成后无需大改就能直接使用或仅需微调的比例是否增加团队沟通成本是否降低关于“这个应该怎么写”的讨论是否减少了新成员上手速度是否加快定量检查可选可以定期如每两周抽样检查 AI 生成的代码对照CLAUDE.md的规范看符合度如何。不符合的地方是规范没写清楚还是开发者没引导 AI 去读取定期回顾在团队技术例会中可以花 10 分钟快速过一遍CLAUDE.md看看是否有过时的内容或者大家最近是否遇到了因文档缺失而导致的共性问题。6. 常见陷阱、问题排查与实战心得在实际使用和维护CLAUDE.md的过程中你会遇到一些典型问题。这里记录了我踩过的坑和总结出的经验。6.1 常见问题速查表问题现象可能原因解决方案AI 完全忽略CLAUDE.md的内容1. 文件未放在项目根目录。2. AI 工具不支持自动读取该文件。3. 文件格式错误如不是.md后缀。1. 确认文件位于项目根目录。2. 查阅你所用的 AI 工具文档确认其上下文加载机制。在 Cursor 中需确保设置中启用了相关功能。3. 尝试在对话中手动提及或粘贴部分关键内容测试 AI 是否能理解。AI 理解了规范但生成代码仍不符合1. 规范描述过于模糊或存在歧义。2. 上下文中存在冲突的指令如之前的对话历史与CLAUDE.md冲突。3. AI 模型的优先级或“注意力”问题。1. 检查并重写有问题的规范使其更具体、可操作。使用代码示例。2. 开启新的聊天会话确保纯净的上下文始于CLAUDE.md。3. 在提问时更明确地强调规范例如“请严格遵守 CLAUDE.md 中关于组件命名的 PascalCase 规范为这个功能创建一个新组件。”文件过于冗长AI 似乎无法吸收全部信息1. 超出了 AI 模型的上下文窗口限制。2. 信息组织混乱重点不突出。1. 采用4.1节提到的模块化方法拆分文件让主文件只保留最核心、最常用的信息。2. 优化文档结构使用清晰的标题和列表。将“必须遵守”的强规范放在前面将“参考建议”放在后面。团队中不同成员维护的CLAUDE.md副本产生分歧缺乏统一的维护流程和版本控制。1. 立即将CLAUDE.md纳入 Git 管理并且只保留一个权威版本在主分支。2. 建立简单的修改流程如创建 PR 并需他人 Review。3. 在团队内同步丢弃所有本地不一致的副本。6.2 实操心得与独家技巧从“问题日志”开始如果你不知道CLAUDE.md该写什么一个极好的起点是记录下最近一周内你因为 AI 不理解项目背景而不得不反复解释或纠正它的所有问题。这些问题就是你的CLAUDE.md初版的核心内容。多用“正例”慎用“反例”在定义规范时尽量提供“应该怎么做”的正确代码示例。心理学和机器学习都有个现象模型更容易学习你明确展示的模式。过多描述“不要怎么做”有时反而会混淆模型。保持语言精准、中性避免使用“最好”、“可能”这类模糊词汇。使用“必须”、“应该”、“可以”等 RFC 2119 关键词来表述要求的强制程度。例如“组件必须使用命名导出。”“对于简单的状态可以优先使用useState而非 Zustand。”将CLAUDE.md视为“可执行的架构文档”传统的架构图Architecture Diagram是给人看的而CLAUDE.md是同时给人和AI看的架构文档。它的表述应该足够结构化、机器可读以便 AI 能提取出关键约束。这意味着多使用列表、代码块、结构化标题。定期“投喂”与测试不要写完就完事了。定期比如每周找一个项目中的小任务如修复一个简单的 bug添加一个简单的 UI 组件在一个全新的聊天会话中仅依靠CLAUDE.md和任务描述来让 AI 完成。观察其输出这是检验文档质量最直接的方法。根据测试结果迭代文档。处理“规范冲突”有时项目历史遗留代码的风格可能与你在CLAUDE.md中定义的新规范冲突。一个务实的做法是在CLAUDE.md中设立一个“遗留代码区”章节明确指出“在src/legacy/目录下的代码由于其历史原因允许不符合下述规范。但在所有新代码和重构中必须遵循新规范。” 这给了 AI 清晰的边界。维护一份好的CLAUDE.md初期需要一些投入但它带来的长期收益是指数级的。它不仅是你的 AI 助手的使用说明书更是项目知识的核心载体是团队技术决策的活化石也是保证项目在快速迭代中不偏离航向的罗盘。当你和你的团队习惯了这种“文档即代码上下文即生产力”的工作模式后你会发现与 AI 协作不再是碰运气而是一种稳定、高效、可预期的软件开发新常态。