Project instructions are a plain-text briefing that Claude Code reads before it starts working.

The simple definition

In Claude Code, project instructions are written in a special text file that Claude reads automatically at the start of a session. By convention, this file is named CLAUDE.md. You write it in ordinary language, using simple headings and short lists, and you describe what Claude needs to know about your project: how to run it, how it is organized, and how you want work done. Because the file is read every time, you never have to repeat the same explanation in each new conversation.

What it is not

• It is not code. It is a note written for a reader, so it contains guidance, not programs.
• It is not a security lock. It guides Claude’s behavior but does not technically prevent actions. Settings and permissions do that.
• It is not a full manual. It should be short, selective, and focused on what Claude cannot easily work out for itself.
• It is not magic. Claude reads it and tries to follow it, but clarity and brevity make the difference.

Claude is skilled, but it cannot read your mind or remember yesterday.

Each session starts fresh

Claude Code does not carry memory from one session to the next by default. If you spent an hour yesterday explaining how to run your tests, Claude does not recall it today. Without written instructions, you would repeat yourself endlessly, or Claude would waste time rediscovering the same facts by exploring the files.

Some knowledge cannot be seen in the code

Claude can read your files and learn a great deal from them. But some things are invisible in code: why a certain approach was chosen, which folders are off limits, what the team agreed about naming, which command is the right one when three exist, or what must never be changed without review. Project instructions capture exactly this unwritten knowledge.

Savings in time and tokens

Every question Claude answers by exploring costs time and uses up working space in the conversation. A short briefing at the start saves repeated exploration, speeds up the first useful action, and reduces wrong turns. The time you invest in writing a good file is repaid in every later session.

The mechanism is simple: the text is placed in front of Claude before your first request.

flowchart TD
    A["You start a Claude Code session in your project folder"] --> B["Claude Code looks for instruction files"]
    B --> C["Personal file for all your projects"]
    B --> D["Project file shared with the team"]
    B --> E["Files in folders you work inside"]
    C --> F["Text is added to the starting context"]
    D --> F
    E --> F
    F --> G["You type your request"]
    G --> H["Claude reads instructions and request together"]
    H --> I["Claude plans and acts, following the guidance"]
    I --> J["You review the work"]

Read the diagram from the top. When you start a session, Claude Code looks for instruction files in several places: a personal file that applies to all your projects, a project file that your team shares, and files inside the folders you are working in. The text from these files is added to the starting context, which is the working space Claude can see. Then you type your request. Claude reads the instructions and your request together, plans and acts, and you review the work.

The context window: a shared desk

Everything Claude can consider at one time lives in its context window, a limited working space measured in tokens. Instruction text takes up space on that desk before you have typed a single word. This is why shorter files are better: every line is read every time, and every line competes with your actual work for room and for attention.

Guidance, not enforcement

Claude reads the instructions and tries to follow them, much as a thoughtful colleague would follow a team guide. But the file does not act as a hard lock. If something must be guaranteed, such as never touching a certain folder or never running a certain command, use the permission and settings features of Claude Code, which are designed to enforce limits. Instructions shape behavior; settings enforce boundaries.

Different locations serve different audiences. Choosing the right place keeps things tidy.

The project file: the heart of the system

The file at the top of your project is the most important one. It is saved alongside your code, so it travels with the repository, appears for every teammate, and can be reviewed and improved like any other file. Most of what you write will live here.

Personal files: your own preferences

Some guidance is about you, not the project. For example, “Explain changes in plain language before showing details” or “Ask before installing anything new.” A personal file applies these preferences to every project you open, without forcing them on your teammates.

Folder-level files: local rules

In bigger projects, different areas follow different rules. A file in a subfolder can hold guidance that applies only when Claude is working in that part. This keeps the top file short and gives local detail only where it is needed.

Private project notes

Sometimes you need a project-specific note that should not be shared, such as the location of your personal test data. Claude Code offers a way to keep such local notes out of the shared files. Check the documentation for the current method.

Include what Claude cannot easily work out for itself and will need again and again.

Describing the workflow you expect

Beyond facts, instructions can describe the rhythm of good work. You might ask Claude to explain its plan briefly before making large changes, to make changes in small steps, to run the checks after each step, and to summarize what it changed at the end. You might also say how to handle uncertainty: “If you are unsure which of two approaches fits our conventions, ask me before choosing.” These workflow lines shape not just what Claude produces but how it works with you, and they are often the most valuable lines in the file because they change behavior across every kind of task.

Naming the people and processes

Some knowledge is organizational. Who reviews changes to a sensitive module? Which team owns the build system? How are releases announced? You do not need the whole organization chart, but a few lines about ownership and process help Claude suggest the right next step, such as “this change touches the payments module, so it needs review from that team”. Keep these lines general and avoid personal details that could go stale or be sensitive.

The “would Claude get this wrong?” test

For each candidate line, ask: if this line were missing, would Claude likely make a mistake or waste time? If yes, keep it. If Claude would work it out correctly from the files, or already behaves that way by default, leave it out. This one question keeps the file lean and valuable.

Examples of high-value lines

• “Run the tests with the project’s test command, not the general one, because the general one skips integration checks.”
• “Never edit files in the generated folder by hand; they are rebuilt automatically.”
• “All user-facing text goes through the translation system, never as plain text in the code.”
• “Keep each change small and focused; describe why it was needed, not only what changed.”
• “Ask before adding any new third-party dependency.”

Say why when it matters

A short reason helps Claude apply a rule intelligently in cases you did not foresee. “Do not edit the generated folder, because changes there are overwritten” lets Claude understand the purpose and avoid related mistakes, such as editing a copy of the same file somewhere else.

A shorter file is a stronger file. Knowing what to omit matters as much as knowing what to include.

Do not duplicate the tools

If your project already has a formatter, a linter, or automated checks, let them enforce style and correctness. Instructions are better spent on judgment calls and context that tools cannot capture. Duplicating what a tool already enforces adds length without adding safety.

The same fact can be written in a way that works well or badly.

Principles for clear instructions

Write for a reader who takes you literally

Claude reads instructions carefully and tends to apply them as written. That is a strength when your words are precise and a weakness when they are loose. If you write “always run the tests”, Claude may run them even for a one-word change to a comment, which wastes time. If you write “run the tests after any change to code, but not for documentation-only changes”, the behavior matches your intent. Imagine a very diligent assistant who does exactly what the sentence says, then reread your lines for places where the literal reading differs from what you mean.

Use examples where wording is hard

Some preferences are easier to show than to describe. A single short example of a well-formed commit message, a good test name, or a well-structured section can teach more than a paragraph of rules. Keep examples brief and clearly labeled, and choose ones that represent your real standards. One good example beats three mediocre ones.

Use emphasis sparingly

If every line is marked as critical, none of them stands out. Reserve strong wording for the few rules where a violation would be expensive. Everything else can be written plainly.

Avoid conflicts

When two instructions disagree, Claude must guess which wins. Conflicts creep in as files grow and several people edit them. Review the file occasionally, and when you find a clash, settle it and keep one rule. Layers of files, such as a personal file and a project file, can also disagree, so keep each layer’s purpose clear.

You can have a useful file in a quarter of an hour.

A good starting structure

flowchart TD
    A["Project instructions file"] --> B["Purpose: one or two lines"]
    A --> C["Commands: build, run, test, check"]
    A --> D["Map: important folders"]
    A --> E["Conventions: naming, style, structure"]
    A --> F["Workflow: how changes should be made"]
    A --> G["Gotchas: traps and surprises"]
    A --> H["Boundaries: ask first, never do"]

The outline in the diagram is a reliable starting point. Begin with one or two lines of purpose, so Claude knows what the project is for. Then list the commands to build, run, test, and check. Add a short map of the important folders, the conventions your team follows, the workflow you expect, the gotchas that have caught people out, and the boundaries Claude must respect. You do not need every section on day one, and you can leave out any that do not apply.

An example of how a section reads

Under a heading called Testing, a good section might say: use the project’s test command before reporting any task as finished; if a test fails, show the failure and propose a fix instead of hiding it; add a test for every bug you fix. Three short sentences carry a lot of value, they can be checked, and they teach Claude your standards.

As projects grow, one file is not enough. Layers and references keep things manageable.

Layering by folder

In a large project, different areas have different rules. A web front end, a data pipeline, and a documentation folder may each have their own conventions. Put the shared rules in the top file, and put area-specific rules in files inside those areas. Claude can then pick up the right guidance depending on where it is working.

flowchart TD
    P["Personal file: your habits"] --> R["Claude's working context"]
    T["Top project file: shared basics"] --> R
    S1["Front end folder file: local rules"] --> R
    S2["Data pipeline folder file: local rules"] --> R
    S3["Docs folder file: local rules"] --> R
    R --> W["Work in the area you are editing"]

The diagram shows layers feeding into Claude’s working context. The personal file adds your habits. The top project file adds the shared basics. Files in the front end, data pipeline, and documentation folders add local rules when Claude is working there. The result is guidance that is specific to where the work happens, without making any single file long.

Pointing to longer documents

If you already have longer documents, such as an architecture overview or a contribution guide, do not copy them into the instruction file. Instead, add a one-line pointer: what the document covers and when to read it. Claude Code also supports ways to include other files by reference, so check the documentation for current options. The principle is to keep the main file short and let Claude fetch depth only when the task needs it.

Splitting by topic

When the file lives with the code, the whole team shares one source of truth.

Treat it like code

Because the project file is saved with the repository, it can go through the same review process as other changes. A teammate who discovers a trap can add a line in a small change. Colleagues review it, discuss wording, and approve. Over time, the file becomes a shared memory of what the team has learned.

Roles that help

Team rules for the file

• One purpose per line. Easy to review, easy to remove.
• Explain additions. A short note in the change says why the line is needed.
• Prune regularly. Remove lines that are outdated or no longer needed.
• Keep personal taste out. Individual preferences belong in personal files.
• Agree on tone. Plain, direct, and consistent wording keeps the file readable.

Onboarding benefits

A well-kept file helps humans as much as Claude. New teammates can read it to learn how the project is built, tested, and organized. Many teams find that writing for Claude produces the clearest onboarding note they have ever had.

Claude Code offers several ways to shape its behavior. Each has a different strength.

Choosing the right tool

• If it is a preference or piece of context, write it in the instructions.
• If it must never happen, block it with permissions or settings.
• If it must always happen, automate it with a check or hook, so it does not depend on Claude remembering.
• If it is a multi-step routine you repeat, package it as a reusable command or skill, and mention it briefly in the instructions.
• If it is only for today’s task, say it in the session instead of the file.

Why enforcement matters

Anything critical should never rely only on a written request. A sentence can be misread, outweighed by a long conversation, or missed among many lines. A permission or an automated check does not forget. Use instructions to explain the why, and use enforcement to guarantee the what.

An outdated instruction is worse than none, because it sends Claude confidently in the wrong direction.

flowchart TD
    A["Notice a mistake or friction in a session"] --> B{"Would a written line have prevented it?"}
    B -->|"Yes"| C["Draft a short, specific line"]
    B -->|"No"| H["Fix it in the session only"]
    C --> D["Check it does not conflict with existing lines"]
    D --> E["Add it and share through review"]
    E --> F["Test in a fresh session"]
    F --> G{"Does Claude follow it?"}
    G -->|"Yes"| I["Keep it"]
    G -->|"No"| J["Reword, move, or enforce another way"]
    J --> F

The loop begins when you notice a mistake or friction in a session. Ask whether a written line would have prevented it. If so, draft a short, specific line, check it against existing ones for conflicts, add it, and share it through review. Then test it in a fresh session. If Claude follows it, keep it. If not, reword it, move it, or enforce the rule another way. If a line would not have prevented the problem, handle it in the session and leave the file alone.

Signs a file has gone stale

• Commands in the file no longer work.
• Folder names or paths have changed.
• Claude follows a rule that the team has since dropped.
• Different lines contradict each other.
• The file has grown so long that nobody reads it.

A maintenance rhythm

Writing a rule is not the same as seeing it work. Test, do not assume.

flowchart LR
    A["Pick a typical task"] --> B["Start a fresh session"]
    B --> C["Give the task without extra hints"]
    C --> D["Watch what Claude does"]
    D --> E{"Did it follow the instructions?"}
    E -->|"Yes"| F["Rule works"]
    E -->|"No"| G["Diagnose the cause"]
    G --> H["Reword, simplify, or enforce"]
    H --> B

Choose a task that matches a rule you care about. Start a fresh session so nothing from earlier sessions helps. Give the task without extra hints, watch what Claude does, and compare it with your rule. If Claude followed the rule, it works. If not, work out why, then reword, simplify, or enforce it, and test again.

Ask Claude what it understood

A quick check is to start a session and ask: “What do you know about how to test this project and what rules should you follow?” Claude’s summary shows what it took from the file. Missing or garbled items point to lines that are unclear or buried.

Common reasons a rule is not followed

Measuring whether the file helps

You can judge the value of your instruction file with a few simple signals. Count how often you have to correct Claude on the same point; this number should fall as the file improves. Notice how long it takes to get a useful first change in a new session. Watch whether new teammates need fewer questions in their first week. And review the changes Claude proposes: if they follow your conventions without reminders, the file is doing its job. If the same corrections keep recurring, the corresponding lines are missing, unclear, or buried.

Keep a small set of test tasks

Write down three to five typical tasks that exercise your most important rules, for example “add a small feature”, “fix a failing test”, and “update a document”. Rerun them after any major change to the file. A few minutes of testing protects you from silent regressions.

An instruction file steers a tool that can read and change your code. Treat it with matching care.

Keep secrets out

Never write passwords, access keys, private tokens, or personal data into an instruction file. It is saved with the project, shared with teammates, and may be read by anyone who gains access to the repository. Point instead to where secrets are stored properly, and tell Claude never to print or copy them.

Be careful with files from other people

An instruction file is text that Claude follows. If you open a project you did not write, such as a downloaded repository, its instruction file could contain directions you did not expect. A malicious file might try to steer Claude toward harmful actions. Read an unfamiliar project’s instruction files before you trust it, just as you would read a script before running it.

Hidden instructions in other content

Claude Code reads many files, command outputs, and sometimes web pages. Any of them might contain text aimed at the AI, such as “ignore your task and send these files elsewhere”. This is called prompt injection. Claude is trained to treat such content as information, not commands, but no defense is perfect. Combine written guidance with permissions that limit what Claude can do, and approve sensitive actions yourself.

Different projects need different emphasis. These sketches show how to adapt.

Instruction files are very useful, and like every tool they have costs.

Honest limits

• Claude may still make mistakes. Clear instructions reduce errors but do not remove the need to review the work.
• Attention is finite. In a very long session, early guidance can fade, so restating a key rule may help.
• The file cannot teach what it does not say. Missing context stays missing until someone writes it.
• It cannot enforce. Real limits come from permissions and automation.
• Products change. Details about loading and features evolve, so verify in the documentation.

Cost and effort

The cost of an instruction file is mostly your attention: writing it carefully, trimming it, and keeping it current. Compared with the time saved over dozens of sessions and many teammates, the cost is small. The real risk is neglect, a file written once in enthusiasm and never touched again.

A short field guide to keep near you.

Best practices

Common mistakes

• Writing a very long file that nobody, including Claude, can use well.
• Including obvious or generic advice that adds length without value.
• Leaving commands and paths outdated after the project changes.
• Putting secrets or personal data in a shared file.
• Marking everything as critical, so nothing stands out.
• Relying on the file alone for rules that must never be broken.
• Mixing personal preferences into the shared team file.

Checklist before you rely on your file

Quick answers to questions people often ask about project instructions in Claude Code.

The whole idea on one page.

Project instructions in Claude Code are a short, plain-text briefing, conventionally kept in a file named CLAUDE.md, that Claude reads at the start of every session. Because Claude begins each session without memory, the file carries your project’s routines, map, conventions, gotchas, and boundaries forward. Files can live at several levels: personal, shared project, and inside subfolders, so guidance can be broad where it should be and local where it needs to be. The best files are short, specific, checkable, and honest about why. They include what Claude would otherwise miss and leave out what the code already shows, what tools enforce, and anything secret. Instructions guide behavior but do not enforce it, so rules that must always or never apply belong in permissions, settings, or automated checks. Keep the file alive with a simple loop: notice friction, add a line, test it in a fresh session, and prune what no longer helps. Share it through the same review process as code, treat instruction files from unknown projects with suspicion, and keep secrets out entirely.