每个 Claude Code 会话都从读取一个文件开始：CLAUDE.md。在你的第一个提示之前，在任何代码之前，在任何事情发生之前，Claude 会读取这个文件，并将其作为整个会话的根本事实。
大多数人要么没有这个文件，要么他们的文件有 300 行的个性化指令。
好的 CLAUDE.md 和 差的 CLAUDE.md 的区别，就像是用清晰的简介来入职一名高级工程师，和把新员工扔进一个没有文档的代码库的区别。
以下是如何编写一个真正有效的 CLAUDE.md 👇
在我们深入之前，我会在我的 Telegram 频道分享关于 AI 和氛围编码的每日笔记：https://t.me/zodchixquant🧠
为什么大多数 CLAUDE.md 文件不起作用
三个原因：
太长。模型通常可以可靠地遵循大约 150-200 条指令。Claude Code 的系统提示已经包含大约 50 条。这意味着你的 CLAUDE.md 可能在 Claude 开始遗漏内容之前只能提供大约 100-150 条指令。如果你的文件有 200 行以上，Claude 并不是故意忽略你的规则。
内容错误。大多数人会在 CLAUDE.md 中填写 Claude 自己就能解决的内容。像“成为高级工程师”或“逐步思考”这样的个性化指令。一般性的建议不会改变 Claude 的行为。每一行不能防止特定错误的指令都是浪费。
没有层级。CLAUDE.md 并不是放置指令的唯一地方。有三个层级，大多数人把所有内容都丢到一个层级里：
全局用于你会在每个项目中重复的规则。项目用于你的团队所需的特定技术栈上下文。局部用于你的个人习惯。
使用这三个层级可以让每个文件保持简短和集中。
真正重要的5个部分
在浏览了来自开源项目的数十个生产级CLAUDE.md文件、Anthropic自家的文档以及社区最佳实践仓库之后，每个有效的文件都会涵盖以下5件事：
1. 关键命令
Claude不知道如何构建、测试或lint你的项目 = 告诉它。
简短且具体。Claude 执行这些操作而不是猜测。如果没有这一部分，当你的项目使用 pnpm vitest 时，Claude 会尝试运行 npm test，并浪费三次机会调试一个从未能工作的命令。
2. 架构图
Claude 每次会话开始时对你的代码库一无所知。给它一张地图。
不是完整的目录清单。只需足够让 Claude 知道各个文件的位置以及各自的用途。
3. 硬性规则（Claude 在没有你时会犯的错误）
这是最重要的部分。这里的每条规则都应回答："删除这条规则会导致 Claude 犯错吗？"
需要注意的两点：
1. 否定规则和正面规则一样重要（例如："绝不提交 .env 文件"）
- 强调标记如 重要 实际有效。
Anthropic 自己的文档确认，添加 "重要" 或 "你必须" 可以提高遵守程度。
将本节内容保持在 15 条规则以内。
4. 工作流程偏好
你希望 Claude 如何工作？这可以防止“当你只要求修复一行时，Claude 却重写了整个文件”的问题。
5. 不要包含的内容
同样重要的是你省略的内容：
这里自动记忆被低估了。Claude 会在 ~/.claude/projects/<project>/memory/ 保持自己的笔记。运行 /memory 可以查看 Claude 已经了解了你项目的哪些信息。
不要在 CLAUDE.md 上浪费行数去写 Claude 在一次会话后就已经弄明白的事情。
完整模板（复制此内容）
这是一个可直接投入生产的 CLAUDE.md，你可以复制并调整。少于 60 行。涵盖 Claude 所需的一切，不多也不少。
删除不适用的部分。
改变一切的规则
在测试了数十种 CLAUDE.md 配置后，这些是对输出质量影响最大的几行：
每一行都可以防止一个特定的、常见的错误。
这是对你 CLAUDE.md 中每一行的测试：删除它是否会导致 Claude 做错事？
每个人都会犯的错误
人们把 CLAUDE.md 当作愿望清单来看待。
你的 CLAUDE.md 应该是技术简报，而不是激励演讲。堆栈、命令、架构、规则、工作流程。其他一切都是噪音，与真正重要的指令争夺注意力。
保持在 80 行以内。当 Claude 出错时进行复查。
文件会随着时间累积。一个在第一个月就写好的 CLAUDE.md 可以让你避免重复自己。
到第六个月，它已经捕捉到克劳德在你的项目中所犯的每一个错误，并自动阻止所有这些错误。
我在我的 Telegram 频道每天分享关于人工智能、金融和氛围编码的笔记：https://t.me/zodchixquant
显示英文原文 / Show English Original
Every Claude Code session starts by reading one file: CLAUDE.md. Before your first prompt, before any code, before anything happens, Claude reads this file and treats it as ground truth for the entire session. Most people either don't have one, or theirs is 300 lines of personality instructions. The difference between a good CLAUDE.md and a bad one is the difference between onboarding a senior engineer with a clear brief and throwing a new hire into a codebase with no documentation. Here's how to write one that actually works👇 Before we dive in, I share daily notes on AI & vibe coding in my Telegram channel: https://t.me/zodchixquant🧠 Why most CLAUDE.md files don't work Three reasons: Too long. Models can reliably follow about 150-200 instructions. Claude Code's system prompt already contains roughly 50. That means your CLAUDE.md gets maybe 100-150 instructions before Claude starts dropping things. If your file is 200+ lines, Claude isn't ignoring your rules on purpose.
Wrong content. Most people fill CLAUDE.md with things Claude can figure out on its own. Personality instructions like "be a senior engineer" or "think step by step." General advice that doesn't change Claude's behavior. Every line that doesn't prevent a specific mistake is a wasted instruction. No hierarchy. CLAUDE.md isn't the only place to put instructions. There are three levels and most people dump everything into one: Global is for rules you'd repeat in every project. Project is for stack-specific context your team needs. Local is for your personal quirks. Using all three keeps each file short and focused. The 5 sections that actually matter After going through dozens of production CLAUDE.md files from open-source projects, Anthropic's own docs, and community best practices repos, every effective file covers these 5 things: 1. Critical commands Claude doesn't know how to build, test, or lint your project = tell it.
Short and specific. Claude runs these instead of guessing. Without this section, Claude will try npm test when your project uses pnpm vitest and waste 3 turns debugging a command that was never going to work. 2. Architecture map Claude starts every session with zero knowledge of your codebase. Give it a map. Not a full directory listing. Just enough so Claude knows where things live and what goes where. 3. Hard rules (the things Claude gets wrong without you) This is the most important section. Every rule here should answer: "Would removing this line cause Claude to make a mistake?" Two things to notice: 1. negative rules are as important as positive ones ("never commit .env")
2. emphasis markers like IMPORTANT actually work. Anthropic's own docs confirm that adding "IMPORTANT" or "YOU MUST" improves adherence. Keep this section under 15 rules. 4. Workflow preferences How do you want Claude to work? This prevents the "Claude rewrites your entire file when you asked for a one-line fix" problem. 5. What NOT to include Equally important is what you leave out: Auto memory is underrated here. Claude maintains its own notes at ~/.claude/projects/<project>/memory/. Run /memory to see what Claude has already learned about your project.
Don't waste CLAUDE.md lines on things Claude figured out after one session. The full template (copy this) Here's a production-ready CLAUDE.md you can copy and adapt. Under 60 lines. Covers everything Claude needs, nothing it doesn't. Delete sections that don't apply. The rules that change everything After testing dozens of CLAUDE.md configurations, these are the lines that made the biggest difference in output quality: Each of these prevents a specific, common mistake. That's the test for every line in your CLAUDE.md: does removing it cause Claude to do the wrong thing?
The mistake everyone makes People treat CLAUDE.md like a wish list. Your CLAUDE.md should be a technical brief, not a motivational speech. Stack, commands, architecture, rules, workflow. Everything else is noise competing for attention with the instructions that actually matter. Keep it under 80 lines. Review it when Claude gets something wrong. The file compounds over time. A good CLAUDE.md in month one saves you from repeating yourself. By month six it's captured every mistake Claude has ever made in your project and prevents all of them automatically. I share daily notes on AI, finance, and vibe coding in my Telegram channel: https://t.me/zodchixquant
Grande AI Hub 主站
