# The CLAUDE.md File That 10x'd My Output (Full File Included)
**作者**: darkzodchi
**日期**: 2026-04-27T08:38:50.000Z
**来源**: [https://x.com/zodchiii/status/2048683276194185640](https://x.com/zodchiii/status/2048683276194185640)
---
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:
```
~/.claude/CLAUDE.md → Global (every project)
.claude/CLAUDE.md → Project (shared with team, in git)
./CLAUDE.local.md → Local (personal overrides, gitignored)
```
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.
```
## Commands
- Build: `npm run build`
- Dev: `npm run dev`
- Test single file: `npm test -- path/to/file`
- Lint + fix: `npm run lint:fix`
- Type check: `npx tsc --noEmit`
```
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.
```
## Architecture
- src/lib/services/ → all business logic
- src/components/ → stateless UI components only
- src/lib/store/ → global state (Zustand)
- src/app/api/ → API routes, no business logic here
- Database access only through Server Actions or API routes
```
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?"
```
## Rules
- NEVER commit .env files or secrets
- All async calls must use try/catch
- Use functional components only, no class components
- Prefix commits: feat:, fix:, docs:, refactor:
- All PRs must pass `npm run verify` before merge
- Static export only, no SSR (deployed to S3)
- IMPORTANT: run type check after every code change
```
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.
```
## Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, don't refactor unrelated code
- Run tests after every change, fix failures before moving on
- Create separate commits per logical change, not one giant commit
- When unsure between two approaches, explain both and let me choose
```
## 5. What NOT to include
Equally important is what you leave out:
```
## Don't include:
- Personality instructions ("be a senior engineer")
- Code formatting rules your linter already handles
- @-imports that embed entire docs into every session
- Duplicate rules (if global says "run tests," project doesn't repeat it)
- Anything Claude will learn on its own via auto memory
```
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.
```
# CLAUDE.md
## Project
[One line: what this project does and who uses it]
## Stack
[Framework, language, database, deployment target]
## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command] -- [path]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`
## Architecture
- [folder] → [what lives here]
- [folder] → [what lives here]
- [folder] → [what lives here]
- [file] → [what this file does]
## Rules
- [Rule that prevents a specific mistake]
- [Rule that prevents a specific mistake]
- [Rule that prevents a specific mistake]
- IMPORTANT: [The one rule Claude keeps breaking]
## Workflow
- [How you want Claude to approach tasks]
- [Commit conventions]
- [Testing expectations]
- [When to ask vs when to act]
## Out of scope
- [Things Claude should not touch]
- [Files that are manually maintained]
- [Integrations Claude shouldn't modify]
```
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:
```
# The lines with highest impact:
- IMPORTANT: run type check after every code change
(prevents Claude from shipping broken types)
- Make minimal changes, don't refactor unrelated code
(prevents Claude from rewriting your entire file)
- Create separate commits per logical change
(prevents the 47-file monster commit)
- When unsure, explain both approaches and let me choose
(prevents Claude from making architectural decisions for you)
- Static export only, no SSR
(prevents Claude from adding server-side code to a static site)
```
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
## 相关链接
- [darkzodchi](https://x.com/zodchiii)
- [@zodchiii](https://x.com/zodchiii)
- [55K](https://x.com/zodchiii/status/2048683276194185640/analytics)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [4:38 PM · Apr 27, 2026](https://x.com/zodchiii/status/2048683276194185640)
- [55.1K Views](https://x.com/zodchiii/status/2048683276194185640/analytics)
- [View quotes](https://x.com/zodchiii/status/2048683276194185640/quotes)
---
*导出时间: 2026/4/27 21:49:41*
---
## 中文翻译
# 让我的产出提升 10 倍的 CLAUDE.md 文件（附完整文件）
**作者**: darkzodchi
**日期**: 2026-04-27T08:38:50.000Z
**来源**: [https://x.com/zodchiii/status/2048683276194185640](https://x.com/zodchiii/status/2048683276194185640)
---
每次 Claude Code 会话都是从读取一个文件开始的：CLAUDE.md。在你发出第一个提示之前、在任何代码之前、在一切发生之前，Claude 会读取这个文件，并将其视为整个会话的基本准则。
大多数人要么没有这个文件，要么他们的文件是 300 行的个性指令。
好的 CLAUDE.md 和差的 CLAUDE.md 之间的区别，就像给一位资深工程师提供清晰的任务简报，与把一个新员工扔进一个没有任何文档的代码库之间的区别。
下面教你如何写一个真正有效的 CLAUDE.md👇
在深入之前，我在我的 Telegram 频道分享关于 AI 和氛围编程（vibe coding）的每日笔记：https://t.me/zodchixquant🧠
## 为什么大多数 CLAUDE.md 文件不起作用
三个原因：
太长。模型能够可靠遵循的指令大约只有 150-200 条。Claude Code 的系统提示词本身已经包含约 50 条。这意味着你的 CLAUDE.md 大概只能容纳 100-150 条指令，超过之后 Claude 就会开始遗漏。如果你的文件超过 200 行，Claude 并不是故意无视你的规则。
内容错误。大多数人把 Claude 自己能搞明白的东西填进 CLAUDE.md。比如“做一名资深工程师”或“一步步思考”这样的个性指令。这些泛泛而谈的建议并不会改变 Claude 的行为。每一行不能防止某个具体错误的指令都是浪费。
没有层级。CLAUDE.md 并不是存放指令的唯一地方。共有三个层级，而大多数人把所有东西都塞进一个文件里：
```
~/.claude/CLAUDE.md → 全局（所有项目）
.claude/CLAUDE.md → 项目（与团队共享，纳入 git）
./CLAUDE.local.md → 本地（个人覆盖配置，被 gitignore 忽略）
```
全局用于你会在每个项目中重复的规则。项目用于团队需要的、与技术栈相关的上下文。本地用于你个人的习惯偏好。
三个都用上，能让每个文件保持简短和聚焦。
## 真正重要的 5 个部分
在翻阅了数十个来自开源项目、Anthropic 官方文档和社区最佳实践仓库的生产级 CLAUDE.md 文件之后，我发现每一个有效的文件都涵盖这 5 项内容：
## 1. 关键命令
Claude 不知道如何构建、测试或对你的项目进行 lint = 告诉它。
```
## Commands
- Build: `npm run build`
- Dev: `npm run dev`
- Test single file: `npm test -- path/to/file`
- Lint + fix: `npm run lint:fix`
- Type check: `npx tsc --noEmit`
```
简短且具体。Claude 会运行这些命令而不是靠猜测。如果没有这个部分，当你的项目使用 pnpm vitest 时，Claude 会尝试运行 npm test，然后浪费 3 轮对话去调试一个根本行不通的命令。
## 2. 架构地图
Claude 每次会话开始时对你的代码库一无所知。给它一张地图。
```
## Architecture
- src/lib/services/ → all business logic
- src/components/ → stateless UI components only
- src/lib/store/ → global state (Zustand)
- src/app/api/ → API routes, no business logic here
- Database access only through Server Actions or API routes
```
不需要完整的目录列表。只需足够让 Claude 知道东西在哪里、什么放在哪里。
## 3. 硬性规则（没有你 Claude 就会做错的事）
这是最重要的部分。这里的每条规则都应该能回答：“删掉这一行会导致 Claude 犯错吗？”
```
## Rules
- NEVER commit .env files or secrets
- All async calls must use try/catch
- Use functional components only, no class components
- Prefix commits: feat:, fix:, docs:, refactor:
- All PRs must pass `npm run verify` before merge
- Static export only, no SSR (deployed to S3)
- IMPORTANT: run type check after every code change
```
需要注意两点：
1. 否定规则与肯定规则同样重要（“绝不提交 .env”）
2. 像 IMPORTANT 这样的强调标记确实有效。
Anthropic 官方文档证实，添加"IMPORTANT"或"YOU MUST"能提高规则的遵循度。
这个部分保持在 15 条规则以内。
## 4. 工作流偏好
你希望 Claude 如何工作？这可以避免“你只要求改一行代码，Claude 却重写了整个文件”的问题。
```
## Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, don't refactor unrelated code
- Run tests after every change, fix failures before moving on
- Create separate commits per logical change, not one giant commit
- When unsure between two approaches, explain both and let me choose
```
## 5. 不要包含什么
同样重要的是你应该排除的内容：
```
## Don't include:
- Personality instructions ("be a senior engineer")
- Code formatting rules your linter already handles
- @-imports that embed entire docs into every session
- Duplicate rules (if global says "run tests," project doesn't repeat it)
- Anything Claude will learn on its own via auto memory
```
自动记忆（auto memory）在这里被低估了。Claude 会在 ~/.claude/projects/<project>/memory/ 维护自己的笔记。运行 /memory 可以查看 Claude 已经对你的项目学到了什么。
不要把 CLAUDE.md 的行数浪费在 Claude 一个会话后就能自己搞明白的事情上。
## 完整模板（直接复制）
这是一个可以直接复制和改编的生产级 CLAUDE.md。不到 60 行。涵盖 Claude 所需的一切，没有多余的东西。
```
# CLAUDE.md
## Project
[One line: what this project does and who uses it]
## Stack
[Framework, language, database, deployment target]
## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command] -- [path]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`
## Architecture
- [folder] → [what lives here]
- [folder] → [what lives here]
- [folder] → [what lives here]
- [file] → [what this file does]
```
## 规则
- [防止某种特定错误的规则]
- [防止某种特定错误的规则]
- [防止某种特定错误的规则]
- 重要：[Claude 反复违反的那条规则]
## 工作流程
- [你希望 Claude 如何处理任务]
- [提交（commit）规范]
- [测试要求]
- [何时提问 vs 何时直接行动]
## 超出范围
- [Claude 不应触碰的内容]
- [手动维护的文件]
- [Claude 不应修改的集成]
```
删除不适用的部分。
## 那些改变一切的规则
在测试了数十种 CLAUDE.md 配置之后，以下这些条目对输出质量的提升最为显著：
```
# 影响最大的条目：
- 重要：每次代码修改后运行类型检查
（防止 Claude 提交类型损坏的代码）
- 做最小化修改，不要重构无关代码
（防止 Claude 重写你的整个文件）
- 每个逻辑更改单独创建一次提交
（防止出现 47 个文件的巨型提交）
- 不确定时，解释两种方案并让我选择
（防止 Claude 替你做架构决策）
- 仅限静态导出，不用 SSR
（防止 Claude 在静态站点中添加服务端代码）
```
其中每一条都是为了防止一种常见的特定错误。
这就是检验 CLAUDE.md 中每一条内容的标准：删掉它之后，Claude 会不会做错事？
## 大家都会犯的错误
人们把 CLAUDE.md 当成了愿望清单。
你的 CLAUDE.md 应该是一份技术简报，而不是励志演讲。技术栈、命令、架构、规则、工作流程。其余的一切都是噪音，会与真正重要的指令争夺注意力。
保持在 80 行以内。当 Claude 出错时回顾并更新它。
这个文件会随着时间不断积累。第一个月一份好的 CLAUDE.md，能让你免于反复交代同样的事情。
到第六个月，它已经记录了 Claude 在你的项目中犯过的所有错误，并自动防止所有这些错误再次发生。
我在 Telegram 频道分享关于 AI、金融和氛围编程的每日笔记：https://t.me/zodchixquant
## 相关链接
- [darkzodchi](https://x.com/zodchiii)
- [@zodchiii](https://x.com/zodchiii)
- [55K](https://x.com/zodchiii/status/2048683276194185640/analytics)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [升级到 Premium](https://x.com/i/premium_sign_up)
- [2026年4月27日 下午4:38](https://x.com/zodchiii/status/2048683276194185640)
- [55.1K 次浏览](https://x.com/zodchiii/status/2048683276194185640/analytics)
- [查看引用](https://x.com/zodchiii/status/2048683276194185640/quotes)
---
*导出时间: 2026/4/27 21:49:41*
