Your CLAUDE.md file is your agent's constitution — most people write it like a README

Every agent needs a foundational context file. Call it CLAUDE.md, AGENTS.md, or SYSTEM.md — the name doesn't matter. What matters is that most people treat it like documentation when it should be treated like a constitution.

Your agent reads this file first, every session. It sets the tone, establishes boundaries, and defines how your agent thinks about its role. Get it wrong, and your agent will be confused, verbose, and unreliable. Get it right, and everything else falls into place.

Here's what doesn't work: a wall of text explaining what the agent can do.

# CLAUDE.md
You are an AI assistant that helps with coding tasks.
You can write code, debug issues, and explain concepts.
You should be helpful and thorough in your responses.
Always ask clarifying questions when needed.

This tells your agent nothing useful. It's generic, wordy, and gives no guidance on how to behave in specific situations.

Here's what works: a constitution that defines identity, boundaries, and decision-making patterns.

# CLAUDE.md

## Identity
You are Forge, a staff engineer focused on shipping production-ready code.

## Core Principles
- Fix first, explain after
- Working code > perfect code
- One clear action per response
- No "I can help you with that" — just do it

## Boundaries
- Never modify production databases directly
- Always run tests before suggesting deployment
- Stop and ask if a task will take >30 minutes

## Communication Style
- Lead with the action you're taking
- Show code, don't describe it
- End with next steps, not summaries

Notice the difference? The second version gives your agent a personality (Forge), clear decision-making rules (fix first), and specific behavioral boundaries (stop at 30 minutes).

The constitutional pattern: Identity + Principles + Boundaries + Style. Four sections that turn a generic AI into a reliable operator.

The identity section is crucial but often skipped. Your agent needs to know who it is before it can know how to act. "You are Claude" is useless. "You are Sarah, a senior product manager who ships fast and measures everything" gives your agent a north star.

Principles should be action-oriented, not aspirational. "Be helpful" is aspirational. "Fix first, explain after" is actionable. Your agent will face dozens of micro-decisions every session — principles help it choose consistently.

Boundaries prevent disasters. Not just "don't delete files" but operational boundaries: "Stop and ask if you need more than 3 API calls" or "Never commit code without running the test suite first." These aren't restrictions — they're guardrails that let your agent operate with more autonomy.

Communication style might seem cosmetic, but it's not. "Show code, don't describe it" prevents your agent from writing paragraphs about what it's going to do instead of just doing it. "End with next steps" keeps momentum going.

Your CLAUDE.md file should be under 200 words and readable in 30 seconds. If your agent needs to parse a novel to understand its role, you've already lost. Constitutional thinking, not comprehensive documentation.

The best CLAUDE.md files I've seen feel like personality profiles, not technical specs. They answer: Who is this agent? How does it make decisions? What would it never do? How does it communicate?

This isn't just about coding agents. Every agent type needs constitutional thinking — whether it's managing your calendar, writing content, or handling customer support. The pattern scales.

If you're running production agents without this foundation, you're building on sand. Start with the constitution, then add the features.