CLAUDE.md Best Practices: 10 Field-Tested Rules for Claude Cowork Teams

CLAUDE.md best practices are what separate a Claude Cowork deployment that ships careful, consistent work from one that silently corrupts your file tree. The difference between the two is not the model. It is whether the instruction file tells Claude what to do with the precision you would give a brand-new employee on their first day — one who knows nothing, needs to be taught everything, and operates only inside the guardrails you set.

Many CLAUDE.md files in the wild do not clear that bar. They are short. They are vague. They are written in the same tentative voice most people use in Slack messages. The agent reads them the way a new hire reads an employee handbook that says "try to be professional" — as suggestion, not specification.

This post is ten rules for writing a CLAUDE.md that holds up in production. Each rule is tied to a specific class of failure — lost versions, overwritten files, drifted naming, broken path matching, runaway agents. None of them require a code change or a new tool. They require the discipline to write instructions the way a specification is written rather than the way a wish is written.

The rules come from writing and rewriting CLAUDE.md files for real projects. The first draft is always too tentative. The third draft is closer. By the fifth or sixth pass, the agent starts producing output that looks like it came from a careful senior employee rather than a new hire on their first week.

01 Write Every Rule in Imperative Voice

The single highest-return edit you can make to a CLAUDE.md file is a search-and-replace on the word "should". An instruction file is not a polite request. It is a specification. Every rule reads as a direct command.

You should try to use the YYYY-MM-DD format
for dates where appropriate, as this is usually
the preferred approach.

Use YYYY-MM-DD for every date.

The first version gives the model three escape hatches — should try, where appropriate, and usually. The second gives zero. A large language model reads probabilistic hedges as permission to deviate. Imperative voice closes the permission.

The same rule applies to prohibitions. Replace "avoid" with "never." Replace "try not to" with "do not." Write one rule per line and keep each rule under fifteen words where possible.

When your CLAUDE.md reads as a command set — "Do X. Never Y. Use Z." — the agent treats it as a specification and follows it. When it reads as advice, the agent treats it as suggestion and improvises. Every paragraph of hedged prose is a paragraph of drift waiting to happen.

02 Front-Load Identity and Session Workflow

Position inside the file affects how consistently the agent follows a rule. Content at the top of a long file is applied more reliably than content buried in the middle. Anything that must apply to every response belongs in the first twenty lines.

Open the file with three short sections, in this exact order: identity, session workflow, and collaboration rules. Everything else — naming conventions, markdown style, tooling lists — goes below.

# [Company Name] — Global Instructions

## Identity
- Name: [Full name]
- Role: [Title]
- Company: [Company name]
- Website: [URL]

## Session workflow
- Start every session with /standup. No exceptions.
- End every session with /conclude.

## Collaboration rules
- Show the plan before executing any multi-step task.
- Never delete or overwrite a file without explicit confirmation.
- Ask a clarifying question if the task is ambiguous.

That block is under thirty lines. The agent now knows who it is working for, how to open and close a session, and what three behaviors are disallowed, before reading anything else in the file.

Put the nice-to-haves — tooling preferences, color palettes, voice guidance — below those three sections. Anything deep in the middle of a long file is the least reliable position for a rule.

03 Pick One Separator and Never Mix

Most CLAUDE.md files in the wild use both hyphens and underscores, often on the same line. When the instruction set is inconsistent, the output is inconsistent. Your workspace ends up with a mix of my-project-v1 and my_project_v2 and nobody can remember which folder was named which way.

Pick one separator — hyphen or underscore — and forbid the other across the entire file.

- Use hyphens or underscores to separate words.
- Good: my-project_v1, your_client-files

- Use hyphens to separate words. Never use underscores.
- Good: my-project-v1, your-client-files
- Bad:  my_project_v1, your_client_files

Why this matters practically: shell scripts, ripgrep patterns, and find commands treat hyphen and underscore as different characters. If your instruction file permits both, your automation breaks on the files the agent produces half the time, and you waste cycles debugging path matching instead of debugging real bugs.

The same principle applies to case. Pick lowercase and stay there. On Windows, MyProject and myproject are the same path with different display. On a case-sensitive macOS volume they are two different paths. Choose lowercase and never deviate.

04 Forbid Ambiguous Filenames by Name

Without an explicit ban, Claude will name things exactly the way overworked humans do — final, final_v2, FINAL_final, untitled, draft, new, test, and temp. Weeks later, nobody on the team can tell which version of the proposal was actually sent to the client.

Put the banned list in the file by name. Do not say "avoid ambiguous names" and trust the model to infer what ambiguous means. Enumerate them.

- Never use temporary or ambiguous names: file1, final, draft, new,
  test, temp, untitled.
- Version files with v1, v2, v1-1. Never use final, final-final, or FINAL.
- Include a YYYY-MM-DD date in the filename when the content is dated.

With that rule in place, acme-proposal-2026-04-23-v1.docx becomes the default output and final_FINAL_v2.docx becomes impossible.

The naming rule also saves you from one of the worst silent agent failures: the agent completes a task, saves the output with a generic name, and then overwrites the same filename on the next task. You lose the prior output with no version history. A named ban on final, draft, and temp, paired with an enforced v1/v2 versioning pattern, eliminates the failure class entirely.

05 Standardize on YYYY-MM-DD for Every Date

Dates are another common source of filename inconsistency. If you do not pick a format, Claude will generate all of them — April 23 2026, 4/23/2026, 23-Apr-2026, 20260423, and apr-23-26 in the same folder.

Specify ISO 8601 — YYYY-MM-DD — and use it for every file, folder, log entry, and timestamp.

- Use YYYY-MM-DD for every date in filenames, folders, and log entries.
- Use the [your timezone] timezone.

The format has two practical advantages beyond consistency. First, it sorts correctly when files are listed alphabetically — you get chronological order for free in every file browser. Second, it is unambiguous across locales. 4/5/2026 means April fifth in North America and May fourth in Europe. 2026-04-05 means one date everywhere on earth.

If your team works across time zones, pair the date rule with a single operating time zone. "Use the Toronto timezone (ET)" is three words and eliminates an entire category of "wait, when was this due" confusion. The agent will stamp every log, every version number, and every due date in the same frame.

06 Write Path Rules for Windows and Mac Explicitly

This is where cross-platform CLAUDE.md files go to die. Cowork mode runs on the Windows and Mac builds of the Claude desktop app, and paths work differently on each. If your instruction file does not specify which rules apply to which OS, the agent will guess — usually wrong, and sometimes in ways that silently break every path it touches.

Pick the OS you actually run on and state it at the top of the file. Then write path rules specific to that OS.

- Use backslashes in paths:
  C:\Users\[name]\project\file.md
- Never use reserved names:
  CON, PRN, AUX, NUL, COM1, LPT1.
- Never end a filename with a
  space or a period.
- Keep total path length
  under 260 characters.
- Never use reserved characters:
  < > : " / \ | ? *

- Use forward slashes:
  /Users/[name]/project/file.md
- Never use a colon in a filename.
  macOS translates : and / between
  display and on-disk storage for
  legacy reasons.
- Treat filenames as case-insensitive
  on default APFS volumes, but
  preserve the case you chose.
- Do not write to ~/Library without
  explicit confirmation.

A CLAUDE.md that treats path handling as a single universal rule will generate C:\Users/name/project\file.md on a Windows host — a mixed-separator path that works by accident on some tools and breaks on others. Be explicit about the OS you are on. If you switch between machines, maintain one CLAUDE.md per host rather than one file that tries to cover both.

07 Cap Folder Depth and Total Path Length

Without a cap, an agent will happily generate folder structures six levels deep and file paths three hundred characters long. On Windows, anything over 260 characters fails silently in half of your tools. Windows 10 and 11 support longer paths behind an opt-in flag, but many common tools — including Explorer, older PowerShell scripts, and most .NET utilities — have not adopted it consistently. Treat 260 as the safe default. On every OS, deep nesting makes files effectively unfindable for humans.

Set two hard limits in the instruction file:

- Never create folder paths deeper than five levels.
- Keep the total path length under 260 characters.
- Keep filenames under 60 characters.

Five levels is enough for every real project. Project → year → phase → deliverable → version covers more use cases than you think.

Sixty characters is a surprisingly forgiving filename budget once dates, version numbers, and company names are accounted for. acme-proposal-2026-04-23-v1.docx is thirty-two characters and tells you everything you need to know.

The folder-depth rule has an unintuitive secondary benefit — it forces collapse of unnecessary hierarchy. Agents prompted with "never go deeper than five levels" will reorganize messy structures into cleaner ones on their own. Without the cap, every agent session tends to add one more nested folder as a safety measure, and your workspace silently grows into an archaeological dig of good intentions.

08 Include Good and Bad Examples for Anything Ambiguous

Models do not learn from abstract rules as reliably as they learn from paired examples. For any rule where the wrong interpretation is plausible, write one Good example and one Bad example directly below the rule.

- Use short, descriptive folder names.

- Use short, descriptive folder names.
  - Good: client-files, shopify-theme, q2-proposals
  - Bad:  Files (1), client files (final), MY STUFF

The paired format does three things the rule alone cannot. It disambiguates the intent — "short" and "descriptive" are both subjective until the model sees the pattern. It shows the specific wrong answers you are worried about — spaces, parentheses, capitalization, the word "final". And it gives the model a template to pattern-match against when it generates its next folder name.

Reserve paired examples for rules that are easy to misread. For rules that are already unambiguous — "use lowercase only" — a bare imperative is enough. Over-examplifying wastes tokens on self-evident instructions and buries the examples that actually matter.

If you had to pick one section of your CLAUDE.md to include Good and Bad examples, pick the naming rules. That is where the model's default behavior is most likely to drift, and where drift is most visible.

09 Ban Vague Qualifiers

Scan every draft of your CLAUDE.md for these words and remove them: some, usually, often, rarely, when appropriate, as needed, try to, consider, probably, might. Every one of them is a loophole.

"Use short filenames where appropriate" translates, in model terms, to "use short filenames when you, the model, feel like it." That is not a rule. That is an opinion.

- Try to use imperative voice when writing rules.
- Consider capping folder depth as needed.
- Usually apply YYYY-MM-DD to dated files.

- Use imperative voice when writing rules.
- Cap folder depth at five levels.
- Use YYYY-MM-DD for every dated file.

The fix is almost always to replace the vague qualifier with an exact value or delete it. If a rule really does depend on context, write the context explicitly — "for filenames containing a date, use YYYY-MM-DD" — rather than leaning on "where appropriate."

The same rule applies to your banned-words list. Do not tell the agent to "avoid overused corporate jargon." Enumerate the banned words. Ten specific prohibited terms outperform a hundred words of style guidance every time. Precision is not pedantry. Precision is the difference between an instruction file and a vibe.

10 Gate Destructive Actions Behind Explicit Confirmation

An agent with write access and no gates is a slow-motion outage. The single cheapest insurance policy you can add to CLAUDE.md is one line near the top of the collaboration rules:

- Never delete or overwrite a file without explicit confirmation.

Pair it with one more rule for bulk operations:

- Flag a task before starting if it will trigger more than 20 tool calls,
  touch more than 50 files, or require more than 3 external research sources.

Those two lines turn every destructive operation into a confirmation step. The agent stops before deleting. The agent stops before overwriting. The agent flags a fifty-file rename before it runs, so you have a chance to approve or redirect it.

In production, the gating rule is what separates "the agent made a mistake and we fixed it in two minutes" from "the agent made a mistake and we spent two days restoring from backup." The delta is one sentence of text.

The same pattern applies to anything irreversible — sending emails, submitting forms, deleting database rows, pushing to a remote branch. If an action cannot be undone, the agent must confirm before taking it. State the rule by name in the file. Do not trust the model to infer irreversibility. One line of CLAUDE.md is cheaper than one incident postmortem.

★ The Takeaway

A CLAUDE.md file is the single artifact that determines whether Claude Cowork behaves like a careful professional or an expensive liability. Many files in the wild are short, vague, and written in the same tentative voice most people use in Slack messages. That is why Cowork deployments so often ship unreliable output.

The ten rules above are not theoretical. Each one is tied to a specific class of failure — lost versions, overwritten files, drifted naming, broken path matching, runaway agents. None of them require a code change or a new tool. They require the discipline to write instructions the way a specification is written rather than the way a wish is written.

If you are standing up Claude Cowork for your team, write the file first and the skills second. If you already have Cowork deployed, audit the CLAUDE.md before shipping another agent workflow. The file is cheap. The incidents are not.