Create Your First CLAUDE.md

What You’ll Build

A working CLAUDE.md file — the master governance document that tells AI agents who they are, what rules to follow, and how your project is structured. By the end, an AI agent dropped into your project cold can orient and begin useful work.

Prerequisites

• Understand the triad (what/how/who)
• Understand governance files (what they do and why)

Steps

Step 1: Create the File

At the root of your project, create a file called CLAUDE.md. This name matters — AI tools like Claude Code auto-load it on startup. It’s the first thing an agent reads.

touch CLAUDE.md

Step 2: Write the Identity Section

Start with who the agent is and what the project does:

# CLAUDE.md — My Project

## Identity

You are working on [project name] — [one sentence describing what it does].

### Operating Style

- [How should the agent communicate? Formal? Casual? Technical?]
- [Any persona traits? "Be concise." "Explain your reasoning."]

This section replaces the generic “I’m an AI assistant” behavior with project-specific identity. The agent becomes a team member, not a generic tool.

See it in action: Open this vault’s CLAUDE.md (at aDNA.aDNA/CLAUDE.md). The identity section defines the Rosetta persona — “named after the Rosetta Stone” — with specific operating style rules like “the structure IS the lesson” and “warm and precise, anti-jargon-first.”

Step 3: Write the Project Map

Add a directory structure overview so the agent knows where things are:

## Project Map

\```
my_project/
├── CLAUDE.md        # This file
├── what/            # Knowledge and reference material
│   ├── context/     # Agent context library
│   └── decisions/   # Architecture Decision Records
├── how/             # Operations and processes
│   ├── templates/   # Reusable file templates
│   └── sessions/    # Session tracking
└── who/             # People and governance
    └── governance/  # Policies and roles
\```

An agent reading this knows immediately what exists and where to find it. Without it, the agent guesses — and guesses wrong.

Step 4: Add Standing Rules

Define the rules that apply to every session:

## Standing Rules

1. **Read STATE.md before working.** Check current phase, blockers, and recent activity.
2. **Never modify shared configs without reading first.** Read-before-write prevents overwrites.
3. **Set `last_edited_by` on every edit.** Attribution enables conflict detection.
4. **Commit after significant changes.** Don't rely on auto-save.

Rules should be specific and actionable. “Be careful” is not a rule. “Read STATE.md before working” is.

Step 5: Define the Agent Protocol

Tell the agent what to do on startup:

## Agent Protocol

### Startup Checklist

1. Read CLAUDE.md (this file — auto-loaded)
2. Read STATE.md — understand current phase and blockers
3. Check `how/sessions/active/` — look for conflicting sessions
4. Create a session file and begin work

This is the convergence model in miniature: the agent starts broad (CLAUDE.md = everything about the project) and narrows to the specific (STATE.md → active session → current task).

Step 6: Validate It

Test your CLAUDE.md by answering these questions:

What You Learned

• CLAUDE.md is the single most important file in an aDNA project — it’s the agent’s first read
• Four sections do the heavy lifting: identity, project map, standing rules, agent protocol
• Specificity beats generality: “Read STATE.md first” > “Be careful”
• The file demonstrates convergence — broad orientation narrowing to specific action

Next Steps

• Apply the Question Test — practice sorting content into the triad
• Token Selection — how CLAUDE.md fits into the token budget