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 with strict: true ”。使用否定句强调排除项，如“使用Prisma ORM， 不要 写原始SQL查询”。这能直接覆盖AI的默认倾向。

3. 编码规范 (Coding Conventions) 将团队约定俗成的、但未在linter中强制规定的规则书面化。

• 作用 ：统一代码风格和设计模式，使AI生成的代码看起来像出自同一人之手。
• 实操要点 ：这里应包含那些ESLint或Prettier管不到的“软性规则”。例如：
  • “异步处理统一使用 async/await ，禁止使用 .then().catch() 链。”
  • “错误处理使用 Result<T, 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 的内容分为两部分思考：

1. 长期稳定上下文 ：技术栈、核心编码规范、项目边界。这部分变动小，是 CLAUDE.md 的基石。
2. 短期动态上下文 ：“当前焦点”部分。这部分应高度精简，并且勤于更新。一旦某个迁移完成或某个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` 模式。所有服务层函数应返回 `Result<T, 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似乎“没生效”？

问题1：AI仍然给出了违反规则的代码。

• 排查 ：首先确认你的Claude Code会话是否确实在项目根目录（或包含 CLAUDE.md 的子目录）中开启。有些编辑器插件可能需要手动刷新或重新加载工作区才能识别新文件。
• 检查 ： CLAUDE.md 中的规则是否足够具体、无歧义？“使用严格模式”不如“TypeScript配置中 strict: true ”明确。“不要用console.log”不如“所有日志必须通过 src/lib/logger.ts 输出”有效。
• 可能性 ：AI模型并非完美遵循指令，尤其在复杂或冲突的指令下。如果规则太多太杂，它可能会忽略或混淆某一条。尝试简化规则，或将最关键的规则（如禁止事项）放在更靠前的位置。

问题2：会话中后期，AI开始“遗忘”CLAUDE.md的内容。

• 原因 ：这是上下文窗口限制的典型表现。随着会话轮次（对话历史）增长，最早的上下文（包括 CLAUDE.md ）可能会被“挤出”模型的注意力窗口。
• 解决方案 ：
  1. 精简 CLAUDE.md ：这是首要任务。移除所有非核心信息，将详细文档外链。
  2. 主动提醒 ：在关键对话节点，可以手动输入简短的指令进行重申，例如：“请记住，我们使用Result模式处理错误，不要throw。”
  3. 开启新会话 ：对于全新的、复杂的任务，与其在一个冗长的旧会话中继续，不如开启一个包含最新 CLAUDE.md 的新会话，这样能保证AI拥有最清晰的初始上下文。

5.2 效果评估与迭代

如何判断你的 CLAUDE.md 是否有效？可以从以下几个维度评估：

1. 纠正频率下降 ：记录你在没有 CLAUDE.md 时，平均每次会话需要纠正AI多少次（例如：“不要用any”，“请用async/await”）。建立 CLAUDE.md 后，这个频率应该显著下降。
2. 代码合并率提升 ：观察AI生成的代码，在稍作修改或无需修改的情况下，直接能够提交或通过初步审查的比例是否提高。
3. 心智负担减轻 ：主观感受上，你是否觉得和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 文件，你会立刻感受到那种上下文对齐带来的流畅感。