CLAUDE.md vs Rules: Organizing Project Instructions

Use CLAUDE.md for instructions that apply throughout a project, and scoped rule files for guidance that matters only to certain work. Neither format resolves contradictory human decisions for you. Tools like fenbs keep the approved decisions behind those instructions available to the team and its connected assistants.

The useful comparison is about scope and maintenance. A single file is easy to find and review. Separate rules can make a large repository easier to work in, provided each rule has a clear purpose and you avoid maintaining several versions of the same requirement.

What is the practical difference between the two?

Claude Code supports Markdown rules in .claude/rules/; a paths field can limit a rule to matching files. Rules without that field load unconditionally. The official instruction documentation↗ (opens in a new tab) describes the supported syntax. Separating a document does not by itself make its content conditional.

Treat the table as an editing decision rather than a command to reorganize every repository. A small application may need only a few useful paragraphs. A repository with unrelated services may benefit from narrower guidance. The number of files is less important than whether a reviewer can explain why each instruction applies.

Which instructions should stay in the main file?

Keep the agreement that should survive a change of task: the package manager the repository uses, the commands people have verified, the broad architecture and the boundary around work that needs approval. Write enough explanation to make an unusual constraint understandable. Do not add a general programming textbook.

Say a studio maintains a website and an internal reporting service. The main file could explain that both use the same account service and that changing its public response requires review. The reporting service’s data export layout belongs closer to that work. Someone fixing a homepage typo should not have to reason through the export format.

• Keep shared constraints here when they affect several areas of the project.
• Name a command only after checking that it exists and identifying the folder where it runs.
• Explain an unusual boundary in one sentence so an assistant does not “clean it up” accidentally.
• Leave today’s unfinished task, temporary experiment and waiting approval with the work record.

The CLAUDE.md file guide covers the starting structure, while CLAUDE.md examples show complete documents; this comparison is about distributing instructions you already understand. When the reason is a human choice, Decisions and rules in fenbs give the team somewhere to preserve that reason alongside the current answer.

When does a separate rule earn its place?

A separate rule earns its place when its applicability can be stated clearly. “Only when editing public API responses” is useful. “Important stuff” is not. Pick a boundary that someone reviewing a change can recognize without asking the original author what they meant.

---
paths:
  - "src/api/**/*.ts"
---

# Public response changes

- Preserve existing response field names unless the task includes an approved contract change.
- Cover a changed response with the relevant contract test.
- Report any compatibility question before changing a public field.

The path pattern is an example, not a suggested directory for every application. Replace it with a path in your repository. Then inspect a matching file and an unrelated file to check that you understand the intended boundary. A rule that matches nothing provides a tidy document without useful guidance.

Do not use a separate rule merely to hide a long passage. First ask whether the passage can be deleted, shortened or linked as reference material. Splitting repeated text creates additional places to maintain. The best boundary often follows the team’s existing ownership of the code rather than a new taxonomy invented for the assistant.

How do you remove contradictory instructions?

Read all instructions that can affect the same task as one document. Look for verbs that disagree: always and never, require and skip, preserve and replace. Two individually reasonable sentences can conflict when one applies to every change and the other applies to a subset of those changes.

1. Write the situation in ordinary language: for example, changing a public response in the reporting service.
2. Collect the applicable instructions and quote the conflicting sentences for a person to review.
3. Identify whether the narrower instruction is an intentional exception or an outdated copy.
4. Ask the responsible person to choose when the agreement is unclear; do not let a generated rewrite settle policy.
5. Update the maintained instruction and remove the obsolete wording, then check the example situation again.

Avoid relying on a filename such as important.md to settle a disagreement. The name helps humans browse; it does not explain the intended exception. Write the boundary directly: “For documentation-only changes, run the content checker; application tests are required when application behavior changes.” Use your actual agreed checks.

Also watch for softer contradictions. “Follow nearby patterns” can disagree with “use the new component” when the nearby code predates that component. State how to handle older code, or the assistant must guess whether consistency means repeating the old approach or migrating everything it touches.

Can you reuse the same rules in other coding tools?

Reuse the agreement, but verify the receiving tool’s loading mechanism. Kiro’s steering documentation↗ (opens in a new tab) describes Markdown guidance in .kiro/steering/. Qwen Code’s memory documentation↗ (opens in a new tab) describes QWEN.md. Similar prose does not make filenames, scope settings or conditional loading interchangeable.

Separate portable meaning from tool-specific packaging. “Preserve public response fields until a contract change is approved” can be the same agreement across tools. A header that selects matching files needs verification in each tool. Copying the entire wrapper without checking it can silently change when the instruction applies.

A phrase such as YAGNI, meaning “you aren’t going to need it,” needs the same care. Translate it into the behavior the team wants: “Do not introduce an optional plugin system for this task; implement the approved export.” An unexplained slogan invites different interpretations even when every assistant reads exactly the same words.

For work split between repositories, the guide to Claude Code across multiple projects covers that separate setup problem. Start this comparison with one real task and one known agreement rather than trying to design a universal instruction format.

What should you verify after splitting the file?

Choose a harmless representative change. Ask the assistant to state the applicable constraints, identify the files it will touch and name the checks it plans to run. Review the answer against the agreement. Then inspect the actual change; correctly repeating a rule is useful evidence, but it does not prove the work follows it.

Keep enforcement separate from prose. Claude Code provides permission settings↗ (opens in a new tab) for controlling tool access. A sentence saying “never deploy” belongs in the instructions as useful guidance, but operational restrictions need configuration and appropriate access controls as well. Do not treat moving that sentence into a rule file as adding a security boundary.

If the expected instruction is missing, use the focused CLAUDE.md troubleshooting guide. Record what loaded and what the assistant actually did before making the rule longer. More words can obscure the original problem when the real cause is the wrong scope or an unresolved disagreement.

How to do this with fenbs

1. Create a free account and add the project whose instructions you are organizing.
2. Save the reusable review prompt in Skills and prompts: collect applicable instructions, identify contradictions and propose changes for review.
3. Record the choices a person approves in Decisions and rules, including their scope and reason.
4. Give the file cleanup a task, and ask your connected assistant to read project context before changing the relevant instructions.
5. Save the verification result and Where we left off so the next session knows which rules were checked and which questions remain open.

fenbs is useful when several sessions or assistants need the same explanation of a rule. It does not replace repository instruction loading or tool permission settings. If one short file is sufficient and you do not need a shared work record, maintaining that file may be all you need.

For other reusable instruction patterns, browse the AI prompts guides. Choose a structure you can review together: one clear shared agreement, narrower detail where it applies and a work record for what is changing.