claude.md怎么写才能让Claude Code更高效? (English)

Generated: 2026-06-24 11:21:18

---

That CLAUDE.md You Wrote for Claude Code? It Might Be Three Months Out of Date

Last month I nearly threw my keyboard across the room because of one project.

Here's what happened: Claude Code jumps in, immediately runs yarn install, and hangs. I stared at the terminal for ten seconds, my brain full of question marks.

Then I opened the project root's CLAUDE.md. Sure enough, the first line read: "This project uses yarn for dependency management."

The problem? That project had migrated from yarn to pnpm three weeks earlier.

No one had updated the file.

And it gets better: I dug through the git log—literally no one had touched that CLAUDE.md in three months.

Think about it: the AI's been following outdated instructions the whole time, while the team wonders, "Why does this thing keep getting dumber?" … Well, no wonder.

That experience made it crystal clear: a well-written CLAUDE.md can make your life amazing; a bad one is just digging a hole for yourself. Today I'm breaking down what I've learned over the past few months into a few key questions, one by one.

---

Question One: Can I Just Toss a CLAUDE.md in the Project Root and Call It Done?

Way too naive.

The easiest thing to mess up isn't the content—it's: did you even put it in the right place?

Claude Code's configuration has four levels, from lowest to highest priority:

1. Global level ~/.claude/CLAUDE.md — shared conventions across all projects
2. Project level CLAUDE.md in the project root — checked into Git, shared by the team
3. Module level CLAUDE.md in subdirectories — a killer feature for monorepos
4. Inline level manual reference via @CLAUDE.md in a conversation

The rule is simple: nearest wins. Module level overrides project level, and project level overrides global level.

Here's a trap I fell into: at first I crammed every rule into a single root-level CLAUDE.md, and then my frontend and backend sub-projects contaminated each other—Claude would ask about backend stuff while in the frontend directory, and use frontend conventions in the backend directory. What a mess.

Later I added a separate CLAUDE.md inside the test/ directory, making it clear: "Test files don't need to follow the main project's architecture conventions. Each test file is independent and self-contained." One line, and peace was restored.

There's an even more flexible approach: the .claude/rules/ directory. Place rule files by path, and Claude automatically loads them when it enters the corresponding directory—no need to pile a bunch of if-else logic into the main file. Now my project root CLAUDE.md is about 80 lines, only covering general rules; the .claude/rules/ directory breaks things down by module, each file 30–50 lines. Clean. Clear. Saves tokens.

One more pitfall: don't expect your first conversation with a new project to be an expert.

Claude Code has an /init command. Run it in the project root, and it automatically scans the code, reads the README, infers the tech stack, and spits out a draft CLAUDE.md. But you need to understand: that's only a starting point. A truly useful CLAUDE.md is fed into existence: every time Claude makes a mistake, you add a rule. Three months later, that file is your most valuable AI asset.

---

Question Two: Can I Just Write It Like a README?

Dead wrong. This is the most common misunderstanding.

I've seen tons of people write stuff like "This project is an e-commerce admin system using a microservices architecture, with three core modules: Products, Orders, Users" directly in their CLAUDE.md.

That line just wastes tokens. Claude can't use it.

Think about it: does the AI need to know what your project is called? That it's e-commerce or a social network? What it needs is—"How do I run you?" "What do you want me to do when I write code?"

The litmus test is dead simple: before you write something, ask yourself—"Is this sentence for a human or for Claude?"

If it's for a human, put it in the README.

If it's for Claude: tech stack, build commands, test commands, code conventions, project-specific agreements. That's it.

For example, my current project's CLAUDE.md starts like this:

# Tech Stack
- Language: TypeScript 5.4
- Package manager: pnpm (don't use npm, don't use yarn)
- Testing: Vitest (don't use Jest; the current project has no Jest config)
- Formatting: Biome (not Prettier)
- CI: GitHub Actions

# Commands
- Build: pnpm build
- Test: pnpm test (runs all)
- Single file test: pnpm test -- <file path>
- Lint: pnpm lint:fix

# Code Conventions
- Components use React functional components + hooks, no class components
- CSS solution is Tailwind, don't write `.css` files
- API requests all use a fetch wrapper with the `/api/` prefix

Every line is useful. Every line tells Claude how to do things, not what the project does.

One guy asked me: "What about project background info?"

Easy. Put it in the README. Claude Code can read the README itself; you don't need to repeat it in CLAUDE.md.

Another little trick: if your team uses both Claude Code and Copilot, you can have CLAUDE.md reference an AGENTS.md. Write the basic content in AGENTS.md, then CLAUDE.md references it via path, and adds Claude Code–specific rules on top. Each tool reads its own file, and you don't maintain two duplicate sets of content.

---

Question Three: Can I Just Copy a Template from the Web and Use It As-Is?

You can copy it, but don't use it directly. Template problems are worse than you think.

I once downloaded a pretty popular CLAUDE.md template, and right there in plain sight it said:

- Follow best practices
- Code should be readable
- Ensure type safety

All fluff. When the AI sees "follow best practices," it's like telling a person "do a good job"—empty platitudes.

But here's the killer: the template had placeholders like , {{ ... }}, and TODO that hadn't been removed. The AI takes those literally! I once saw someone complain on a GitHub issue that Claude kept outputting "TODO: implement this later." After hours of debugging, they found it in their CLAUDE.md. The AI thought it was an instruction.

So what should you do? My recommended approach: start from real project analysis.

First, run /init to have Claude Code scan the project and generate a draft. Then delete and edit based on that draft. Or manually check configuration files like package.json, pyproject.toml, biome.json, and write in the actual tech stack.

As for the content, I stick to three ironclad rules:

1. Specific and verifiable — not "use good testing practices," but "test files use Vitest; mocks go in the `__m