1. 项目概述从“交接文档”到AI协作范式的转变最近在折腾各种AI编程工具从Cursor到Claude Code再到各种本地部署的Agent框架一个绕不开的问题摆在了面前如何让AI真正理解我的项目并按照我的习惯和规则来工作这让我想起了刚入行时每次接手新项目最头疼的环节——看前任留下的“交接文档”。那些文档质量参差不齐有的寥寥数语有的又过于冗长真正能让我快速上手的少之又少。如今面对AI这个“新同事”我们同样需要一份高质量的“交接文档”这就是CLAUDE.md或.cursorrules等类似文件诞生的背景。简单来说CLAUDE.md是一个纯文本的配置文件它的核心作用是为AI助手如Claude、Cursor内置的AI等提供关于当前项目的上下文、规则、偏好和约束。你可以把它理解为项目的“宪法”或“操作手册”。没有它AI就像一个新来的、对公司文化和项目历史一无所知的实习生虽然聪明但容易跑偏、效率低下甚至好心办坏事。有了它AI就能迅速进入角色理解项目的技术栈、代码风格、架构设计原则甚至你个人的编码癖好从而提供高度一致且符合预期的辅助。这个文件的价值远不止于告诉AI“这里用空格缩进那里用Tab”。它本质上是在定义人机协作的界面和协议。随着AI编码助手从“玩具”变成“生产力工具”从偶尔的代码补全发展到深度参与架构设计、代码重构和问题调试如何高效、精准地管理AI的行为就成了一个必须解决的工程问题。CLAUDE.md正是这个问题的答案之一。它适合所有正在或打算深度使用AI进行软件开发的开发者、团队负责人乃至技术管理者。无论你是独立开发者想提升个人效率还是团队希望统一代码质量理解并写好这份文档都是迈入下一代人机协同开发模式的关键一步。2. CLAUDE.md的核心价值与设计哲学2.1 为什么需要一份专门的AI配置文档你可能会问项目里已经有README.md介绍功能有.eslintrc.js、.prettierrc定义代码风格为什么还要额外搞一个CLAUDE.md这是因为传统工具和AI助手的工作模式有本质区别。README是给人看的侧重于项目背景、安装步骤和宏观设计代码规范工具是给编译器或静态分析工具用的执行的是硬性规则。而AI助手它是一个具有理解、推理和生成能力的“智能体”Agent它需要的不仅是规则更是意图、上下文和决策边界。举个例子.eslintrc可以规定“字符串必须用单引号”但无法告诉AI“在编写React组件时优先使用函数组件和Hooks除非有明确的性能考量需要使用类组件。” 后者是一种更高层次的、基于上下文的开发原则。再比如你的项目可能禁止使用某个过时的第三方库但新来的AI助手不知道它可能会在生成的代码中引用这个库。CLAUDE.md就是用来传达这些“潜规则”和“项目特异性知识”的桥梁。它的设计哲学是声明式和意图驱动的。你不是在写一系列冰冷的“禁止”指令而是在向一个聪明的合作伙伴阐述“在这个项目里我们通常这样思考那样做事。”2.2 超越代码风格定义协作的“心智模型”一份优秀的CLAUDE.md其作用远不止于统一代码格式。它旨在为AI构建一个关于本项目的“心智模型”。这个模型包括几个层次技术栈与架构层明确项目使用的核心框架如Next.js 14, Vue 3、状态管理方案Zustand, Pinia、UI库Shadcn/ui, Element Plus、以及整体的架构模式如Clean Architecture, 模块化设计。这能防止AI建议使用不兼容的技术或反模式。代码质量与安全层定义代码质量标准。例如要求所有函数必须有JSDoc/TSDoc注释复杂逻辑必须附带单元测试禁止使用eval()等危险函数对用户输入必须进行严格的验证和转义。这相当于将团队的安全与质量文化“灌输”给AI。工作流程与惯例层说明项目的特定惯例。比如“API响应处理统一使用在src/utils/api-handler.ts中定义的wrapResponse函数”“错误信息必须通过i18n文件引用禁止硬编码字符串”“组件命名采用PascalCase工具函数采用camelCase”。这些惯例往往无法通过通用工具自动化检查但对维护一致性至关重要。沟通与输出风格层指导AI如何与你互动。你可以要求“在建议代码时先简要解释你的思路”“如果对某个实现不确定请主动提问而不是猜测”“生成的代码块请标明修改的文件路径”。这能优化你和AI之间的沟通效率。注意不要把CLAUDE.md写成一份事无巨细的“百科全书”。它的目标是提供关键、高频的上下文。过于冗长的文档反而会让AI难以抓住重点。原则是优先定义那些如果AI不知道就会导致严重偏离或返工的规则。3. CLAUDE.md的实战结构与内容解析一份结构清晰的CLAUDE.md能极大提升AI的理解效率。虽然没有绝对统一的标准但经过多个项目的实践我总结出一个高效的四段式结构它逻辑上层层递进从项目全局到编码细节。3.1 第一部分项目全景图与技术栈声明这部分的目标是让AI在30秒内建立对项目的整体认知。它应该放在文件最开头。# 项目电商后台管理系统 (Next.js) ## 核心技术栈 - **框架**: Next.js 14 (App Router) - **语言**: TypeScript 5.x - **样式**: Tailwind CSS CSS Modules (关键组件) - **状态管理**: Zustand (全局状态) React Query (服务端状态) - **UI库**: 自主基于 [shadcn/ui](https://ui.shadcn.com) 构建未引入其他重型UI库。 - **数据库**: PostgreSQL通过 Prisma ORM 访问。 - **API风格**: RESTful内部使用 tRPC 进行类型安全的端到端通信可选。 ## 重要约束与原则 1. **禁止**使用 any 类型。所有未知类型必须使用 unknown 并细化。 2. **优先**函数式组件与 React Hooks。仅在极少数需要生命周期精细控制的场景考虑类组件。 3. **必须**所有数据获取操作必须通过 src/lib/api 下封装的函数进行禁止在组件内直接使用 fetch。 4. **目标**保持 bundle 体积最小化。引入任何新的 npm 包前需评估其大小和必要性。实操心得在声明技术栈时不仅要列出名称最好注明版本和关键选择理由。例如“使用Zustand而非Redux Toolkit因为本项目状态复杂度中等Zustand的简洁性更合适。” 这能帮助AI在后续建议时做出更符合项目背景的权衡。3.2 第二部分代码规范与质量门禁这部分是CLAUDE.md的筋骨将团队的代码要求具体化。它需要与现有的ESLint、Prettier配置协同但补充那些工具无法覆盖的“语义层”规则。## 代码风格与质量 ### 命名规范 - **文件/目录**: kebab-case (例如user-profile.tsx, api-handlers/) - **React组件**: PascalCase (例如ProductCard.tsx) - **函数/变量/常量**: camelCase (例如fetchUserData, MAX_RETRY_COUNT) - **类型/接口**: PascalCase并以 T 或 I 前缀区分本项目约定使用 T如 TUserProfile。 ### 组件设计 - **组件结构**: 每个组件一个独立目录包含 index.tsx (主组件)、types.ts (类型)、styles.module.css (样式如果需要) 和 __tests__/ 目录。 - **Props定义**: 使用 type 而非 interface 定义组件Props并必须使用 export type 导出。 - **默认导出**: 组件使用默认导出 (export default Component)工具函数使用命名导出。 ### 注释与文档 - **公共API**: 所有导出的函数、组件、Hooks必须包含完整的JSDoc/TSDoc注释说明用途、参数、返回值。 - **复杂逻辑**: 任何非一目了然的算法或业务逻辑必须添加行内注释解释“为什么这么做”。 - **TODO/FIXME**: 允许使用但必须附上作者缩写和日期如 // TODO [LF] 2024-10-01: 优化此处的缓存策略。 ### 错误处理 - **禁止**静默吞掉错误 (catch (e) {})。 - **必须**使用项目约定的 Logger.error() 函数记录错误并向用户展示友好的错误信息通过UI toast。 - **异步操作**必须处理Promise拒绝使用 try-catch 或 .catch()。注意事项这部分规则可能会和ESLint规则重叠。我的建议是CLAUDE.md侧重于“为什么”和“高层次该怎么做”而把具体的语法检查留给ESLint。例如ESLint可以检查“是否使用了any”而CLAUDE.md可以说明“为什么我们禁止使用any为了类型安全”。3.3 第三部分工作流程与AI交互指令这是最具特色的一部分直接定义了你希望AI如何与你合作。它让AI从一个被动的代码生成器变成一个主动的协作伙伴。## 对AI助手的期望与工作流程 ### 代码生成与修改 1. **上下文优先**在建议任何代码前请先分析相关文件如父组件、API定义的现有模式和约定。 2. **渐进式更改**如果改动较大请先概述你的方案在我确认后再生成详细代码。 3. **路径标注**所有生成的代码块请在开头用注释标明目标文件路径例如// File: src/components/product/ProductList.tsx。 4. **解释思路**对于复杂的逻辑或算法在代码前用一两句话说明你的实现思路。 ### 问题分析与调试 1. **假设验证**如果你对项目某个部分的行为有假设请先询问或引导我验证而不是基于假设直接给出方案。 2. **根因分析**遇到bug时请尝试分析根本原因而不仅仅是提供表面修复。可以给出排查步骤的建议。 3. **依赖检查**在建议安装新包时请同时检查其许可证、维护状态、包体积并提醒潜在冲突。 ### 沟通风格 - **简洁直接**回答技术问题请直接切入重点避免冗长的背景介绍除非我问。 - **主动提问**如果我的需求模糊或存在矛盾请主动、具体地提问以澄清。 - **选项提供**对于有争议的设计决策可以提供2-3个备选方案并列出各自的优缺点。踩过的坑最初我忽略了这部分结果AI经常生成一些“正确但不合时宜”的代码。比如我让它“给这个列表加个搜索”它可能直接用了一个我们项目里不存在的UI组件库或者写了一个不符合我们数据流模式的搜索逻辑。加入了工作流程指令后AI会先问“咱们项目的列表数据是从父组件props来的还是自己用React Query fetch的搜索是前端过滤还是需要调用后端API” 沟通效率直线上升。3.4 第四部分项目特定知识库与“黑名单”每个项目都有一些独特的“地雷”或“捷径”。这部分就是项目的“内部维基”存放那些在官方文档里找不到但对开发至关重要的信息。## 项目特定知识 ### 已废弃的模块 - src/utils/old-auth.js: 已废弃所有认证逻辑请使用 src/lib/auth 下的新模块。 - legacy-api/ 目录下的所有代码仅供兼容旧版新功能严禁调用。 ### 常用工具函数位置 - **日期处理**: src/utils/date-formatter.ts - **金额格式化**: src/utils/currency.ts - **表单验证schema**: src/schemas/ (使用Zod定义) ### 已知的“坑”与解决方案 - **问题**在 ProductTable 组件中直接使用 useEffect 加载数据会导致重复渲染。 - **解决方案**数据加载应移至父组件 ProductManagementPage通过props传入。 - **问题**user.avatar 字段可能为 null 或空字符串。 - **解决方案**始终使用 getUserAvatar(user) 工具函数获取头像URL它内置了回退逻辑。 ### 环境与配置 - **环境变量**所有敏感配置必须通过 .env.local 定义前缀为 NEXT_PUBLIC_ 的变量才会暴露给前端。 - **API基地址**开发环境使用 http://localhost:3000/api通过 src/config/index.ts 中的 getApiBaseUrl() 函数获取。实操心得这部分内容需要持续维护。每当团队踩了一个新坑或者总结出一个最佳实践就立刻更新到CLAUDE.md里。这相当于在给AI做“持续培训”让后来者无论是人还是AI都能避免重复踩坑。我习惯在文件末尾加一个“最后更新日期”提醒自己和团队这不是一份一劳永逸的文档。4. 高级技巧让CLAUDE.md动态化与场景化基础的CLAUDE.md已经能解决80%的问题。但对于更复杂的项目或追求极致效率的团队可以进一步探索一些高级用法。4.1 分层与模块化配置对于大型Monorepo项目一个根目录的CLAUDE.md可能不够用。你可以在不同子包或功能模块下放置更具体的CLAUDE.md文件。AI助手特别是像Cursor这类能感知工作区的工具会优先读取当前打开文件所在目录的配置没有则向上级目录查找。例如/claude.md定义全局规则如代码风格、通用工具链。/packages/web-app/claude.md定义前端React特定的规则如Hooks使用规范、组件设计模式。/packages/web-app/src/features/payment/claude.md定义支付业务模块的特定逻辑如必须调用的风控接口、特定的状态流转。这种结构允许你在保持全局一致性的同时为不同模块赋予特定的“专业知识”。4.2 利用注释进行实时上下文注入CLAUDE.md是静态配置但开发过程是动态的。你可以在代码文件中通过特殊格式的注释给AI注入临时、高优先级的指令。这比反复修改CLAUDE.md文件要灵活得多。// AI: 接下来生成的代码请遵循以下规则 // 1. 使用我们自定义的 useQuery Hook来自 src/lib/react-query而不是TanStack Query原生的。 // 2. 错误处理必须调用 showErrorToast(error)。 // 3. 数据加载状态使用 Skeleton 组件来自 /components/ui/skeleton。 import { useState } from react; // ... 接下来让AI帮你补全代码或者当AI的理解出现偏差时你可以立即纠正// AI: 你刚才生成的函数名 processUserInfo 不符合我们的命名规范。 // 请将其重命名为 formatUserProfileForDisplay并补充JSDoc注释。注意事项这种实时指令非常强大但不宜滥用。它更适合处理一次性的、局部的上下文。如果某条指令被频繁使用就应该考虑将其沉淀到CLAUDE.md中成为永久规则。4.3 与Agent框架结合从规则到能力当你的项目从使用单一的AI编码助手发展到使用自定义的AI Agent例如基于LangChain、LlamaIndex构建的智能体时CLAUDE.md的概念可以进一步扩展为agent.md或instructions.md。此时文档不仅包含规则还定义了Agent的角色、目标和可用工具。# 角色本项目的代码审查专家Agent ## 你的核心目标 1. 自动审查新提交的Pull Request代码。 2. 重点检查安全漏洞、性能反模式和与架构原则的背离。 3. 生成清晰、可操作的审查意见而非仅仅列出问题。 ## 你的专属知识 - 此处嵌入整个项目的CLAUDE.md内容 - 重点安全规则SQL查询必须使用Prisma的参数化查询禁止字符串拼接。 - 重点性能规则React组件内避免创建新的对象/函数作为props。 ## 你可以使用的工具 1. **代码解析工具**可以理解AST抽象语法树识别特定模式。 2. **依赖分析工具**可以检查引入新包的风险。 3. **风格检查工具**可以调用项目的ESLint和Prettier。 ## 输出格式 请按以下格式输出审查结果 - **[高危]**/[中危]/[低危] [问题简述] - **文件**: path/to/file.js - **行号**: 42 - **问题描述**: 具体描述问题及潜在风险。 - **修改建议**: 提供具体的代码修改示例。 - **依据规则**: 引用CLAUDE.md中的哪一条规则或通用最佳实践。在这种范式下文档变成了驱动AI Agent的“程序”实现了从静态规则配置到动态智能体行为的跃升。5. 常见问题与避坑指南实录在实际编写和使用CLAUDE.md的过程中我遇到了不少典型问题。这里记录下我的排查思路和解决方案希望能帮你少走弯路。5.1 问题规则冲突或AI无法理解现象你定义了一条规则但AI在生成代码时似乎忽略了它或者生成了矛盾的代码。排查思路检查规则表述是否清晰避免使用模糊、有歧义的词汇。比如“避免使用复杂逻辑”就不如“单个函数圈复杂度Cyclomatic Complexity不应超过10”来得明确。检查规则优先级如果规则之间存在潜在冲突AI可能会困惑。例如一条规则说“保持代码简洁”另一条说“必须进行完整的错误处理”。在AI看来冗长的try-catch块可能就不“简洁”了。你需要明确优先级或提供更具体的指导“在简洁性和健壮性冲突时优先保证健壮性但应尝试将错误处理逻辑抽取为独立函数。”简化与测试将复杂的复合规则拆分成几条简单、原子性的规则。然后针对每条规则单独测试AI的响应。例如先只测试“函数必须加JSDoc”这一条确认AI能理解并执行后再加入其他规则。解决方案示例原模糊规则“好好处理错误。” 修改为清晰规则对所有可能抛出异常的操作如网络请求、文件IO、JSON解析使用try-catch包裹。在catch块中至少要用console.error记录错误对象。向用户展示的错误信息应来自预定义的友好消息映射表ERROR_MESSAGES而非直接显示原始错误。5.2 问题文档过长导致AI注意力分散现象CLAUDE.md文件写了几百行AI在响应时似乎只记住了最后几条规则或者表现得不稳定。根因分析大多数AI模型都有上下文窗口限制。虽然Claude等模型支持超长上下文但过多的信息仍可能导致模型难以聚焦于当前任务最相关的部分。这被称为“中间丢失”现象模型对输入中间部分的信息记忆较弱。解决方案优先级排序将规则分为“核心规则必须遵守”和“最佳实践建议遵守”。把核心规则如技术栈、安全禁令、关键架构原则放在文档最前面和最显眼的位置比如用## 核心规则这样的标题强调。结构化与索引使用清晰的标题层级并可以考虑在文档开头增加一个“快速索引”部分列出最重要的规则条目和其所在章节方便AI和人快速定位。模块化拆分如前文所述对于大型项目采用分层的CLAUDE.md文件而不是一个庞然大物。5.3 问题规则未能随项目演进而更新现象AI基于过时的CLAUDE.md给出了建议导致代码与项目现状不符。预防与维护策略建立更新机制将CLAUDE.md纳入版本控制如Git任何技术栈升级、架构调整或重要规范变更都需要同步更新此文件。可以在团队的Pull Request模板中增加一项检查“本次改动是否更新了CLAUDE.md或相关文档”添加“有效期”提示在文件顶部注明最后复审日期例如!-- Last reviewed: 2024-10-01 --。这能提醒团队成员该文档的“新鲜度”。链接到动态资源对于变化频繁的信息如API端点列表、组件库文档不要在CLAUDE.md中直接写死而是提供链接。例如“最新可用的UI组件请查阅内部Storybookhttps://storybook.internal.company.com”。5.4 问题不同AI工具间的规则不兼容现象你在Cursor里用.cursorrules定义了一套规则换到Claude Code或VS Code with Continue插件时又得重新配置。现状与应对目前确实没有统一的行业标准。.cursorrules、CLAUDE.md、continue.json等分别是不同工具约定的配置格式。务实解决方案内容为主格式次之保持核心规则内容技术栈、代码规范、工作流程的稳定性和一致性。这些内容本质上是纯文本知识。使用符号链接或生成脚本你可以维护一个“真理之源”文件比如PROJECT_AI_GUIDE.md然后通过脚本或符号链接在项目根目录生成各个工具所需的特定文件.cursorrules,CLAUDE.md确保内容同步。拥抱主流保持关注可以优先采用受众更广的CLAUDE.md命名因为Claude API及其衍生工具如Claude Code影响力较大。同时关注社区动态看是否有趋同的迹象。5.5 一份自查清单在完成你的CLAUDE.md后可以用下面这份清单快速检查[ ]目标明确AI看完后是否能准确说出本项目的主要技术栈和核心禁忌[ ]规则可执行每一条规则是否清晰、无歧义能让AI生成可验证的代码例如“代码要美观”不可执行“使用Prettier格式化单行最大80字符”可执行。[ ]重点突出最重要的规则是否放在了最前面[ ]避免矛盾规则之间是否存在直接冲突如既要求“代码简短”又要求“详尽注释”。[ ]持续有效文档中是否包含了容易过时的信息如具体的库版本号除非这是强制约束。[ ]有用示例对于复杂的约定是否提供了正例和反例[ ]沟通界面是否定义了期望的AI交互风格如主动提问、解释思路编写CLAUDE.md不是一个一蹴而就的任务而是一个持续迭代的过程。它始于你对项目混乱的反思成于你与AI协作效率的显著提升。最开始可能只有寥寥几条规则但随着项目的复杂化和你与AI磨合的深入这份文档会逐渐丰满最终成为项目知识资产中不可或缺的一部分。它不仅仅是一份给AI的说明书更是对项目开发规范、设计理念和团队共识的一次系统性梳理其价值早已超越了工具配置本身。 CLAUDE.md：AI编程助手的项目配置指南与最佳实践
1. 项目概述从“交接文档”到AI协作范式的转变最近在折腾各种AI编程工具从Cursor到Claude Code再到各种本地部署的Agent框架一个绕不开的问题摆在了面前如何让AI真正理解我的项目并按照我的习惯和规则来工作这让我想起了刚入行时每次接手新项目最头疼的环节——看前任留下的“交接文档”。那些文档质量参差不齐有的寥寥数语有的又过于冗长真正能让我快速上手的少之又少。如今面对AI这个“新同事”我们同样需要一份高质量的“交接文档”这就是CLAUDE.md或.cursorrules等类似文件诞生的背景。简单来说CLAUDE.md是一个纯文本的配置文件它的核心作用是为AI助手如Claude、Cursor内置的AI等提供关于当前项目的上下文、规则、偏好和约束。你可以把它理解为项目的“宪法”或“操作手册”。没有它AI就像一个新来的、对公司文化和项目历史一无所知的实习生虽然聪明但容易跑偏、效率低下甚至好心办坏事。有了它AI就能迅速进入角色理解项目的技术栈、代码风格、架构设计原则甚至你个人的编码癖好从而提供高度一致且符合预期的辅助。这个文件的价值远不止于告诉AI“这里用空格缩进那里用Tab”。它本质上是在定义人机协作的界面和协议。随着AI编码助手从“玩具”变成“生产力工具”从偶尔的代码补全发展到深度参与架构设计、代码重构和问题调试如何高效、精准地管理AI的行为就成了一个必须解决的工程问题。CLAUDE.md正是这个问题的答案之一。它适合所有正在或打算深度使用AI进行软件开发的开发者、团队负责人乃至技术管理者。无论你是独立开发者想提升个人效率还是团队希望统一代码质量理解并写好这份文档都是迈入下一代人机协同开发模式的关键一步。2. CLAUDE.md的核心价值与设计哲学2.1 为什么需要一份专门的AI配置文档你可能会问项目里已经有README.md介绍功能有.eslintrc.js、.prettierrc定义代码风格为什么还要额外搞一个CLAUDE.md这是因为传统工具和AI助手的工作模式有本质区别。README是给人看的侧重于项目背景、安装步骤和宏观设计代码规范工具是给编译器或静态分析工具用的执行的是硬性规则。而AI助手它是一个具有理解、推理和生成能力的“智能体”Agent它需要的不仅是规则更是意图、上下文和决策边界。举个例子.eslintrc可以规定“字符串必须用单引号”但无法告诉AI“在编写React组件时优先使用函数组件和Hooks除非有明确的性能考量需要使用类组件。” 后者是一种更高层次的、基于上下文的开发原则。再比如你的项目可能禁止使用某个过时的第三方库但新来的AI助手不知道它可能会在生成的代码中引用这个库。CLAUDE.md就是用来传达这些“潜规则”和“项目特异性知识”的桥梁。它的设计哲学是声明式和意图驱动的。你不是在写一系列冰冷的“禁止”指令而是在向一个聪明的合作伙伴阐述“在这个项目里我们通常这样思考那样做事。”2.2 超越代码风格定义协作的“心智模型”一份优秀的CLAUDE.md其作用远不止于统一代码格式。它旨在为AI构建一个关于本项目的“心智模型”。这个模型包括几个层次技术栈与架构层明确项目使用的核心框架如Next.js 14, Vue 3、状态管理方案Zustand, Pinia、UI库Shadcn/ui, Element Plus、以及整体的架构模式如Clean Architecture, 模块化设计。这能防止AI建议使用不兼容的技术或反模式。代码质量与安全层定义代码质量标准。例如要求所有函数必须有JSDoc/TSDoc注释复杂逻辑必须附带单元测试禁止使用eval()等危险函数对用户输入必须进行严格的验证和转义。这相当于将团队的安全与质量文化“灌输”给AI。工作流程与惯例层说明项目的特定惯例。比如“API响应处理统一使用在src/utils/api-handler.ts中定义的wrapResponse函数”“错误信息必须通过i18n文件引用禁止硬编码字符串”“组件命名采用PascalCase工具函数采用camelCase”。这些惯例往往无法通过通用工具自动化检查但对维护一致性至关重要。沟通与输出风格层指导AI如何与你互动。你可以要求“在建议代码时先简要解释你的思路”“如果对某个实现不确定请主动提问而不是猜测”“生成的代码块请标明修改的文件路径”。这能优化你和AI之间的沟通效率。注意不要把CLAUDE.md写成一份事无巨细的“百科全书”。它的目标是提供关键、高频的上下文。过于冗长的文档反而会让AI难以抓住重点。原则是优先定义那些如果AI不知道就会导致严重偏离或返工的规则。3. CLAUDE.md的实战结构与内容解析一份结构清晰的CLAUDE.md能极大提升AI的理解效率。虽然没有绝对统一的标准但经过多个项目的实践我总结出一个高效的四段式结构它逻辑上层层递进从项目全局到编码细节。3.1 第一部分项目全景图与技术栈声明这部分的目标是让AI在30秒内建立对项目的整体认知。它应该放在文件最开头。# 项目电商后台管理系统 (Next.js) ## 核心技术栈 - **框架**: Next.js 14 (App Router) - **语言**: TypeScript 5.x - **样式**: Tailwind CSS CSS Modules (关键组件) - **状态管理**: Zustand (全局状态) React Query (服务端状态) - **UI库**: 自主基于 [shadcn/ui](https://ui.shadcn.com) 构建未引入其他重型UI库。 - **数据库**: PostgreSQL通过 Prisma ORM 访问。 - **API风格**: RESTful内部使用 tRPC 进行类型安全的端到端通信可选。 ## 重要约束与原则 1. **禁止**使用 any 类型。所有未知类型必须使用 unknown 并细化。 2. **优先**函数式组件与 React Hooks。仅在极少数需要生命周期精细控制的场景考虑类组件。 3. **必须**所有数据获取操作必须通过 src/lib/api 下封装的函数进行禁止在组件内直接使用 fetch。 4. **目标**保持 bundle 体积最小化。引入任何新的 npm 包前需评估其大小和必要性。实操心得在声明技术栈时不仅要列出名称最好注明版本和关键选择理由。例如“使用Zustand而非Redux Toolkit因为本项目状态复杂度中等Zustand的简洁性更合适。” 这能帮助AI在后续建议时做出更符合项目背景的权衡。3.2 第二部分代码规范与质量门禁这部分是CLAUDE.md的筋骨将团队的代码要求具体化。它需要与现有的ESLint、Prettier配置协同但补充那些工具无法覆盖的“语义层”规则。## 代码风格与质量 ### 命名规范 - **文件/目录**: kebab-case (例如user-profile.tsx, api-handlers/) - **React组件**: PascalCase (例如ProductCard.tsx) - **函数/变量/常量**: camelCase (例如fetchUserData, MAX_RETRY_COUNT) - **类型/接口**: PascalCase并以 T 或 I 前缀区分本项目约定使用 T如 TUserProfile。 ### 组件设计 - **组件结构**: 每个组件一个独立目录包含 index.tsx (主组件)、types.ts (类型)、styles.module.css (样式如果需要) 和 __tests__/ 目录。 - **Props定义**: 使用 type 而非 interface 定义组件Props并必须使用 export type 导出。 - **默认导出**: 组件使用默认导出 (export default Component)工具函数使用命名导出。 ### 注释与文档 - **公共API**: 所有导出的函数、组件、Hooks必须包含完整的JSDoc/TSDoc注释说明用途、参数、返回值。 - **复杂逻辑**: 任何非一目了然的算法或业务逻辑必须添加行内注释解释“为什么这么做”。 - **TODO/FIXME**: 允许使用但必须附上作者缩写和日期如 // TODO [LF] 2024-10-01: 优化此处的缓存策略。 ### 错误处理 - **禁止**静默吞掉错误 (catch (e) {})。 - **必须**使用项目约定的 Logger.error() 函数记录错误并向用户展示友好的错误信息通过UI toast。 - **异步操作**必须处理Promise拒绝使用 try-catch 或 .catch()。注意事项这部分规则可能会和ESLint规则重叠。我的建议是CLAUDE.md侧重于“为什么”和“高层次该怎么做”而把具体的语法检查留给ESLint。例如ESLint可以检查“是否使用了any”而CLAUDE.md可以说明“为什么我们禁止使用any为了类型安全”。3.3 第三部分工作流程与AI交互指令这是最具特色的一部分直接定义了你希望AI如何与你合作。它让AI从一个被动的代码生成器变成一个主动的协作伙伴。## 对AI助手的期望与工作流程 ### 代码生成与修改 1. **上下文优先**在建议任何代码前请先分析相关文件如父组件、API定义的现有模式和约定。 2. **渐进式更改**如果改动较大请先概述你的方案在我确认后再生成详细代码。 3. **路径标注**所有生成的代码块请在开头用注释标明目标文件路径例如// File: src/components/product/ProductList.tsx。 4. **解释思路**对于复杂的逻辑或算法在代码前用一两句话说明你的实现思路。 ### 问题分析与调试 1. **假设验证**如果你对项目某个部分的行为有假设请先询问或引导我验证而不是基于假设直接给出方案。 2. **根因分析**遇到bug时请尝试分析根本原因而不仅仅是提供表面修复。可以给出排查步骤的建议。 3. **依赖检查**在建议安装新包时请同时检查其许可证、维护状态、包体积并提醒潜在冲突。 ### 沟通风格 - **简洁直接**回答技术问题请直接切入重点避免冗长的背景介绍除非我问。 - **主动提问**如果我的需求模糊或存在矛盾请主动、具体地提问以澄清。 - **选项提供**对于有争议的设计决策可以提供2-3个备选方案并列出各自的优缺点。踩过的坑最初我忽略了这部分结果AI经常生成一些“正确但不合时宜”的代码。比如我让它“给这个列表加个搜索”它可能直接用了一个我们项目里不存在的UI组件库或者写了一个不符合我们数据流模式的搜索逻辑。加入了工作流程指令后AI会先问“咱们项目的列表数据是从父组件props来的还是自己用React Query fetch的搜索是前端过滤还是需要调用后端API” 沟通效率直线上升。3.4 第四部分项目特定知识库与“黑名单”每个项目都有一些独特的“地雷”或“捷径”。这部分就是项目的“内部维基”存放那些在官方文档里找不到但对开发至关重要的信息。## 项目特定知识 ### 已废弃的模块 - src/utils/old-auth.js: 已废弃所有认证逻辑请使用 src/lib/auth 下的新模块。 - legacy-api/ 目录下的所有代码仅供兼容旧版新功能严禁调用。 ### 常用工具函数位置 - **日期处理**: src/utils/date-formatter.ts - **金额格式化**: src/utils/currency.ts - **表单验证schema**: src/schemas/ (使用Zod定义) ### 已知的“坑”与解决方案 - **问题**在 ProductTable 组件中直接使用 useEffect 加载数据会导致重复渲染。 - **解决方案**数据加载应移至父组件 ProductManagementPage通过props传入。 - **问题**user.avatar 字段可能为 null 或空字符串。 - **解决方案**始终使用 getUserAvatar(user) 工具函数获取头像URL它内置了回退逻辑。 ### 环境与配置 - **环境变量**所有敏感配置必须通过 .env.local 定义前缀为 NEXT_PUBLIC_ 的变量才会暴露给前端。 - **API基地址**开发环境使用 http://localhost:3000/api通过 src/config/index.ts 中的 getApiBaseUrl() 函数获取。实操心得这部分内容需要持续维护。每当团队踩了一个新坑或者总结出一个最佳实践就立刻更新到CLAUDE.md里。这相当于在给AI做“持续培训”让后来者无论是人还是AI都能避免重复踩坑。我习惯在文件末尾加一个“最后更新日期”提醒自己和团队这不是一份一劳永逸的文档。4. 高级技巧让CLAUDE.md动态化与场景化基础的CLAUDE.md已经能解决80%的问题。但对于更复杂的项目或追求极致效率的团队可以进一步探索一些高级用法。4.1 分层与模块化配置对于大型Monorepo项目一个根目录的CLAUDE.md可能不够用。你可以在不同子包或功能模块下放置更具体的CLAUDE.md文件。AI助手特别是像Cursor这类能感知工作区的工具会优先读取当前打开文件所在目录的配置没有则向上级目录查找。例如/claude.md定义全局规则如代码风格、通用工具链。/packages/web-app/claude.md定义前端React特定的规则如Hooks使用规范、组件设计模式。/packages/web-app/src/features/payment/claude.md定义支付业务模块的特定逻辑如必须调用的风控接口、特定的状态流转。这种结构允许你在保持全局一致性的同时为不同模块赋予特定的“专业知识”。4.2 利用注释进行实时上下文注入CLAUDE.md是静态配置但开发过程是动态的。你可以在代码文件中通过特殊格式的注释给AI注入临时、高优先级的指令。这比反复修改CLAUDE.md文件要灵活得多。// AI: 接下来生成的代码请遵循以下规则 // 1. 使用我们自定义的 useQuery Hook来自 src/lib/react-query而不是TanStack Query原生的。 // 2. 错误处理必须调用 showErrorToast(error)。 // 3. 数据加载状态使用 Skeleton 组件来自 /components/ui/skeleton。 import { useState } from react; // ... 接下来让AI帮你补全代码或者当AI的理解出现偏差时你可以立即纠正// AI: 你刚才生成的函数名 processUserInfo 不符合我们的命名规范。 // 请将其重命名为 formatUserProfileForDisplay并补充JSDoc注释。注意事项这种实时指令非常强大但不宜滥用。它更适合处理一次性的、局部的上下文。如果某条指令被频繁使用就应该考虑将其沉淀到CLAUDE.md中成为永久规则。4.3 与Agent框架结合从规则到能力当你的项目从使用单一的AI编码助手发展到使用自定义的AI Agent例如基于LangChain、LlamaIndex构建的智能体时CLAUDE.md的概念可以进一步扩展为agent.md或instructions.md。此时文档不仅包含规则还定义了Agent的角色、目标和可用工具。# 角色本项目的代码审查专家Agent ## 你的核心目标 1. 自动审查新提交的Pull Request代码。 2. 重点检查安全漏洞、性能反模式和与架构原则的背离。 3. 生成清晰、可操作的审查意见而非仅仅列出问题。 ## 你的专属知识 - 此处嵌入整个项目的CLAUDE.md内容 - 重点安全规则SQL查询必须使用Prisma的参数化查询禁止字符串拼接。 - 重点性能规则React组件内避免创建新的对象/函数作为props。 ## 你可以使用的工具 1. **代码解析工具**可以理解AST抽象语法树识别特定模式。 2. **依赖分析工具**可以检查引入新包的风险。 3. **风格检查工具**可以调用项目的ESLint和Prettier。 ## 输出格式 请按以下格式输出审查结果 - **[高危]**/[中危]/[低危] [问题简述] - **文件**: path/to/file.js - **行号**: 42 - **问题描述**: 具体描述问题及潜在风险。 - **修改建议**: 提供具体的代码修改示例。 - **依据规则**: 引用CLAUDE.md中的哪一条规则或通用最佳实践。在这种范式下文档变成了驱动AI Agent的“程序”实现了从静态规则配置到动态智能体行为的跃升。5. 常见问题与避坑指南实录在实际编写和使用CLAUDE.md的过程中我遇到了不少典型问题。这里记录下我的排查思路和解决方案希望能帮你少走弯路。5.1 问题规则冲突或AI无法理解现象你定义了一条规则但AI在生成代码时似乎忽略了它或者生成了矛盾的代码。排查思路检查规则表述是否清晰避免使用模糊、有歧义的词汇。比如“避免使用复杂逻辑”就不如“单个函数圈复杂度Cyclomatic Complexity不应超过10”来得明确。检查规则优先级如果规则之间存在潜在冲突AI可能会困惑。例如一条规则说“保持代码简洁”另一条说“必须进行完整的错误处理”。在AI看来冗长的try-catch块可能就不“简洁”了。你需要明确优先级或提供更具体的指导“在简洁性和健壮性冲突时优先保证健壮性但应尝试将错误处理逻辑抽取为独立函数。”简化与测试将复杂的复合规则拆分成几条简单、原子性的规则。然后针对每条规则单独测试AI的响应。例如先只测试“函数必须加JSDoc”这一条确认AI能理解并执行后再加入其他规则。解决方案示例原模糊规则“好好处理错误。” 修改为清晰规则对所有可能抛出异常的操作如网络请求、文件IO、JSON解析使用try-catch包裹。在catch块中至少要用console.error记录错误对象。向用户展示的错误信息应来自预定义的友好消息映射表ERROR_MESSAGES而非直接显示原始错误。5.2 问题文档过长导致AI注意力分散现象CLAUDE.md文件写了几百行AI在响应时似乎只记住了最后几条规则或者表现得不稳定。根因分析大多数AI模型都有上下文窗口限制。虽然Claude等模型支持超长上下文但过多的信息仍可能导致模型难以聚焦于当前任务最相关的部分。这被称为“中间丢失”现象模型对输入中间部分的信息记忆较弱。解决方案优先级排序将规则分为“核心规则必须遵守”和“最佳实践建议遵守”。把核心规则如技术栈、安全禁令、关键架构原则放在文档最前面和最显眼的位置比如用## 核心规则这样的标题强调。结构化与索引使用清晰的标题层级并可以考虑在文档开头增加一个“快速索引”部分列出最重要的规则条目和其所在章节方便AI和人快速定位。模块化拆分如前文所述对于大型项目采用分层的CLAUDE.md文件而不是一个庞然大物。5.3 问题规则未能随项目演进而更新现象AI基于过时的CLAUDE.md给出了建议导致代码与项目现状不符。预防与维护策略建立更新机制将CLAUDE.md纳入版本控制如Git任何技术栈升级、架构调整或重要规范变更都需要同步更新此文件。可以在团队的Pull Request模板中增加一项检查“本次改动是否更新了CLAUDE.md或相关文档”添加“有效期”提示在文件顶部注明最后复审日期例如!-- Last reviewed: 2024-10-01 --。这能提醒团队成员该文档的“新鲜度”。链接到动态资源对于变化频繁的信息如API端点列表、组件库文档不要在CLAUDE.md中直接写死而是提供链接。例如“最新可用的UI组件请查阅内部Storybookhttps://storybook.internal.company.com”。5.4 问题不同AI工具间的规则不兼容现象你在Cursor里用.cursorrules定义了一套规则换到Claude Code或VS Code with Continue插件时又得重新配置。现状与应对目前确实没有统一的行业标准。.cursorrules、CLAUDE.md、continue.json等分别是不同工具约定的配置格式。务实解决方案内容为主格式次之保持核心规则内容技术栈、代码规范、工作流程的稳定性和一致性。这些内容本质上是纯文本知识。使用符号链接或生成脚本你可以维护一个“真理之源”文件比如PROJECT_AI_GUIDE.md然后通过脚本或符号链接在项目根目录生成各个工具所需的特定文件.cursorrules,CLAUDE.md确保内容同步。拥抱主流保持关注可以优先采用受众更广的CLAUDE.md命名因为Claude API及其衍生工具如Claude Code影响力较大。同时关注社区动态看是否有趋同的迹象。5.5 一份自查清单在完成你的CLAUDE.md后可以用下面这份清单快速检查[ ]目标明确AI看完后是否能准确说出本项目的主要技术栈和核心禁忌[ ]规则可执行每一条规则是否清晰、无歧义能让AI生成可验证的代码例如“代码要美观”不可执行“使用Prettier格式化单行最大80字符”可执行。[ ]重点突出最重要的规则是否放在了最前面[ ]避免矛盾规则之间是否存在直接冲突如既要求“代码简短”又要求“详尽注释”。[ ]持续有效文档中是否包含了容易过时的信息如具体的库版本号除非这是强制约束。[ ]有用示例对于复杂的约定是否提供了正例和反例[ ]沟通界面是否定义了期望的AI交互风格如主动提问、解释思路编写CLAUDE.md不是一个一蹴而就的任务而是一个持续迭代的过程。它始于你对项目混乱的反思成于你与AI协作效率的显著提升。最开始可能只有寥寥几条规则但随着项目的复杂化和你与AI磨合的深入这份文档会逐渐丰满最终成为项目知识资产中不可或缺的一部分。它不仅仅是一份给AI的说明书更是对项目开发规范、设计理念和团队共识的一次系统性梳理其价值早已超越了工具配置本身。