1. 项目概述为什么你的AI编码助手需要一份“入职手册”如果你用过Claude Code、Cursor或者GitHub Copilot超过一周大概率会遇到一个让人抓狂的问题AI的“失忆症”。周一你刚花半小时调教好它让它记住了你的项目结构、编码规范甚至你个人对TypeScript严格模式的执念。它表现得像个合作多年的老搭档代码写得又快又准。到了周五你打开同一个项目开启一个新的会话它仿佛被格式化了——开始建议你用JavaScript提议使用你明确禁止的设计模式甚至忘了你项目用的是Jest而不是Vitest。问题不在于AI的记忆力不行而在于你从未给它一份稳定的“记忆载体”。每次新会话它都像一个第一天入职的新员工对你的团队规矩、项目历史和当前的工作重点一无所知。你需要做的不是每次都重复口头培训而是为它准备一份标准化的“项目入职手册”。这就是CLAUDE.md文件的核心价值一个放在项目根目录的Markdown文件它能被Claude Code以及一些其他能读取项目文件的AI助手在每次会话开始时自动读取并作为上下文的一部分。这个简单的机制能将你与AI协作的效率和一致性提升一个数量级。本质上CLAUDE.md是一个高ROI的工程实践。它通过预设上下文极大地减少了你在每次会话中需要重复解释的背景信息、需要纠正的错误倾向所消耗的精力。对于Web开发、全栈开发等领域的从业者来说这尤其重要因为我们的项目往往有复杂的技术栈、严格的代码规范和特定的架构约束。这份文件不仅服务于AI也能成为你团队新成员的最佳入门指南迫使你将那些“只可意会”的团队规则书面化。2. CLAUDE.md的核心设计哲学与结构拆解CLAUDE.md的设计并非随意堆砌信息其背后有一套提升AI协作确定性的逻辑。它的核心目标是约束与引导约束AI不要做出不符合项目约定的“创造性”发挥引导它在你设定的框架内高效工作。2.1 设计原则从对抗到协作在没有明确指引的情况下AI模型如Claude的行为是基于其海量训练数据中的统计模式。它可能会采用它“见过”的最常见的做法但这常常与你的项目特定要求相悖。例如它可能默认使用console.log进行调试因为这在开源代码中太常见了或者它倾向于使用any类型来快速通过TypeScript检查。这种默认行为导致了你与AI之间的“对抗”——你不断地纠正它。CLAUDE.md通过提供先验知识将这种关系转变为“协作”。你提前告诉它“在我们的世界里规则是这样的。” AI会将这些规则视为当前会话的“最高指令”从而输出更符合你预期的结果。这类似于在函数式编程中提供不可变的状态或者在配置管理中声明环境变量都是为了消除不确定性。2.2 五大核心模块解析一个高效的CLAUDE.md通常包含五个模块每个模块解决一类特定的上下文缺失问题。1. 项目概览 (Project Overview)这是AI的“第一眼”。用3-5句话清晰定义项目的边界和核心职责。作用防止AI“越界”。它能明确告诉AI这个服务是做什么的负责哪个数据域以及绝对不可以修改哪些部分。这对于微服务架构或Monorepo项目至关重要。实操要点必须明确指出所有权的边界。例如“这是用户服务只处理/src/user/下的逻辑数据库schema是user。不要修改/src/payment/或/src/order/目录下的任何文件。” 模糊的表述会导致AI在重构时动到不该动的代码。2. 技术栈 (Tech Stack)明确到具体版本的技术选型清单。作用锁定技术环境避免版本漂移。AI训练数据涵盖了大量不同版本不提版本它可能会混合使用不同版本的语法或API。实操要点不仅要写“Node.js”更要写“Node.js 20.x (LTS)”。不仅要写“TypeScript”更要写“TypeScript 5.4 withstrict: true”。使用否定句强调排除项如“使用Prisma ORM不要写原始SQL查询”。这能直接覆盖AI的默认倾向。3. 编码规范 (Coding Conventions)将团队约定俗成的、但未在linter中强制规定的规则书面化。作用统一代码风格和设计模式使AI生成的代码看起来像出自同一人之手。实操要点这里应包含那些ESLint或Prettier管不到的“软性规则”。例如“异步处理统一使用async/await禁止使用.then().catch()链。”“错误处理使用ResultT, E模式来自neverthrow或自定义禁止使用throw。”“函数长度不超过30行超过必须拆分为私有函数。”“禁止用注释解释代码在做什么代码应自解释注释只用于解释‘为什么’这么做。”“导入模块必须使用路径别名/禁止使用相对路径../../../。”4. 禁止事项 (Do NOT)以否定形式列出高频“雷区”和破坏性操作。作用主动防御。AI具有“乐于助人”的倾向可能会主动添加日志、安装新包、修改遗留代码来“修复”它认为的问题。这个模块就是明确的“停止”信号。实操要点根据项目历史痛点来制定。例如“禁止添加console.log所有日志必须通过/src/utils/logger.ts输出。”“禁止修改/src/legacy/目录下的任何文件这是已冻结的代码。”“禁止未经许可在package.json中添加新的依赖包。”“禁止使用any类型如无法确定类型请使用unknown并做类型守卫。”“禁止提交TODO注释。如需后续处理请立即创建GitHub Issue并链接。”5. 当前上下文 (Current Focus)一个需要频繁更新的动态模块描述本周或当天的开发焦点。作用提供“情境感知”。让AI了解当前的工作流、正在进行的迁移、已知的缺陷以及需要避开的代码区域。实操要点这部分应该像团队的站会更新。例如“当前重点将用户认证模块从JWT迁移至Clerk。参考文档/docs/auth-migration.md。”“已知问题/src/api/login.ts中的速率限制在负载下存在漏洞修复方案正在feature/fix-rate-limit分支中测试。”“注意不要修改/src/db/schema.prisma文件因为有一个关于关系重构的PR#123正在评审中合并前任何修改都会导致冲突。”注意CLAUDE.md是一个活文档。特别是“当前上下文”部分应该随着开发进程每天或每周更新。一个过时的上下文比没有上下文更危险因为它会引导AI基于错误的前提进行工作。3. 高级用法与工程化实践当基础用法熟练后你可以通过一些高级技巧和工程化思维将CLAUDE.md的效用最大化并规避其潜在的成本问题。3.1 嵌套CLAUDE.md与作用域管理对于大型项目或Monorepo单一的根目录CLAUDE.md可能不够精细。Claude Code支持读取嵌套的CLAUDE.md文件这允许你进行作用域化的上下文管理。my-monorepo/ ├── CLAUDE.md # 全局规则通用代码规范、包管理器、提交规范 ├── packages/ │ ├── web-app/ │ │ ├── CLAUDE.md # 前端特定规则React 18, Vite, Tailwind, 组件规范 │ │ └── src/ │ └── api-service/ │ ├── CLAUDE.md # 后端特定规则Node.js, Fastify, 数据库客户端使用规范 │ └── src/ └── shared/ └── CLAUDE.md # 共享库规则纯函数、无副作用、严格版本导出工作机制当你在packages/web-app/src/components/目录下开启会话时Claude Code会同时读取项目根目录和packages/web-app/下的CLAUDE.md文件并将两者内容合并。嵌套文件的规则可以覆盖或细化全局规则。例如全局规则说“用Jest”但前端项目可能指定“用Vitest React Testing Library”。这种结构使得上下文既有一致性又有灵活性。实操心得在嵌套文件中你可以引用相对路径的文档。例如在API服务的CLAUDE.md里写“数据库操作必须通过/src/lib/db.ts封装的客户端其使用规范详见/docs/db-best-practices.md。” 这样既保持了主文件的简洁又提供了深度信息的入口。3.2 应对令牌限制与成本优化策略CLAUDE.md的每个字符都会消耗AI模型的上下文令牌Token。一个冗长的CLAUDE.md会持续占用宝贵的上下文窗口导致你在长会话中更早地触及模型的令牌上限或者因为处理更多令牌而增加API调用成本。策略一保持精简与引用这是最重要的原则。CLAUDE.md不应成为你的全部项目文档。它应该是指南针而不是百科全书。只放非协商性规则和当前焦点项目结构、绝对不能违反的约定、本周的优先事项。详细文档外部化将架构图、详细的API规范、复杂的业务逻辑说明放在/docs/目录下的独立Markdown文件中然后在CLAUDE.md里引用。## 架构与深入规范 * 系统整体架构请参考/docs/architecture.md * REST API设计规范详见/docs/api-conventions.md * 数据库分库分表策略见/docs/db-sharding.md当AI需要深入理解某个部分时你可以手动将这些文件拖入会话实现按需加载上下文而不是一次性全量加载。策略二区分长期与短期上下文将CLAUDE.md的内容分为两部分思考长期稳定上下文技术栈、核心编码规范、项目边界。这部分变动小是CLAUDE.md的基石。短期动态上下文“当前焦点”部分。这部分应高度精简并且勤于更新。一旦某个迁移完成或某个PR合并就应立即从文件中移除相关说明避免积累无效信息。策略三经济高效的API访问方案原文提到了一个关于成本的实践点如果你频繁使用Claude Code并遇到速率限制或成本问题可以考虑通过配置ANTHROPIC_BASE_URL环境变量将请求代理到一些提供更优定价的第三方服务。这类服务通常以较低的固定月费提供对Claude API的访问对于需要长时间、高频率会话的开发者或小团队来说可以显著降低使用门槛使得维护一个“富上下文”的CLAUDE.md在经济上更加可持续。当然在选择此类服务时务必关注其稳定性、数据隐私政策以及与官方API的同步延迟。3.3 将CLAUDE.md融入开发工作流要让CLAUDE.md发挥最大价值就不能让它只是一个孤立的文件而应将其集成到团队的开发流程中。1. 版本控制与共享将CLAUDE.md提交到Git仓库中。这确保了团队每个成员拉取代码后都能立即获得相同的AI协作上下文。它应该像README.md或.gitignore一样成为项目模板的一部分。2. 作为新成员入职工具正如原文所说一个写好的CLAUDE.md本身就是一份极佳的项目入门文档。新同事可以通过阅读它快速了解项目的技术边界、代码风格和当前的“战斗状态”这比口口相传或翻阅零散的文档要高效得多。这倒逼团队将隐性知识显性化改善了团队的知识管理。3. 与代码审查结合在代码审查Code Review时可以将CLAUDE.md作为审查依据之一。如果AI生成的代码或团队成员提交的代码违反了CLAUDE.md中明确的规范例如使用了禁止的any类型审查者可以立即指出这使规范执行有了白纸黑字的依据。4. 定期回顾与更新建议在团队周会或迭代回顾会上花几分钟时间审视CLAUDE.md特别是“当前焦点”和“禁止事项”部分。是否有新的痛点需要加入“禁止事项”“当前焦点”是否已经过时技术栈是否需要升级保持文件的时效性和相关性是其生命力的关键。4. 实战案例从零构建一个Web项目的CLAUDE.md让我们以一个假设的“任务管理后端服务”TaskMaster API为例从头构建一份详实的CLAUDE.md。我们将看到每个部分如何具体落地。# 项目TaskMaster API 这是一个基于Node.js的RESTful API服务专门处理用户任务Todo的创建、更新、查询和删除。它独立拥有taskmaster数据库schema。本项目位于一个Monorepo中请不要修改/packages/web-frontend/或/packages/shared-auth/中的任何代码。 ## 技术栈 - **运行时**: Node.js 20.x (请勿使用18.x或更早版本我们依赖了Node 20的稳定Fetch API) - **语言**: TypeScript 5.4必须开启严格模式 (strict: true) - **Web框架**: Fastify 4.x (禁用Express) - **ORM/数据库**: Prisma 5.x PostgreSQL。所有数据库操作**必须**通过Prisma Client禁止手写原始SQL字符串。 - **测试**: Vitest 1.x Supertest。单元测试和集成测试都放在/__tests__/目录下。 - **包管理器**: pnpm 8.x (Monorepo根目录已配置请勿使用npm或yarn安装依赖) - **代码风格**: ESLint (Airbnb配置扩展) Prettier。提交前必须通过pnpm run lint和pnpm run format。 ## 编码规范 1. **异步处理**: 统一使用 async/await。禁止使用 .then()、.catch() 链式调用。 2. **错误处理**: 使用 Result 模式。所有服务层函数应返回 ResultT, Error 类型使用 neverthrow 库。控制器层负责将 Result 转换为HTTP响应。禁止在业务逻辑中 throw 错误。 3. **依赖注入**: 核心业务逻辑服务层应通过构造函数接收其依赖如数据库仓库、邮件客户端。这便于测试。 4. **文件与函数组织**: - 遵循“控制器-服务-仓库”分层架构。文件路径src/modules/[module]/[controller|service|repository].ts。 - 每个函数长度原则上不超过30行。如果逻辑复杂请拆分为多个私有函数或工具函数。 - 使用具名导出export function默认导出仅用于Vue/React组件。 5. **日志记录**: 使用配置好的Pino日志实例 (src/lib/logger.ts)。根据日志级别 (debug, info, warn, error) 正确使用。**禁止**在代码中遗留 console.log。 6. **注释哲学**: 代码应自解释。禁止添加“这里循环数组”之类的注释。注释只用于解释“为什么”采用某种复杂或非常规的实现方式并可以链接到相关的Issue或PR。 ## 禁止事项 - **绝对禁止**修改 src/legacy/v1/ 目录下的任何文件。这是已废弃的API版本仅供只读参考。 - **禁止**在 package.json 中直接添加新的依赖。请先创建RFC文档或在团队频道讨论。 - **禁止**在TypeScript中使用 any 类型。如果类型暂时难以确定使用 unknown 并添加必要的类型守卫。 - **禁止**提交包含 TODO、FIXME、XXX 等标记的代码。如有待办事项请立即创建GitHub Issue并在提交信息中引用Issue编号如 fix: #123。 - **禁止**在API路由处理函数中直接进行数据库查询。必须通过对应的Service层调用。 ## 当前焦点 (更新于2023-10-27) 1. **性能优化**: 我们正在优化任务列表查询接口 (GET /api/v2/tasks)该接口在数据量过大时响应缓慢。相关优化方案见 docs/performance-optimization.md。请避免对该接口的查询逻辑进行大规模重构。 2. **进行中的PR**: PR #158 正在重构用户权限验证中间件。在它合并之前请勿修改 src/middleware/auth.ts 文件以免造成冲突。 3. **已知问题**: 任务提醒的推送通知 (src/services/notification.service.ts) 在特定时区存在重复发送的bug。临时修复已部署根治方案正在 feature/fix-notification-dup 分支中测试。请暂时不要改动该服务的核心调度逻辑。这份CLAUDE.md为AI提供了一个坚实、明确的协作框架。它知道项目的边界、该用什么工具、该怎么写代码、什么不能碰以及当前团队正在忙什么。这能确保无论是周一还是周五AI都能以一个“知情者”的身份与你合作。5. 常见陷阱、排查与效果评估即使有了CLAUDE.md在实践中也可能遇到问题。以下是一些常见情况的排查思路和注意事项。5.1 为什么CLAUDE.md似乎“没生效”问题1AI仍然给出了违反规则的代码。排查首先确认你的Claude Code会话是否确实在项目根目录或包含CLAUDE.md的子目录中开启。有些编辑器插件可能需要手动刷新或重新加载工作区才能识别新文件。检查CLAUDE.md中的规则是否足够具体、无歧义“使用严格模式”不如“TypeScript配置中strict: true”明确。“不要用console.log”不如“所有日志必须通过src/lib/logger.ts输出”有效。可能性AI模型并非完美遵循指令尤其在复杂或冲突的指令下。如果规则太多太杂它可能会忽略或混淆某一条。尝试简化规则或将最关键的规则如禁止事项放在更靠前的位置。问题2会话中后期AI开始“遗忘”CLAUDE.md的内容。原因这是上下文窗口限制的典型表现。随着会话轮次对话历史增长最早的上下文包括CLAUDE.md可能会被“挤出”模型的注意力窗口。解决方案精简CLAUDE.md这是首要任务。移除所有非核心信息将详细文档外链。主动提醒在关键对话节点可以手动输入简短的指令进行重申例如“请记住我们使用Result模式处理错误不要throw。”开启新会话对于全新的、复杂的任务与其在一个冗长的旧会话中继续不如开启一个包含最新CLAUDE.md的新会话这样能保证AI拥有最清晰的初始上下文。5.2 效果评估与迭代如何判断你的CLAUDE.md是否有效可以从以下几个维度评估纠正频率下降记录你在没有CLAUDE.md时平均每次会话需要纠正AI多少次例如“不要用any”“请用async/await”。建立CLAUDE.md后这个频率应该显著下降。代码合并率提升观察AI生成的代码在稍作修改或无需修改的情况下直接能够提交或通过初步审查的比例是否提高。心智负担减轻主观感受上你是否觉得和AI沟通更顺畅了不再需要反复强调基础规则迭代你的CLAUDE.md这份文件不是一成不变的。它是一个不断优化的工具。收集反馈每当你在会话中不得不纠正AI一个重复性错误时就问自己“这个规则应该被加到CLAUDE.md里吗”定期清理每过一个开发周期如一个Sprint回顾“当前焦点”和“禁止事项”。移除已解决的事项添加新出现的问题。团队评审在团队内部共享和评审CLAUDE.md确保它反映了团队的共识而不是个人的偏好。5.3 超越CLAUDE.md生态工具与未来展望CLAUDE.md的理念可以扩展到整个AI辅助开发工作流。IDE插件增强未来可能会有专门的IDE插件不仅能读取CLAUDE.md还能根据当前打开的文件类型动态注入更具体的规则例如打开一个.test.ts文件时自动加入测试相关的规范。与Linter/Formatter集成想象一下ESLint规则可以直接从CLAUDE.md的“编码规范”部分自动生成或同步实现从“文档约束”到“工具强制”的无缝衔接。项目模板化你可以为不同类型项目如“Next.js全栈应用”、“Node.js微服务”、“React组件库”创建带有预制CLAUDE.md的模板。这样每次启动新项目时AI协作的最佳实践就已经内置其中。我个人在多个项目中实践CLAUDE.md超过半年最深的体会是它最大的价值不仅仅是让AI更听话更是迫使我自己和团队将开发规范显式化、文档化。很多模糊的“我们一般都这样写”的规则在要写入CLAUDE.md的那一刻必须被清晰地定义出来。这个过程本身就能减少团队内的认知摩擦。对于AI来说这是一份操作手册对于团队来说这是一份不断演进的开发宪法。从今天开始为你最重要的项目创建一个CLAUDE.md文件你会立刻感受到那种上下文对齐带来的流畅感。
CLAUDE.md：为AI编码助手创建项目上下文手册，提升协作效率
发布时间：2026/5/26 6:50:19
1. 项目概述为什么你的AI编码助手需要一份“入职手册”如果你用过Claude Code、Cursor或者GitHub Copilot超过一周大概率会遇到一个让人抓狂的问题AI的“失忆症”。周一你刚花半小时调教好它让它记住了你的项目结构、编码规范甚至你个人对TypeScript严格模式的执念。它表现得像个合作多年的老搭档代码写得又快又准。到了周五你打开同一个项目开启一个新的会话它仿佛被格式化了——开始建议你用JavaScript提议使用你明确禁止的设计模式甚至忘了你项目用的是Jest而不是Vitest。问题不在于AI的记忆力不行而在于你从未给它一份稳定的“记忆载体”。每次新会话它都像一个第一天入职的新员工对你的团队规矩、项目历史和当前的工作重点一无所知。你需要做的不是每次都重复口头培训而是为它准备一份标准化的“项目入职手册”。这就是CLAUDE.md文件的核心价值一个放在项目根目录的Markdown文件它能被Claude Code以及一些其他能读取项目文件的AI助手在每次会话开始时自动读取并作为上下文的一部分。这个简单的机制能将你与AI协作的效率和一致性提升一个数量级。本质上CLAUDE.md是一个高ROI的工程实践。它通过预设上下文极大地减少了你在每次会话中需要重复解释的背景信息、需要纠正的错误倾向所消耗的精力。对于Web开发、全栈开发等领域的从业者来说这尤其重要因为我们的项目往往有复杂的技术栈、严格的代码规范和特定的架构约束。这份文件不仅服务于AI也能成为你团队新成员的最佳入门指南迫使你将那些“只可意会”的团队规则书面化。2. CLAUDE.md的核心设计哲学与结构拆解CLAUDE.md的设计并非随意堆砌信息其背后有一套提升AI协作确定性的逻辑。它的核心目标是约束与引导约束AI不要做出不符合项目约定的“创造性”发挥引导它在你设定的框架内高效工作。2.1 设计原则从对抗到协作在没有明确指引的情况下AI模型如Claude的行为是基于其海量训练数据中的统计模式。它可能会采用它“见过”的最常见的做法但这常常与你的项目特定要求相悖。例如它可能默认使用console.log进行调试因为这在开源代码中太常见了或者它倾向于使用any类型来快速通过TypeScript检查。这种默认行为导致了你与AI之间的“对抗”——你不断地纠正它。CLAUDE.md通过提供先验知识将这种关系转变为“协作”。你提前告诉它“在我们的世界里规则是这样的。” AI会将这些规则视为当前会话的“最高指令”从而输出更符合你预期的结果。这类似于在函数式编程中提供不可变的状态或者在配置管理中声明环境变量都是为了消除不确定性。2.2 五大核心模块解析一个高效的CLAUDE.md通常包含五个模块每个模块解决一类特定的上下文缺失问题。1. 项目概览 (Project Overview)这是AI的“第一眼”。用3-5句话清晰定义项目的边界和核心职责。作用防止AI“越界”。它能明确告诉AI这个服务是做什么的负责哪个数据域以及绝对不可以修改哪些部分。这对于微服务架构或Monorepo项目至关重要。实操要点必须明确指出所有权的边界。例如“这是用户服务只处理/src/user/下的逻辑数据库schema是user。不要修改/src/payment/或/src/order/目录下的任何文件。” 模糊的表述会导致AI在重构时动到不该动的代码。2. 技术栈 (Tech Stack)明确到具体版本的技术选型清单。作用锁定技术环境避免版本漂移。AI训练数据涵盖了大量不同版本不提版本它可能会混合使用不同版本的语法或API。实操要点不仅要写“Node.js”更要写“Node.js 20.x (LTS)”。不仅要写“TypeScript”更要写“TypeScript 5.4 withstrict: true”。使用否定句强调排除项如“使用Prisma ORM不要写原始SQL查询”。这能直接覆盖AI的默认倾向。3. 编码规范 (Coding Conventions)将团队约定俗成的、但未在linter中强制规定的规则书面化。作用统一代码风格和设计模式使AI生成的代码看起来像出自同一人之手。实操要点这里应包含那些ESLint或Prettier管不到的“软性规则”。例如“异步处理统一使用async/await禁止使用.then().catch()链。”“错误处理使用ResultT, E模式来自neverthrow或自定义禁止使用throw。”“函数长度不超过30行超过必须拆分为私有函数。”“禁止用注释解释代码在做什么代码应自解释注释只用于解释‘为什么’这么做。”“导入模块必须使用路径别名/禁止使用相对路径../../../。”4. 禁止事项 (Do NOT)以否定形式列出高频“雷区”和破坏性操作。作用主动防御。AI具有“乐于助人”的倾向可能会主动添加日志、安装新包、修改遗留代码来“修复”它认为的问题。这个模块就是明确的“停止”信号。实操要点根据项目历史痛点来制定。例如“禁止添加console.log所有日志必须通过/src/utils/logger.ts输出。”“禁止修改/src/legacy/目录下的任何文件这是已冻结的代码。”“禁止未经许可在package.json中添加新的依赖包。”“禁止使用any类型如无法确定类型请使用unknown并做类型守卫。”“禁止提交TODO注释。如需后续处理请立即创建GitHub Issue并链接。”5. 当前上下文 (Current Focus)一个需要频繁更新的动态模块描述本周或当天的开发焦点。作用提供“情境感知”。让AI了解当前的工作流、正在进行的迁移、已知的缺陷以及需要避开的代码区域。实操要点这部分应该像团队的站会更新。例如“当前重点将用户认证模块从JWT迁移至Clerk。参考文档/docs/auth-migration.md。”“已知问题/src/api/login.ts中的速率限制在负载下存在漏洞修复方案正在feature/fix-rate-limit分支中测试。”“注意不要修改/src/db/schema.prisma文件因为有一个关于关系重构的PR#123正在评审中合并前任何修改都会导致冲突。”注意CLAUDE.md是一个活文档。特别是“当前上下文”部分应该随着开发进程每天或每周更新。一个过时的上下文比没有上下文更危险因为它会引导AI基于错误的前提进行工作。3. 高级用法与工程化实践当基础用法熟练后你可以通过一些高级技巧和工程化思维将CLAUDE.md的效用最大化并规避其潜在的成本问题。3.1 嵌套CLAUDE.md与作用域管理对于大型项目或Monorepo单一的根目录CLAUDE.md可能不够精细。Claude Code支持读取嵌套的CLAUDE.md文件这允许你进行作用域化的上下文管理。my-monorepo/ ├── CLAUDE.md # 全局规则通用代码规范、包管理器、提交规范 ├── packages/ │ ├── web-app/ │ │ ├── CLAUDE.md # 前端特定规则React 18, Vite, Tailwind, 组件规范 │ │ └── src/ │ └── api-service/ │ ├── CLAUDE.md # 后端特定规则Node.js, Fastify, 数据库客户端使用规范 │ └── src/ └── shared/ └── CLAUDE.md # 共享库规则纯函数、无副作用、严格版本导出工作机制当你在packages/web-app/src/components/目录下开启会话时Claude Code会同时读取项目根目录和packages/web-app/下的CLAUDE.md文件并将两者内容合并。嵌套文件的规则可以覆盖或细化全局规则。例如全局规则说“用Jest”但前端项目可能指定“用Vitest React Testing Library”。这种结构使得上下文既有一致性又有灵活性。实操心得在嵌套文件中你可以引用相对路径的文档。例如在API服务的CLAUDE.md里写“数据库操作必须通过/src/lib/db.ts封装的客户端其使用规范详见/docs/db-best-practices.md。” 这样既保持了主文件的简洁又提供了深度信息的入口。3.2 应对令牌限制与成本优化策略CLAUDE.md的每个字符都会消耗AI模型的上下文令牌Token。一个冗长的CLAUDE.md会持续占用宝贵的上下文窗口导致你在长会话中更早地触及模型的令牌上限或者因为处理更多令牌而增加API调用成本。策略一保持精简与引用这是最重要的原则。CLAUDE.md不应成为你的全部项目文档。它应该是指南针而不是百科全书。只放非协商性规则和当前焦点项目结构、绝对不能违反的约定、本周的优先事项。详细文档外部化将架构图、详细的API规范、复杂的业务逻辑说明放在/docs/目录下的独立Markdown文件中然后在CLAUDE.md里引用。## 架构与深入规范 * 系统整体架构请参考/docs/architecture.md * REST API设计规范详见/docs/api-conventions.md * 数据库分库分表策略见/docs/db-sharding.md当AI需要深入理解某个部分时你可以手动将这些文件拖入会话实现按需加载上下文而不是一次性全量加载。策略二区分长期与短期上下文将CLAUDE.md的内容分为两部分思考长期稳定上下文技术栈、核心编码规范、项目边界。这部分变动小是CLAUDE.md的基石。短期动态上下文“当前焦点”部分。这部分应高度精简并且勤于更新。一旦某个迁移完成或某个PR合并就应立即从文件中移除相关说明避免积累无效信息。策略三经济高效的API访问方案原文提到了一个关于成本的实践点如果你频繁使用Claude Code并遇到速率限制或成本问题可以考虑通过配置ANTHROPIC_BASE_URL环境变量将请求代理到一些提供更优定价的第三方服务。这类服务通常以较低的固定月费提供对Claude API的访问对于需要长时间、高频率会话的开发者或小团队来说可以显著降低使用门槛使得维护一个“富上下文”的CLAUDE.md在经济上更加可持续。当然在选择此类服务时务必关注其稳定性、数据隐私政策以及与官方API的同步延迟。3.3 将CLAUDE.md融入开发工作流要让CLAUDE.md发挥最大价值就不能让它只是一个孤立的文件而应将其集成到团队的开发流程中。1. 版本控制与共享将CLAUDE.md提交到Git仓库中。这确保了团队每个成员拉取代码后都能立即获得相同的AI协作上下文。它应该像README.md或.gitignore一样成为项目模板的一部分。2. 作为新成员入职工具正如原文所说一个写好的CLAUDE.md本身就是一份极佳的项目入门文档。新同事可以通过阅读它快速了解项目的技术边界、代码风格和当前的“战斗状态”这比口口相传或翻阅零散的文档要高效得多。这倒逼团队将隐性知识显性化改善了团队的知识管理。3. 与代码审查结合在代码审查Code Review时可以将CLAUDE.md作为审查依据之一。如果AI生成的代码或团队成员提交的代码违反了CLAUDE.md中明确的规范例如使用了禁止的any类型审查者可以立即指出这使规范执行有了白纸黑字的依据。4. 定期回顾与更新建议在团队周会或迭代回顾会上花几分钟时间审视CLAUDE.md特别是“当前焦点”和“禁止事项”部分。是否有新的痛点需要加入“禁止事项”“当前焦点”是否已经过时技术栈是否需要升级保持文件的时效性和相关性是其生命力的关键。4. 实战案例从零构建一个Web项目的CLAUDE.md让我们以一个假设的“任务管理后端服务”TaskMaster API为例从头构建一份详实的CLAUDE.md。我们将看到每个部分如何具体落地。# 项目TaskMaster API 这是一个基于Node.js的RESTful API服务专门处理用户任务Todo的创建、更新、查询和删除。它独立拥有taskmaster数据库schema。本项目位于一个Monorepo中请不要修改/packages/web-frontend/或/packages/shared-auth/中的任何代码。 ## 技术栈 - **运行时**: Node.js 20.x (请勿使用18.x或更早版本我们依赖了Node 20的稳定Fetch API) - **语言**: TypeScript 5.4必须开启严格模式 (strict: true) - **Web框架**: Fastify 4.x (禁用Express) - **ORM/数据库**: Prisma 5.x PostgreSQL。所有数据库操作**必须**通过Prisma Client禁止手写原始SQL字符串。 - **测试**: Vitest 1.x Supertest。单元测试和集成测试都放在/__tests__/目录下。 - **包管理器**: pnpm 8.x (Monorepo根目录已配置请勿使用npm或yarn安装依赖) - **代码风格**: ESLint (Airbnb配置扩展) Prettier。提交前必须通过pnpm run lint和pnpm run format。 ## 编码规范 1. **异步处理**: 统一使用 async/await。禁止使用 .then()、.catch() 链式调用。 2. **错误处理**: 使用 Result 模式。所有服务层函数应返回 ResultT, Error 类型使用 neverthrow 库。控制器层负责将 Result 转换为HTTP响应。禁止在业务逻辑中 throw 错误。 3. **依赖注入**: 核心业务逻辑服务层应通过构造函数接收其依赖如数据库仓库、邮件客户端。这便于测试。 4. **文件与函数组织**: - 遵循“控制器-服务-仓库”分层架构。文件路径src/modules/[module]/[controller|service|repository].ts。 - 每个函数长度原则上不超过30行。如果逻辑复杂请拆分为多个私有函数或工具函数。 - 使用具名导出export function默认导出仅用于Vue/React组件。 5. **日志记录**: 使用配置好的Pino日志实例 (src/lib/logger.ts)。根据日志级别 (debug, info, warn, error) 正确使用。**禁止**在代码中遗留 console.log。 6. **注释哲学**: 代码应自解释。禁止添加“这里循环数组”之类的注释。注释只用于解释“为什么”采用某种复杂或非常规的实现方式并可以链接到相关的Issue或PR。 ## 禁止事项 - **绝对禁止**修改 src/legacy/v1/ 目录下的任何文件。这是已废弃的API版本仅供只读参考。 - **禁止**在 package.json 中直接添加新的依赖。请先创建RFC文档或在团队频道讨论。 - **禁止**在TypeScript中使用 any 类型。如果类型暂时难以确定使用 unknown 并添加必要的类型守卫。 - **禁止**提交包含 TODO、FIXME、XXX 等标记的代码。如有待办事项请立即创建GitHub Issue并在提交信息中引用Issue编号如 fix: #123。 - **禁止**在API路由处理函数中直接进行数据库查询。必须通过对应的Service层调用。 ## 当前焦点 (更新于2023-10-27) 1. **性能优化**: 我们正在优化任务列表查询接口 (GET /api/v2/tasks)该接口在数据量过大时响应缓慢。相关优化方案见 docs/performance-optimization.md。请避免对该接口的查询逻辑进行大规模重构。 2. **进行中的PR**: PR #158 正在重构用户权限验证中间件。在它合并之前请勿修改 src/middleware/auth.ts 文件以免造成冲突。 3. **已知问题**: 任务提醒的推送通知 (src/services/notification.service.ts) 在特定时区存在重复发送的bug。临时修复已部署根治方案正在 feature/fix-notification-dup 分支中测试。请暂时不要改动该服务的核心调度逻辑。这份CLAUDE.md为AI提供了一个坚实、明确的协作框架。它知道项目的边界、该用什么工具、该怎么写代码、什么不能碰以及当前团队正在忙什么。这能确保无论是周一还是周五AI都能以一个“知情者”的身份与你合作。5. 常见陷阱、排查与效果评估即使有了CLAUDE.md在实践中也可能遇到问题。以下是一些常见情况的排查思路和注意事项。5.1 为什么CLAUDE.md似乎“没生效”问题1AI仍然给出了违反规则的代码。排查首先确认你的Claude Code会话是否确实在项目根目录或包含CLAUDE.md的子目录中开启。有些编辑器插件可能需要手动刷新或重新加载工作区才能识别新文件。检查CLAUDE.md中的规则是否足够具体、无歧义“使用严格模式”不如“TypeScript配置中strict: true”明确。“不要用console.log”不如“所有日志必须通过src/lib/logger.ts输出”有效。可能性AI模型并非完美遵循指令尤其在复杂或冲突的指令下。如果规则太多太杂它可能会忽略或混淆某一条。尝试简化规则或将最关键的规则如禁止事项放在更靠前的位置。问题2会话中后期AI开始“遗忘”CLAUDE.md的内容。原因这是上下文窗口限制的典型表现。随着会话轮次对话历史增长最早的上下文包括CLAUDE.md可能会被“挤出”模型的注意力窗口。解决方案精简CLAUDE.md这是首要任务。移除所有非核心信息将详细文档外链。主动提醒在关键对话节点可以手动输入简短的指令进行重申例如“请记住我们使用Result模式处理错误不要throw。”开启新会话对于全新的、复杂的任务与其在一个冗长的旧会话中继续不如开启一个包含最新CLAUDE.md的新会话这样能保证AI拥有最清晰的初始上下文。5.2 效果评估与迭代如何判断你的CLAUDE.md是否有效可以从以下几个维度评估纠正频率下降记录你在没有CLAUDE.md时平均每次会话需要纠正AI多少次例如“不要用any”“请用async/await”。建立CLAUDE.md后这个频率应该显著下降。代码合并率提升观察AI生成的代码在稍作修改或无需修改的情况下直接能够提交或通过初步审查的比例是否提高。心智负担减轻主观感受上你是否觉得和AI沟通更顺畅了不再需要反复强调基础规则迭代你的CLAUDE.md这份文件不是一成不变的。它是一个不断优化的工具。收集反馈每当你在会话中不得不纠正AI一个重复性错误时就问自己“这个规则应该被加到CLAUDE.md里吗”定期清理每过一个开发周期如一个Sprint回顾“当前焦点”和“禁止事项”。移除已解决的事项添加新出现的问题。团队评审在团队内部共享和评审CLAUDE.md确保它反映了团队的共识而不是个人的偏好。5.3 超越CLAUDE.md生态工具与未来展望CLAUDE.md的理念可以扩展到整个AI辅助开发工作流。IDE插件增强未来可能会有专门的IDE插件不仅能读取CLAUDE.md还能根据当前打开的文件类型动态注入更具体的规则例如打开一个.test.ts文件时自动加入测试相关的规范。与Linter/Formatter集成想象一下ESLint规则可以直接从CLAUDE.md的“编码规范”部分自动生成或同步实现从“文档约束”到“工具强制”的无缝衔接。项目模板化你可以为不同类型项目如“Next.js全栈应用”、“Node.js微服务”、“React组件库”创建带有预制CLAUDE.md的模板。这样每次启动新项目时AI协作的最佳实践就已经内置其中。我个人在多个项目中实践CLAUDE.md超过半年最深的体会是它最大的价值不仅仅是让AI更听话更是迫使我自己和团队将开发规范显式化、文档化。很多模糊的“我们一般都这样写”的规则在要写入CLAUDE.md的那一刻必须被清晰地定义出来。这个过程本身就能减少团队内的认知摩擦。对于AI来说这是一份操作手册对于团队来说这是一份不断演进的开发宪法。从今天开始为你最重要的项目创建一个CLAUDE.md文件你会立刻感受到那种上下文对齐带来的流畅感。
