How CLAUDE.md Works: Instructions, Loading, and Limits

CLAUDE.md works by supplying written project instructions to a Claude Code session, where the model reads them alongside the task and other available context. It guides behavior; it does not execute as a program or enforce permissions. fenbs adds the shared work record a rules file cannot maintain: current tasks, decisions and where the previous session stopped.

Think of the file as a short briefing that accompanies work. It can say which checks matter and explain a surprising project constraint. Whether the resulting change is correct still depends on what the assistant does, what tools it can use and how the result is verified.

What happens between an instruction and an action?

The assistant interprets the instruction while deciding its next step. If the file says to preserve existing response fields, the assistant should account for that when planning a change to an API, meaning the interface another program calls. The sentence does not install a validator that automatically rejects renamed fields.

Anthropic describes Claude Code’s work as a loop of gathering context, taking action and verifying results in its core workflow documentation↗ (opens in a new tab). An instruction can affect each part: what to read, which changes to make and what evidence to produce. Those are separate opportunities to inspect whether the guidance was useful.

Say a project asks for a smaller contact form. A rule may explain that collected customer fields need approval. A good session notices that rule before editing, identifies the affected fields and checks the approved requirement. A poor session may repeat the rule in its final message after already removing a field without asking.

That example is why a correct summary of the file is only a starting check. Review the proposed action and the actual result as well. You want evidence that the rule affected the work at the right moment, not evidence that the assistant can quote the sentence.

What syntax does an instruction need?

Use ordinary Markdown: headings organize subjects, bullet points separate requirements and backticks identify commands or paths. A heading is a label for the reader, not an executable setting. An instruction written under “Critical rules” still needs a clear condition and an observable action.

# Project guide

This repository maintains the public appointment website.

## Changes
- Preserve existing booking fields unless the task includes an approved change.
- Keep form labels visible when a field contains a value.

## Verification
- Identify the relevant repository check before editing.
- Report what ran and what could not be verified.
- Ask a person to review changes to customer information collection.

The example deliberately avoids inventing a test command. A real file should name commands verified in that repository. “Run the relevant check” can be a temporary draft, but the maintained version becomes more useful when it identifies the actual check and the directory where it runs.

Prefer literal guidance to a pile of labels: “Do not change a public field name without an approved contract change” is clearer than “Use best practices.” For other shapes, see the CLAUDE.md examples. Keep specialized syntax tied to a documented mechanism rather than assuming arbitrary keys create new behavior.

How does the text become available to a session?

Claude Code discovers supported instruction files according to their location and scope; nested guidance can be loaded when relevant work is opened. Use /context to inspect loaded files. Anthropic’s instruction loading documentation↗ (opens in a new tab) gives the current details. A file existing on disk is different from a file being included in the session.

This creates two distinct questions. First, did the session receive the instruction? Second, did the instruction help the assistant choose the right action? Check the first before rewriting the second. A beautifully worded rule in an unrelated directory cannot help a session that never receives it.

For the full file setup, use the CLAUDE.md file guide. If you work across repositories, the multiple-project guide covers that separate organization problem. Here the important mechanism is the boundary between available guidance and guidance the model actually applies.

Why can instructions be followed inconsistently?

An instruction can be vague, outdated or in tension with another instruction. “Keep the change small” and “migrate every old component you encounter” lead to different work. Resolve the intended scope with a person rather than making both sentences more emphatic.

A second problem is weak evidence. The assistant may be told to test thoroughly without being told which outcome matters. State a concrete condition: the form retains its visible labels, the public response keeps its fields or the export preserves its column order. Then choose the actual project check that can assess that condition.

Anthropic’s verification guidance↗ (opens in a new tab) emphasizes observable checks. A useful review pairs the instruction with a representative task and a result a person can inspect. Keep a failed check visible; rewriting the summary to sound complete does not improve the underlying work.

When a task fails, record the sequence: what the instruction said, what the assistant read, what it did and which check exposed the problem. The troubleshooting guide helps diagnose loading and adherence separately. That evidence is a better basis for a correction than adding another paragraph of warnings.

Why is a written rule different from a permission?

A written rule asks the assistant to behave a certain way. A permission determines whether an operation is allowed through the configured tool or service. If your project says “do not deploy,” that is valuable guidance, but a dependable deployment boundary also depends on credentials and access controls.

Claude Code documents its tool controls separately in the permissions guide↗ (opens in a new tab). Keep that separation when reviewing a setup. Asking an assistant to describe a restriction is not a test that the service enforces it, and testing a restriction should not require attempting an unauthorized live change.

What work context should live outside the file?

Keep changing progress outside the standing instructions: the bug being investigated, the test that failed, the open question and the next step. A sentence saying “the migration is unfinished” can become false tomorrow. A lasting instruction should explain how to handle such work, while the task record says where this particular migration stands.

Keep proposals distinct from agreements too. A person may decide to retain an old interface because another product depends on it. The file can carry the resulting constraint, but the shared record should retain who chose it and why. Decisions and context in fenbs let another connected assistant recover that explanation without relying on a private conversation.

How to do this with fenbs

1. Create a free account and add one active project.
2. Add its current tasks and the next action, with uncertainty stated plainly.
3. Record the choices a person approved in Decisions and rules; keep proposals open until a person decides.
4. Ask the connected assistant to read context at the start and save task progress and Where we left off before stopping.

fenbs supplies a shared work record; it does not replace Claude Code’s instruction loading, permissions or your review. If your only need is a stable local command list, a repository file may be enough. The AI prompts hub covers related instruction workflows when the project needs more structure.