If you're building with Claude — whether using the API, Claude Code, or an agent framework — you've probably seen references to a file called CLAUDE.md. This guide explains what it is, why it matters, and how to write one that actually improves your agent's behavior.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude reads automatically in certain contexts to understand how it should behave. Think of it as a persistent system prompt that lives in your project, not in your API call.

In Claude Code, if you put a CLAUDE.md in your project root, Claude reads it every session. In agent frameworks like WireClaw, it defines the agent's identity, capabilities, and rules of behavior.

The name is specific to Anthropic's tooling — other AI systems have equivalent files (GitHub Copilot uses .github/copilot-instructions.md, for example).

Why CLAUDE.md Matters

Without a CLAUDE.md, Claude falls back to generic helpful-assistant mode. It doesn't know:

A good CLAUDE.md makes the difference between an agent that wanders off and one that stays on task.

The 7 Things a Good CLAUDE.md Needs

After scoring hundreds of CLAUDE.md files with our CLAUDE.md Auditor, here's what separates high-scoring files from low ones:

1. Agent Identity

Start with who the agent is. Not just a name — a clear statement of its purpose and context.

Weak:


You are a helpful assistant.

Strong:


You are Aria (aria@company.com), a customer support agent for Acme Software. 
You help users troubleshoot billing issues, account access, and product questions. 
You have read-only access to the support ticket database.

The strong version tells Claude: who it is, what it does, and what it has access to.

2. Capabilities Section

List what the agent can and cannot do. This prevents Claude from hallucinating capabilities it doesn't have and reminds it to use the ones it does.


## What You Can Do
- Search the support ticket database
- Read user account information
- Escalate tickets to human agents
- Send templated email replies

## What You Cannot Do
- Modify billing information directly
- Access payment details
- Make promises about refunds without manager approval

3. Communication Protocol

How should the agent respond? Channel matters here.


## Communication
- Reply in the same channel you were addressed in
- Keep responses under 200 words unless the user asks for detail
- Always include a ticket reference number when discussing specific issues
- Sign messages as "Aria (Acme Support)"

4. Memory Rules

What should the agent remember and where should it store things?


## Memory
- Save user preferences to /workspace/preferences/{user_id}.md
- Keep a log of unresolved issues in /workspace/open-tickets.md
- Never store payment information, even temporarily

5. Task Approach

How should the agent handle typical tasks? Give it a default workflow.


## Task Approach
1. Identify the issue category (billing, access, product)
2. Check the knowledge base before answering
3. If you can't resolve: acknowledge, escalate, set expectation
4. Always confirm resolution before closing

6. Iron Laws

These are non-negotiable constraints. Claude takes these seriously when clearly labeled.


## Iron Laws
- NEVER share another user's account information with a different user
- NEVER make commitments about features not yet released
- ALWAYS escalate security-related issues to the security team immediately
- NEVER end a conversation without confirming the user's issue was addressed

7. Examples

A few worked examples dramatically improve behavior consistency.


## Examples

**User asks about a refund:**
Don't: "I can process that refund for you right now."
Do: "I can submit a refund request, which goes to our billing team for approval within 1-2 business days. Want me to submit one now?"

Common Mistakes

Too vague. "Be helpful and professional" isn't an iron law — it's a suggestion. Claude already tries to be that. Write constraints that change behavior.

No tools listed. If your agent has tool access (search, code execution, file system), document it. Claude won't reliably use tools it doesn't know it has.

No memory rules. Without explicit memory guidance, Claude may store information inconsistently or not at all.

All rules, no identity. An agent needs to know what it is before it knows what it should do.

Check Your CLAUDE.md Score

The CLAUDE.md Auditor scores your file across all 7 dimensions and gives you specific improvement suggestions. Paste your file and see where you stand — a score of 70+ usually means solid behavior; below 50 means critical pieces are missing.

Building Agent Skills

If you're building Claude agents, you may also need SKILL.md files — structured definitions of specific capabilities your agent can invoke. The SKILL.md Generator can create them from a plain description.

---

*helloandy.net provides free tools for AI agent developers and AI writers. No account required.*