# The One File That Turns Claude Code Into a Senior Developer on Your Team - FULL GUIDE
**作者**: NeilXbt
**日期**: 2026-04-26T13:03:45.000Z
**来源**: [https://x.com/neil_xbt/status/2048387556555792544](https://x.com/neil_xbt/status/2048387556555792544)
---
Every developer using Claude Code is losing time. Most of them do not know it.
Not to bad outputs. Not to hallucinations or wrong syntax or misunderstood requirements. To something far more avoidable than any of those.
They are losing time to repetition.
Every new session starts the same way. Re-explaining the stack. Re-establishing the conventions. Correcting the framework assumption Claude made because nobody told it which one to use.
Undoing the refactor it helpfully applied to a file you did not ask it to touch. Reminding it, again, that you use pnpm and not npm, named exports and not default, kebab-case and not camelCase for file names.
The AI is not the problem. The absence of a single file is.
That file is called CLAUDE.md and it is the most underrated feature in Claude Code by a significant margin.
## What CLAUDE.md Actually Is
When you run Claude Code inside a project folder, it automatically looks for a file called CLAUDE.md in the root of that directory before doing anything else. If it finds one, it reads the entire file first.
Every instruction, convention, constraint, and piece of context in that file becomes the foundation every session is built on. Not just the current session. Every session. Permanently. For as long as the project exists.
Think of it as a persistent system prompt that travels with your project. The difference between a contractor who needs the briefing repeated every morning and a team member who has been working alongside you for months and already knows how you think, what you care about, and what you will never tolerate in the codebase.
One file. Permanent context. Zero repeated instructions.
The time investment to write a thorough CLAUDE.md is 20 to 30 minutes. The time you recover is every session that follows it.
## What Happens Without It
Here is the real cost of not having one, described honestly.
Claude writes code using the wrong framework because it made a reasonable assumption based on the limited context you gave it. You correct it. It uses the right framework for the next response. You close the session. Next time you open the project, the assumption is back.
Claude installs a package you ruled out three weeks ago after a painful debugging session revealed it caused memory leaks in your deployment environment. You never told Claude about that decision. How would it know?
Claude rewrites a component you did not ask it to touch because it noticed an opportunity to improve it while completing the task you actually requested. The rewrite breaks something. You spend 40 minutes tracking down why.
None of these failures are the model's fault. They are information failures. Claude is working with incomplete context and doing its best with what it has. The CLAUDE.md file is how you fix that.
## The Structure That Works
A high-performance CLAUDE.md has seven sections. Each one fills a specific gap that produces specific failures when it is missing. Here is what each section does and why it matters.
Project Overview
Start with a plain-English description of what the project is, who it is for, and what the two or three non-negotiable priorities are. Two paragraphs maximum.
This shapes every decision Claude makes before writing a single line of code. A project described as "a crypto signal dashboard where speed and clarity are non-negotiable" produces different code than an undescribed project where Claude fills the gap with its own assumptions about what matters.
Tech Stack
List everything explicitly. Framework, styling, language, database, authentication, deployment, package manager, state management, charting libraries, testing tools. If you use it in the project, it goes here.
If you leave this out, Claude makes assumptions. Sometimes they are right. Frequently they are wrong in ways that take time to catch and correct.
Coding Conventions
This is the section most CLAUDE.md files handle poorly, and it is the one that produces the most day-to-day friction when it is vague.
Do not write "write clean code." That means nothing specific enough to act on. Write the actual rules. Named exports only, no default exports. Kebab-case for file names. Arrow function syntax throughout. No var. Early returns over nested conditionals. Components under 150 lines before extracting. Types co-located with the file that uses them unless shared across three or more files.
These are the rules you silently apply every time you review a pull request. Write them down once and never enforce them manually again.
What Claude Should Never Do
This section is the most underused and arguably the most valuable, especially for experienced developers who already know exactly what they cannot stand in a codebase.
Write it as a list of hard stops. Never install a new package without asking first. Never rewrite a component that was not part of the task. Never use useEffect for data fetching. Never add console.log statements. Never suggest switching the database or framework. Never add placeholder comments that say "implement this later."
Claude is helpful by nature. Sometimes it is helpful in directions you did not ask it to go. The NEVER section is what gives you control over that helpfulness and points it only where you want it.
File Structure
Paste your directory tree and annotate each folder with what belongs there and what does not. Tell Claude explicitly what should never be created without asking. Clarify where components go versus pages versus utilities versus shared types.
Without this, Claude creates new folders based on its best guess about your organizational preferences. Sometimes those guesses are fine. Sometimes they introduce structural decisions you will be living with for months.
Current Sprint Goals
Tell Claude what you are actively building right now and, just as importantly, what is explicitly out of scope this sprint. Not working on authentication yet. Not touching the payment integration until next week. Not optimizing for mobile until the desktop version is stable.
Without this section, Claude will helpfully solve problems you are not trying to solve yet, which adds noise to your work and can introduce changes that conflict with planned future work.
Important Context
This is where you capture the decisions that already got made the hard way. You tried Socket.io and it caused memory leaks. You evaluated three charting libraries and chose the one you chose for specific reasons. The API you are using has rate limits that must be respected in every fetch call. The project started as a personal tool and is now a paid product, which means code quality has different stakes than it did in month one.
Every piece of context in this section is a repetition you never have to make and a mistake Claude cannot make because it does not know the history.
## The Full Template
Here is a complete CLAUDE.md template ready to copy and customize.
```
# CLAUDE.md
## Project Overview
[What does the project do? Who is it for? What are the 2-3 non-negotiable priorities?]
## Tech Stack
- Framework: [e.g. Next.js 14 App Router]
- Styling: [e.g. Tailwind CSS only]
- Language: [e.g. TypeScript strict mode]
- Database: [e.g. Supabase]
- Auth: [e.g. Supabase Auth]
- Deployment: [e.g. Vercel]
- Package manager: [e.g. pnpm]
- State management: [e.g. Zustand]
## Coding Conventions
- [Naming conventions for files, functions, components]
- [Syntax preferences and patterns]
- [Component structure rules]
- [Commenting rules]
- [Typing rules and preferences]
## Never Do This
- Never install packages without asking first
- Never rewrite files I did not ask you to touch
- [Your specific hard stops]
## File Structure
[Paste your directory tree and annotate each folder]
[Add explicit rules about what should never be created without asking]
## Current Sprint Goals
[What are you actively building this week?]
[What is explicitly out of scope right now?]
## Important Context
[Past decisions and why they were made]
[Constraints and limitations to always account for]
[Anything that would help avoid repeating a hard lesson]
## Communication Style
- Be direct. Skip preamble.
- If unsure, ask before writing code.
- When you make a change, tell me what and why in one sentence.
- Flag potential bugs or architectural issues even when not asked.
```
## The Global CLAUDE.md
Once you have used project-level files for a few weeks, you will notice that certain preferences appear in every project. How you like to communicate. The syntax choices you make regardless of the stack. The things you will not tolerate in any codebase.
Those belong in a global CLAUDE.md that runs in the background across every project automatically.
Create it with two commands in your terminal:
mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md
Then fill it with the preferences that never change. Your package manager of choice. Your position on default exports. How you want Claude to communicate, no filler openers, no "Great question", code first then explanation. The things you never want to see in any project regardless of context.
This file and your project-level file stack. When both exist, Claude operates with two layers of context simultaneously. The global file sets your universal standards. The project file adds what is specific to the current work. The combination produces a working environment that feels genuinely personalized because it is.
## CLAUDE.md Beyond Code
The file is not limited to development projects.
If you use Claude Code for writing, research, content operations, or any other workflow, CLAUDE.md works exactly the same way. You define the context, the conventions, and the hard stops for whatever work you are doing in that folder.
A content operations CLAUDE.md might define your writing voice in specific terms. Short punchy sentences. First person throughout. No em dashes. No passive voice where active works. No intros that take more than two sentences to reach the point. No conclusions that summarize what was already said. Conversational but never sloppy. Opinionated and specific rather than hedged and general.
Write that once and every article Claude helps you with starts from your voice rather than its default. The editing work that remains is refinement, not reconstruction.
## The Mistakes That Kill the File's Value
A few common patterns reduce CLAUDE.md from a force multiplier to a mildly helpful document.
Being too vague is the most frequent. "Write good code" and "keep things organized" give Claude nothing specific to act on. The file earns its value through specificity. Every rule should be precise enough that you could judge whether a given piece of code follows it without ambiguity.
Writing it once and never updating it is the second. Your project evolves. Major architectural decisions get made. New constraints emerge. The CLAUDE.md should be updated at the end of every sprint to reflect the current reality of the project, not the reality from six weeks ago.
Skipping the NEVER section is the third. This section is where experienced developers, people who have been burned by specific patterns enough times to have real opinions about them, get the most value. If you have strong opinions about what you do not want, write them down. That is precisely what the section is for.
Maintaining only a project-level file and never building the global one is the fourth. Every time you start a new project and spend 20 minutes writing the same universal preferences, you are doing work the global file would have done for you.
## The Combination That Changes Everything
A solid CLAUDE.md handles project-wide context. The next level is combining it with custom commands stored in .claude/commands/ as Markdown files.
Each file becomes a reusable slash command.
A /new-component command that already knows your component spec.
A /code-review command that applies your exact standards.
A /add-feature command that asks the right questions before writing a line of code.
Your CLAUDE.md handles the permanent context. Your slash commands handle the repeatable workflows.
Together, they produce a working environment where the tool already knows what you need before you start typing, which is what a genuinely useful collaborator feels like rather than a very fast typist who needs constant supervision.
## The 30-Minute Investment
The developers getting the most out of Claude Code are not the ones writing the most sophisticated prompts. They are the ones who spent 30 minutes at the start of a project writing a file that does the prompting for them.
Every session after that runs on a foundation of context that took 30 minutes to build and returns compounding value indefinitely.
Stop explaining yourself at the start of every session. Stop correcting the same assumptions every week. Stop undoing the helpfulness that went in the wrong direction because nobody defined which direction was right.
Write the file. Lock in the context.
Then open a new session and notice what is different.
## 相关链接
- [NeilXbt](https://x.com/neil_xbt)
- [@neil_xbt](https://x.com/neil_xbt)
- [8.3K](https://x.com/neil_xbt/status/2048387556555792544/analytics)
- [Socket.io](https://socket.io/)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [9:03 PM · Apr 26, 2026](https://x.com/neil_xbt/status/2048387556555792544)
- [8,306 Views](https://x.com/neil_xbt/status/2048387556555792544/analytics)
- [View quotes](https://x.com/neil_xbt/status/2048387556555792544/quotes)
---
*导出时间: 2026/4/27 09:33:15*