我花了半年踩的坑：不给Claude写员工手册，它就是个废物 (English)

Generated: 2026-06-24 00:51:45

---

Oh no, another Claude Code tutorial? Are you sure you want to read this?

Wait. Don’t scroll away.

I know what you’re thinking — nine out of ten tutorials out there are just someone installing the thing, running a demo, taking a screenshot for their feed, and then it disappears into a bookmarked folder you never open again. You and I have both done it. The whole “get started, then give up” routine in one smooth motion. But this one’s different.

Let me tell you a real story. Last month, a new developer joined my team. Graduated from a top university, IQ so high it made me look like a beginner. And the first two weeks? He was a wreck. Why? Because he had no idea about all the little conventions we have in our project: indentation is four spaces, API keys go in environment variables, even commit messages have a strict format. No matter how brilliant, without context you're just stumbling around in the dark.

Then I gave him a one-page employee handbook. Ten minutes later, he went from “uh-huh, sure” to “got it, I’ll follow the rules.”

Claude Code is that new developer. Super capable, but knows nothing about your project.

A lot of people install it, type “write me a web scraper” as their first command, and then complain it writes code that looks like trash. And I’ll be blunt — if you don’t tell it what framework you’re using, where the database is, whether you prefer camelCase or snake_case, of course it’s going to mess up. That would be a miracle.

So today I’m not going to walk you through some flashy twenty-minute tutorial. I’ve been using Claude Code for the better part of a year, made plenty of mistakes, and only now feel like I really understand its temperament. Every single word in this article comes from hands-on testing. The stuff that other people keep to themselves? I’m laying it all out here.

Follow this guide. If it doesn’t work, come back and yell at me. I’ll take it.

---

1. First things first: What the heck is Claude Code anyway?

Everyone says it’s powerful, but nobody explains why.

It’s not the web version of Claude. It’s not a little plugin inside your IDE. It’s a standalone agent running in your terminal, like a beast.

Think of it as a brand new full-stack engineer you just hired. On day one, you hand them three things: an access card (API Key), a workstation (your project folder), and their first task (the prompt you type). Give them those three, and the work they’ll do will make your jaw drop.

To save time, I usually just run:

claude --dangerously-skip-permissions

Brutal? Yeah. Fast? Absolutely. If you’re not comfortable with that, leave the flag out — it will ask you “can I execute this?” before every command. I’ve been using it for months, never had an issue. But you decide for yourself.

---

2. Installation? One line.

macOS / Linux:

npm install -g @anthropic-ai/claude-code

Windows: Open PowerShell as administrator and run the same command.

That’s it. Run claude --version to check. If you see a version number, you’re good.

Don’t waste time searching for some IDE integration guide — it has nothing to do with your IDE. One command and you’re done. Honestly, I have to give Anthropic credit for that.

---

3. Don’t rush into work — write an employee handbook first.

It’s installed. Most people immediately type something like “refactor my entire project!” Then three exchanges in, they realize the code it’s writing doesn’t match the project style at all.

The problem is you didn’t give it context.

Every new conversation, Claude Code is like a programmer who just walked in the door — smart as hell, but knows nothing about your project. If you don’t tell it whether you’re using Python or Go, Flask or FastAPI, what test coverage you expect, it can only guess. And the odds of guessing right are about as good as throwing darts with your eyes closed.

The fix?

Create a file in your project root called CLAUDE.md. This is its employee handbook.

Here’s a typical example from my projects:

# Project Overview
This is a quantitative trading system. Python backend + Vue frontend.
Backend uses FastAPI, database is PostgreSQL, message queue is Redis.
All APIs must have type annotations. Test coverage should be at least 80%.

# Important Conventions
- Never hardcode API keys in code. Always use environment variables.
- Function names in snake_case, class names in PascalCase.
- All async operations must use asyncio. No threading.
- Git commit format: <type>(<scope>): <description>

# Personal Preferences
- Comments in Chinese, code in English.
- Prefer pandas 2.0+. Don't use the old append method.
- Use loguru for logging. No print statements.

Once you create this file, every time you open Claude Code in that project, it will automatically read it. Give the new hire their handbook, and you won’t have to worry about the work going off the rails.

Some people use Claude Code for three months and get less out of it than someone who uses it for three days with a CLAUDE.md. That’s the difference.

---

4. Basic commands: treat AI like a tool, not a deity.

Once you’re inside Claude Code, you can do more than you think.

Get these common ones down first:

• /help — Check the help (useful if you’re new)
• /clear — Clear the current conversation without losing the context from CLAUDE.md (this command is a lifesaver)
• /status — Check how many tokens you’ve used so far
• /compact — Compress the context to save some token costs
• /cost — See how much you’ve spent? I check this every night before bed.

Permission modes:

• claude — Default mode. Asks for your permission before every command.
• claude -p — Plan mode. It outlines a plan before executing. Great for large tasks.
• claude --dangerously-skip-permissions — My go-to. No questions, just do it.
• claude --resume — Resume your last session.

More than you expected, right?

---

5. Skills / Hooks / MCP: the three things that separate the pros from the crowd.

I’m going to be honest