CLAUDE.md: Write Clear Project Instructions for Claude Code

A CLAUDE.md file is a plain-text Markdown file that gives Claude Code persistent instructions about a project or your working preferences. Write the things an assistant needs before it acts: how the project is organized, which commands check a change, and which rules its owner approved.

The file works best as a short starting point. Tools like fenbs can keep the changing task state and decision record outside the repository instructions, so the file stays useful while different assistants continue the same work.

How do you create a useful first file?

1. List the project facts you would explain to a capable new contributor before their first change.
2. Create CLAUDE.md at the project root, or use the project location supported by Claude Code.
3. Write short sections for project layout, working commands, and important rules.
4. Check every command and path against the repository instead of trusting a generated draft.
5. Start a fresh session, confirm the file is loaded, and test a small representative task.

Claude Code’s instruction and memory documentation↗ (opens in a new tab) describes supported file locations, loading behavior, and the /init starting-file command. Treat generated instructions as a draft for review. A guessed test command is worse than a clear statement that the project has no automated check yet.

Suppose a small studio maintains a booking site. Useful instructions would name its app directory, its actual package manager, and the requirement to preserve keyboard access on forms. “Build a modern website” would add little: it says nothing about how to make the next change correctly.

What information belongs in CLAUDE.md?

Include stable guidance that changes an assistant’s choices. A reader should be able to connect each line to an action, a location, or a check. Keep broad aspirations in the project overview and specific implementation details near the code they describe.

Explain a surprising rule briefly. If a team keeps dates as calendar dates rather than timestamps, name that choice and its reason. The explanation helps an assistant recognize where the rule applies instead of mechanically replacing every date value it sees.

A rule’s approval history can live in fenbs Decisions and rules. The file can then state the practical instruction without becoming a transcript of every discussion that led to it.

Which scope should hold each instruction?

Claude Code supports user, project, and local project instruction locations. A personal preference belongs at user scope; a team convention belongs with the project. Instructions for a particular area can be kept closer to that area rather than making every session read unrelated detail.

For instance, “explain unfamiliar code before editing it” may be your personal preference. “All public forms require accessible labels” is a project requirement. “Use my temporary test server” is local setup information and should not silently become a requirement for everyone.

Be careful with overlapping files. A root rule that says to use the shared helper and a nested rule that says to build a separate helper create ambiguity. Keep an owner for shared instructions and review the combined guidance when a directory gains its own rules.

For repositories using a different instruction filename, see whether Claude Code reads AGENTS.md. If you manage several repositories, the separate multiple-project guide covers that wider setup.

How short should the instructions be?

Short enough that every line earns its place. Begin with a page you can review comfortably, then remove information Claude can discover directly from obvious project files. Do not add a permanent paragraph every time a single task needs an exception.

# Project
Describe the product and the directory where the app lives.

## Work here
Name the package manager and the commands used for checks.

## Follow these conventions
List the few approved rules that change implementation choices.

## Before finishing
Report what changed, which checks ran, and what remains unverified.

## Ask the owner
Name the actions that require approval.

A checklist can be concise while still being precise. “Preserve keyboard use; check focus and error messages after editing a form” is more useful than a long paragraph about quality. Put a detailed procedure in an appropriate reference rather than pasting every procedure into the starting file.

Anthropic’s Claude Code best practices↗ (opens in a new tab) emphasizes focused instructions and verifiable work. For longer starter patterns, use the separate CLAUDE.md examples rather than expanding this file into a general manual.

How do you verify that a rule is working?

Test an observable result. If the file says to reuse an existing helper, ask Claude to plan a small change that needs it. Check whether the plan identifies the helper and whether the eventual patch uses it. A confident claim that the file was read is weaker evidence than the correct action.

Then test a boundary case. Ask for a change in a different directory and see whether an area-specific rule is applied too broadly. If a requirement is ignored, check the loaded instruction files, the current working directory, and contradictory wording before adding more emphasis.

Instruction text is guidance, not a security barrier. Use Claude Code’s settings and permission configuration↗ (opens in a new tab) for the controls it provides, and restrict sensitive actions in the systems that own them. The file can explain your approval policy, but it cannot make an unrestricted credential safe.

For a file that still appears to be ignored, follow the focused CLAUDE.md troubleshooting guide. The AI prompts collection covers related instruction practices. Keep test observations with the task so the next assistant knows which behavior was actually checked.

How to do this with fenbs

1. Create a free account and add a project for the repository.
2. Record the owner-approved requirements in Decisions and rules, including the reason for any unusual restriction.
3. Keep the concise implementation guidance in CLAUDE.md and put the current task’s plan and checks on its fenbs task.
4. Connect Claude Code and ask it to read the project’s AI context before beginning.
5. Ask it to save progress before stopping so the next session sees completed work and remaining checks.

fenbs does not replace the repository’s file-loading behavior or import your Claude chat history. A single project with a few stable instructions may only need the file. fenbs helps when changing decisions and unfinished work need to remain available to more than one supported assistant.