为什么 CLAUDE.md 是代码库中最重要的文件

Source: Dev.to

问题：上下文遗忘

每次启动 Claude Code 会话时，你都在和一个极其能干的工程师对话，而它对你的项目一无所知——不了解你的文件夹结构、命名约定、部署流水线或遗留的变通方案。

没有上下文，Claude 会做出合理但错误的假设：

• 在错误的目录创建文件
• 当你的项目使用 pnpm 时却使用 npm
• 当其他代码都是 TypeScript 时生成 JavaScript
• 当你使用 Vitest 时却写 Jest 测试

结果是？你花的时间比自己写代码还多，用来纠正 Claude 的错误。

解决方案：CLAUDE.md

CLAUDE.md 放在项目根目录，Claude Code 每次启动会话时会自动加载它。把它当作 AI 队友的入职文档——他们在第一天就能获得所有需要了解的信息。

CLAUDE.md 应该包含什么

1. 项目概述

## Project Overview
BuildrFlags is a multi-tenant feature flag SaaS built with Next.js 15,
AWS Lambda, and DynamoDB. Targets small-to-medium engineering teams.

2. 技术栈与约定

## Tech Stack
- Language: TypeScript (strict mode, ESM, no `any`)
- Frontend: Next.js 15, React 19, Tailwind CSS v4, shadcn/ui
- Backend: AWS Lambda (Node.js 20+), API Gateway HTTP API v2
- Database: DynamoDB (single-table design)
- Package manager: pnpm v9+
- Testing: Vitest (unit), Playwright (E2E)

3. 文件结构

## Structure
- `src/app/` — Next.js app router pages
- `src/components/` — React components (co‑located with pages)
- `infra/` — Terraform modules
- `tasks/` — Task tracking (todo.md, done.md)

4. 命令

## Commands
- `pnpm dev` — Start dev server
- `pnpm test` — Run Vitest
- `pnpm lint` — ESLint check
- `pnpm build` — Production build

5. 规则

## Rules
- NEVER push directly to main — always create a PR targeting dev
- Read files before modifying them — don't guess at content
- Run tests after every change
- Use single-table DynamoDB design — no new tables without approval
- All API responses must include CORS headers

实际效果

自从在项目中采用 CLAUDE.md 以后：

• 首次尝试的准确率 从约 60 % 提升到 >90 %
• 会话启动时间 从需要 5–10 分钟的上下文设置降至零
• 代码审查的修改量 下降约 70 %
• 新成员入职 变得极其轻松——他们阅读的文件就是 Claude 阅读的文件

当我们在 Workhuman 推广 Claude Code 时，结构化的 CLAUDE.md 成为实现 60 % 迁移工作量降低 的基石，帮助他们完成 Java 现代化项目。

实战技巧

• 从小开始，持续迭代。 第一个 CLAUDE.md 不会完美。每次 Claude 做出错误假设时，添加相应规则防止下次再出现。
• 要指令化，而非描述化。 与其写 “我们更倾向于使用 TypeScript”，不如写 “Language: TypeScript (strict, ESM, no any)”。Claude 对直接指令的响应更好。
• 加入“不该怎么做”的示例。 Claude 同样能从反模式中学习。
• 保持在 500 行以内。 CLAUDE.md 每次会话都会加载进上下文。2000 行的文件会浪费 token 并稀释重要信息。
• 在 git 中进行版本管理。 这是一份随项目演进的活文档。像审查代码一样在 PR 中审查变更。

更大的视角

CLAUDE.md 不仅是 Claude Code 的一个功能——它还是推动良好工程实践的强制手段。如果你不能用一个 markdown 文件清晰阐述项目的约定、结构和规则，那么你的人工团队成员大概也在为同样的模糊感苦恼。

最好的 CLAUDE.md 文件会成为事实上的项目文档——对人类和 AI 都同样有价值。